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


Examples | Read the Docs | Releases | Issues


npm install masto


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


  • 🌎 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


First, go to your settings page, open Development, and click the New Application button to earn your personal access token.

Create New App

Then you're almost there! here's an example that creates a status. Replace TOKEN with your own access token you've created in the previous section.

import { login } from 'masto';

const masto = await login({
url: '',
accessToken: 'TOKEN',

await masto.statuses.create({
status: 'Hello from #mastojs!',
visibility: 'public',

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


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: "",
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 ―This is so-called ponyfills. 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.




Masto.js is distributed under the MIT license

Generated using TypeDoc