masto

Universal Mastodon API client for JavaScript

Q&A | Examples | Read the Docs | Releases

Features

• 🌎 Universal: Works in Node.js, browsers, and Deno
• 📦 Lightweight: Less runtime codes, 6kB+ minified and gzipped
• 📚 TypeScript: Written in TypeScript, and provides type definitions
• 🧪 Tested: 100% test coverage using a real Mastodon server
• 🤓 Maintained: Actively maintained by a Fediverse lover since 2018

Migration Guides

• Migrate from v5 to v6
• Migrate from v4 to v5

Who's using Masto.js?

• Elk - A nimble Mastodon web client
• Phanpy - A minimalistic opinionated Mastodon web client
• ...and a lot more!

Quick Start

In this quick start, we'll look at how to create a simple Mastodon bot that publishes a post using Masto.js.

First, you must install Node.js and npm in your environment. Follow the npm official guide for the setup, and proceed to the next step. Alternatively, you can use yarn, pnpm, or other package managers to install Masto.js.

The minimal required version of dependencies is as follows:

• Node.js: >= 18.x
• npm: >= 9.x
• TypeScript (optional peer dependency): >= 5.0.0

If you successfully installed Node.js and npm, create your first Masto.js project with the following command. Assume you're using a POSIX-compatible operating system.

Create a directory and initialise your project.

npm init --yes
npm pkg set type=module

Make sure a package.json file is created in your project directory. Then install Masto.js using npm

npm install masto

Now you successfully initialised your project for developing a Mastodon bot. Next, you need to create an application to obtain an access token required to access your account.

Go to your settings page, open Development, and click the New Application button to obtain your personal access token.

You need to fill out Application name, but rest of the fields can be left as defaults. What you need to select for Scopes is depending on your bot's ability, but you can access most of the functionality by granting read and write. See OAuth Scopes documentation for further information.

Once you have created an application, save Your access token securely. This string is required to access your account through Masto.js.

Then you're almost there! Create a file named index.js inside your project directory and add the following code. This is an example which will post a status from your account.

import { createRestAPIClient } from "masto";

const masto = createRestAPIClient({
  url: process.env.URL,
  accessToken: process.env.TOKEN,
});

const status = await masto.v1.statuses.create({
  status: "Hello from #mastojs!",
});

console.log(status.url);

Finally, run the program with the following command. Replace {URL} with your instance's URL such as https://mastodon.social, and {TOKEN} to your access token that you obtained in the previous section.

URL={URL} TOKEN={TOKEN} node ./index.js

You can learn about other available features in the documentation. You may also want to refer examples to see more examples. Of course, you can ask questions in the Discussions if you have any.

Enjoy your Mastodon development with Masto.js!

Contribution

See CONTRIBUTING.md

License

Masto.js is distributed under the MIT license

Changelog

6.10.0 (2024-10-21)

Features

• Support new accounts field in PreviewCard of status introduced by Mastodon 4.3.0 (96a84f2)

Bug Fixes

• Fix duplicated WebSocket connection created when acquiring connection before one established (dbfd4c8)
• Fix WebSocket client to maintain subscription even if other subscription with same parameter ends (e6d6bd0)
• Unsubscribe from WebSocket stream when iterator ended (b7732ed)