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: 99% test coverage using a real Mastodon server
• 🤓 Maintained: Actively maintained by a Fediverse lover since 2018

Migration Guides

• v5.x → v6.0.0
• v4.x → v5.0.0

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 when it's ready. Alternatively, you can use yarn, pnpm or other package managers to install Masto.js, but this guide below uses npm.

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 could successfully install 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.

mkdir my-bot
cd my-bot
npm init es6 --yes

And 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 earn your personal access token.

You need to fill out Application name, but the website and redirect URI are fine to be the default for now. 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.

If you could create 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!",
  visibility: "public",
});

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

Other available features are described in the documentation. You may also want to refer /examples directory on this repository.

Contribution

See CONTRIBUTING.md

License

Masto.js is distributed under the MIT license

Changelog

6.7.7 (2024-05-03)

Bug Fixes

• Eliminate direct imports from ws (37049df)
• Refactor FormData, querystring and websocket utils (1052740)
• Refactor WebSocketSubscription and remove unused code (6870df2)