Logo showing a cloud presented as a tree

madata

Make any cloud service with an API your backend!

Make any cloud service your backend

What is Madata?

Ever noticed how it's relatively easy to build a client-side JS app, but once you need to persist data remotely, things get complicated? Madata bridges that gap, by providing a unified API for authentication, reading & storing data, as well as file uploads, for a number of supported cloud services. Using Madata, you can develop apps with user accounts and remote storage and host them anywhere that supports hosting static assets. And what's better, it’s completely free and open source! Madata is an evolution of the storage component of our language Mavo, as we got many requests from developers who wanted to use it without the rest of Mavo.

Madata works in the browser, as well as in NodeJS. In Node, it requires version 18.7 or higher.

Here be dragons Madata has not yet been officially released, we are trying a “soft launch” first. It is currently in pre-alpha and very much a work in progress. Its API may change. It may have bugs. Please try it out, and open issues as you find them! Pull requests are welcome too :)

Getting Started

While you can install Madata via npm, you can also just use it directly from the CDN (provided by Netlify):

// Import Madata and all supported backends
import Backend from "https://madata.dev/src/index.js";

You then create a Backend object by passing a URL to Backend.from():

let backend = Backend.from("https://github.com/leaverou/repo/data.json");

You can now call methods like…

These methods are identical for all backends that support them. This means you can swap one backend for another without having to change your code, just by changing a URL!

Here is a full example that provides a very bare-bones authentication UI, reads an object from a JSON file on GitHub, provides UI for editing the data, and saves back.

This example uses inline event handlers and global variables to keep the code short, don’t do that in production. :)

<span id=myUsername></span>
<button id=loginButton onclick="backend.login()">Login</button>
<button id=logoutButton onclick="backend.logout()" hidden>Logout</button>

Value: <input id="valueInput" oninput="json.value = this.value">
<button id=saveButton onclick="backend.store(json)">Save</button>

<script type=module>
import Backend from "https://madata.dev/src/index.js";

globalThis.backend = Backend.from("https://github.com/leaverou/repo/data.json");

backend.addEventListener("mv-login", evt => {
	loginButton.hidden = true;
	myUsername.textContent = backend.user.username;
});

backend.addEventListener("mv-logout", evt => {
	logoutButton.hidden = true;
	myUsername.textContent = "";
});

globalThis.json = (await backend.load()) ?? {value: 0};
valueInput.value = json.value;
</script>

Backends are at the core of Madata. They are the adapters to the different services and data sources supported by Madata. You can read about how to use them in the docs.

Supported backends

Service Auth? Writes? Uploads?
GitHub Files GitHub
GitHub Gist GitHub
GitHub API GitHub
GitHub Labels GitHub
Dropbox
Firebase
Google Drive Google
Google Sheets Google
Google Calendar Google
Local storage
HTML Element
Basic remote fetching

Supported backends

Visit the backends page for the full list.

Authentication

Read more about authentication

Storage

Save:

let fileInfo = await backend.store(json);

Uploads

For backends that support uploads, this is how simple it could be to create an image uploader:

<input type=file id=uploader>
uploadForm.addEventListener("submit", evt => {
	evt.preventDefault();

	let file = uploader.files[0];

	if (file && file.type.startsWith("image/")) {
		backend.upload(file, `images/${file.name}`);
	}
});

You can check if backend.upload is defined to see if the backend supports image uploads.