neet / masto.js

Mastodon API client for JavaScript, TypeScript, Node.js, browsers

Examples | Read the Docs | Releases | Issues

Migration Guide From v4

Features

• 🌎 Isomorphic which means browsers and Node.js are both supported
• 🌊 Fetch API is supported natively
• ⌨️ TypeScript powers static typing. And of course there's no any!
• 💪 You don't need to type URLs because each endpoints have their own function
• 📄 Detailed docs and rich hovering menu for IDE, provided by TSDoc

Quick start

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

Firstly, you need to 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 dependency is as follows

• Node.js: >= 14.x
• npm: >= 6.x
• TypeScript (optional peer dependency): >= 3.6.0

If you could successfully installed Node.js and npm, create your first Masto.js project with the following command. Assume you're using 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 could initialise your project for developing a Mastodon bot. Next, you need to create an application to obtain an access token required to get access to 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 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 to most of 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 to 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 { login } from 'masto';

const masto = await login({
  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} to 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.

FAQ

Q. I want to use in Mastodon-compatible servers

Masto.js validates your Mastodon instance's version to provide more helpful error messages, but this may lead to not working with some Mastodon-compatible software. Therefore, we are offering a way to disable this feature.

await login({
  url: "https://example.com",
  accessToken: "...",
+ disableVersionCheck: true
});

Q. Do I need polyfills?

Masto.js uses fetch and other Web APIs which may not be supported in specific environments such as the legacy version of Node.js, but we also automatically switch to another module that provides the same functionality. For example, if we detected fetch API is not available, we switch to node-fetch module. Therefore, you don't need to be aware of polyfill / ponyfill in most cases, but you will need to install them manually in some cases.

• Node.js < 18: We use node-fetch, abort-controller, and form-data as ponyfill. You don't need to install polyfills. However, if you have installed polyfills of these APIs in global, Masto.js chose them as a priority.
• Node.js >= 18: We use native fetch API. You don't need to install polyfills.
• Browsers: We don't include any ponyfill or polyfill in the bundle. You need to manually install abort-controller, fetch, and form-data to support legacy browsers.

Contribution

See CONTRIBUTING.md

License

Masto.js is distributed under the MIT license