Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/neet/masto.js
🐘 Universal Mastodon API client for JavaScript
https://github.com/neet/masto.js
fediverse mastodon mastodon-api
Last synced: 9 days ago
JSON representation
🐘 Universal Mastodon API client for JavaScript
- Host: GitHub
- URL: https://github.com/neet/masto.js
- Owner: neet
- License: mit
- Created: 2018-04-13T07:27:40.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2024-10-23T14:32:05.000Z (18 days ago)
- Last Synced: 2024-10-29T17:34:59.627Z (11 days ago)
- Topics: fediverse, mastodon, mastodon-api
- Language: TypeScript
- Homepage: https://neet.github.io/masto.js/
- Size: 10.7 MB
- Stars: 736
- Watchers: 4
- Forks: 51
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
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](https://bundlephobia.com/package/masto)
- 📚 **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](https://github.com/neet/masto.js/releases/tag/1.0.0)
## Migration Guides
- [Migrate from v5 to v6](https://github.com/neet/masto.js/releases/tag/v6.0.0)
- [Migrate from v4 to v5](https://github.com/neet/masto.js/releases/tag/v5.0.0)
## Who's using Masto.js?
- [Elk](https://github.com/elk-zone/elk) - A nimble Mastodon web client
- [Phanpy](https://github.com/cheeaun/phanpy) - A minimalistic opinionated Mastodon web client
- [...and a lot more!](https://github.com/neet/masto.js/network/dependents)
## 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](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) 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.
```sh
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](https://docs.joinmastodon.org/client/authorized/)_ 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](https://docs.joinmastodon.org/api/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.
```ts
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](https://neet.github.io/masto.js). You may also want to refer [examples](https://github.com/neet/masto.js/tree/main/examples) to see more examples. Of course, you can ask questions in the [Discussions](https://github.com/neet/masto.js/discussions) if you have any.
Enjoy your Mastodon development with Masto.js!
## Contribution
See [CONTRIBUTING.md](CONTRIBUTING.md)
## License
Masto.js is distributed under [the MIT license](https://opensource.org/licenses/MIT)