madata

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.

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…

• backend.load() to read data
• backend.login() to authenticate the user
• backend.logout() to log the user out
• backend.store() to store data
• backend.upload() to upload files

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.

<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

Authentication

• backend.login() shows authentication UI
• backend.login({passive: true}) tries to authenticate the user silently (i.e. if they are already logged in) It is called automatically when you call backend.load() or backend.store().
• backend.logout() logs the user out
• mv-login and mv-logout events are fired on the Backend object when the user logs in or out

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.