{"id":15105686,"url":"https://github.com/rhysd/mstdn","last_synced_at":"2025-09-27T05:30:50.833Z","repository":{"id":57304529,"uuid":"88333367","full_name":"rhysd/Mstdn","owner":"rhysd","description":"Tiny web-based mastodon client for your desktop","archived":true,"fork":false,"pushed_at":"2018-12-25T03:57:26.000Z","size":567,"stargazers_count":388,"open_issues_count":28,"forks_count":15,"subscribers_count":23,"default_branch":"master","last_synced_at":"2024-05-23T04:54:41.178Z","etag":null,"topics":["desktop","desktop-application","electron","mastodon"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rhysd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-04-15T08:06:59.000Z","updated_at":"2024-03-27T15:09:02.000Z","dependencies_parsed_at":"2022-08-27T02:57:43.627Z","dependency_job_id":null,"html_url":"https://github.com/rhysd/Mstdn","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhysd%2FMstdn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhysd%2FMstdn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhysd%2FMstdn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhysd%2FMstdn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rhysd","download_url":"https://codeload.github.com/rhysd/Mstdn/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219871882,"owners_count":16554465,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["desktop","desktop-application","electron","mastodon"],"created_at":"2024-09-25T20:42:11.048Z","updated_at":"2025-09-27T05:30:45.322Z","avatar_url":"https://github.com/rhysd.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"Web-based Desktop Client for [Mastodon][]\n=========================================\n[![npm version][npm version badge]][npm]\n\nMstdn is a desktop application based on the mobile version of the Mastodon page\nand the [Electron][] framework. It basically uses Mastodon's mobile page and\nprovides various desktop application features (such as desktop notifications,\nkeybindings, and multi-account support).\n\n\u003cimg src=\"https://github.com/rhysd/ss/blob/master/Mstdn/main.png?raw=true\" width=\"484\" alt=\"screen shot\"/\u003e\n\nFeatures:\n\n- [x] Small window on your menubar (or isolated normal window)\n- [x] Desktop notification\n- [x] Customizable (and pluggable) shortcut keybinds\n- [x] Multi-account (switching among accounts)\n- [x] User CSS\n- [x] Plugin architecture based on Node.js and Electron APIs\n\nMastodon is an open source project. So if you want to make a new UI, you can\njust fork the project, implement your favorite UI and host it on your place.\nThen you can participate Mastodon networks from it.\n\nHowever, Mastodon is a web application. So we can't use it outside of a browser.\nThis small tool provides the ability to use the Mastodon page in a desktop\napplication window outside of a browser.\n\n## Installation\n\n### Via [npm][]\n\n```\n$ npm install -g mstdn\n```\n\n### Via [yarn][]\n\n```\n$ yarn global add mstdn --prefix /usr/local\n```\n\n### As an isolated app\n\nDownload a package archive from the [Release page][], put the unarchived app\ninto the proper place, and open it.\n\n### Arch Linux ([AUR][])\n\nInstall the `mstdn` package from the AUR.\n\n## Usage\n\nIf you installed this app via npm or yarn, the following command is available to\nstart app:\n\n```\n$ open-mstdn-app\n```\n\nAt first, a dialog which recommends that you create a config is shown and JSON\nconfig file will be opened in your editor. You need to fill in the `\"name\"` and\n`\"host\"` keys in first element of `\"accounts\"`. Please see the `accounts`\nsection below for more information about how to configure the option.\n\nThen please try to start app again. Usage is the same as web client on mobile\ndevices. Some shortcuts are available by default (please see the 'Customization'\nsection below).\n\nSupported platforms are macOS (confirmed with 10.12), Linux (confirmed on Arch\nLinux kernel version 4.11) and Windows (confirmed with Windows 8.1).\n\nThere are two window modes in this app: 'menubar mode' and 'normal window mode'.\nYou can switch them with `\"normal_window\"` option (please see below\n'Customization' section for how to configure it).\n\n- **menubar mode**: Window is attached to the menubar. You can toggle the window\n  by clicking the menubar icon or typing the hot key. The advantage of this mode\n  is that the app does not fill any workspaces. You can see your timeline on\n  demand anytime. Like as menus in menubar on macOS, menubar window is automatically\n  hidden when it loses its focus. This mode is the default on macOS and Linux.\n- **normal window mode**: App starts with a normal window like a separated\n  browser window. You can put/resize window wherever you would like in your\n  workspace.\n\nIn both modes, the app remembers the size and location of its window. So you\nneed to specify window size (or location in normal window mode) only once.\n\nAfter starting the app, you would see the login page of your instance. Some\ninstances allow to login with other web services. However, Mstdn.app cannot\nfully support it. If you encounter problems with a customized login feature,\nplease try to login with normal flow instead.\n\n## Customization\n\nMstdn can be customized using the JSON config file at `{app dir}/config.json`\n\nThe `{app dir}` is:\n\n- `~/Library/Application\\ Support/Mstdn` for macOS\n- `~/.config/Mstdn` for Linux\n- `%APPDATA%\\Mstdn` for Windows.\n\nThe JSON file can contain the following key-values:\n\n### `hot_key`\n\n`hot_key` is a key sequence to toggle application window. The shortcut key is\ndefined globally.  The format is an [Electron's\naccelerator](https://github.com/electron/electron/blob/master/docs/api/accelerator.md).\nPlease see the document to know how to configure this value. Default value is\n`\"CmdOrCtrl+Shift+Enter\"`. If you want to disable, please set this value to an\nempty string or `null`.\n\n### `icon_color`\n\nThe color of icon in menubar. `\"black\"` or `\"white\"` can be specified.\n\n### `always_on_top`\n\nWhen this value is set to `true`, the window won't be hidden if it loses a\nfocus. Default value is `false`.\n\n### `normal_window`\n\nWhen this value is set to `true`, application will be launched as a normal\nwindow application.  If the menu bar behavior does not work for you, please set\nthis value to `true` to avoid it.  Default value is `false` on macOS or Linux,\n`true` on Windows because window position is broken in some versions of Windows.\n\n### `hide_menu`\n\nWhen this value is set to `true`, the application will be launched with the\nmenubar hidden, assuming `normal_window` is also true. When set to `false`, the\nmenubar will be visible on launch. Default value is `false`.\n\nOn Windows, typing Alt key shows the hidden menubar.\n\n### `zoom_factor`\n\nFont zoom factor in application. It should be positive number. For example,\n`0.7` means `70%` font zooming. Default font size is a bit bigger because the UI\nis originally for mobile devices. So default value is `0.9`.\n\n### `accounts`\n\nArray of your accounts. Each element should have `\"name\"`, `\"host\"` and\n`\"default_page\"` keys.\n\n- `\"name\"` represents your screen name. If your name is `@foo` then please\n  specify `\"foo\"` for it.\n\n- `\"host\"` represents a host part of URL of your mastodon instance. If you\n  belong to `https://mastodon.social`, please specify `mastodon.social`.\n  `https://` is not necessary.\n\n- `\"default_page\"` is a path of the first shown page on app start. If\n  `/web/notifications` is specified, `https://{your host}/web/notifications`\n  will be opened when the app starts.\n\nYou need to write up this config at first.\n\n### `chromium_sandbox`\n\nIf `true` is specified, Chromium's native sandbox is enabled (and default value\nis `true`).  Sandbox provides some OS level security protection such as resource\naccess control like tabs in Chromium. However, sandbox also blocks plugins for\nElectron application.\n\nIf `false` is specified, you can use some advanced features (user CSS and key\nshortcut plugin).  Before setting `false` to this value, please read and\nunderstand [sandbox documentation in Electron repo][sandbox doc] to know what\nyou're doing.\n\nPlease note that this sandbox feature is different from Node.js integration in\nElectron. Node.js integration is always disabled.\n\n### `keymaps`\n\nObject whose key is a key sequence and whose value is an action name.\n\n| Action Name       | Description                     | Default Key |\n|-------------------|---------------------------------|-------------|\n| `scroll-down`     | Scroll down window              | `j`         |\n| `scroll-up`       | Scroll up window                | `k`         |\n| `scroll-top`      | Scroll up to top of window      | `i`         |\n| `scroll-bottom`   | Scroll down to bottom of window | `m`         |\n| `next-account`    | Switch to next account          | N/A         |\n| `prev-account`    | Switch to previous account      | N/A         |\n| `open-in-browser` | Open current page in browser    | N/A         |\n\nIf an action name starts with `/`, it will navigate to the path. For example,\nif you set `\"/web/timelines/home\"` to some key shortcut and you input the key,\nbrowser will navigate page to `https://{your host}/web/timelines/home`.\n\nBelow is a default path actions. They are corresponding the position of tab\nitems.\n\n| Path                          | Description                       | Default Key |\n|-------------------------------|-----------------------------------|-------------|\n| `/web/statuses/new`           | Move to 'make a new toot' page    | `1`         |\n| `/web/timelines/home`         | Move to 'home timeline' page      | `2`         |\n| `/web/notifications`          | Move to 'notifications' page      | `3`         |\n| `/web/timelines/public/local` | Move to 'local timeline' page     | `4`         |\n| `/web/timelines/public`       | Move to 'federated timeline' page | `5`         |\n| `/web/getting-started`        | Move to 'getting started' page    | `6`         |\n\nIf an action name ends with `.js`, it will run key shortcut plugin (please see\nbelow 'Key Shortcut Plugin' section). This plugin feature requires\n`\"chromium_sandbox\": true`.\n\nBy default, some key shortcuts for tab items are set in addition to above table.\n\n\u003cdetails\u003e\n\u003csummary\u003e Example of configuration \u003c/summary\u003e\n\u003cpre\u003e\u003ccode\u003e\n{\n  \"hot_key\": \"F8\",\n  \"icon_color\": \"black\",\n  \"always_on_top\": false,\n  \"normal_window\": false,\n  \"zoom_factor\": 0.9,\n  \"chromium_sandbox\": true,\n  \"accounts\": [\n    {\n      \"name\": \"Linda_pp\",\n      \"host\": \"mstdn.jp\",\n      \"default_page\": \"/web/timelines/home\"\n    },\n    {\n      \"name\": \"inudog\",\n      \"host\": \"mastodon.social\",\n      \"default_page\": \"/web/timelines/home\"\n    }\n  ],\n  \"keymaps\": {\n    \"1\": \"/web/statuses/new\",\n    \"2\": \"/web/timelines/home\",\n    \"3\": \"/web/notifications\",\n    \"4\": \"/web/timelines/public/local\",\n    \"5\": \"/web/timelines/public\",\n    \"6\": \"/web/getting-started\",\n    \"ctrl+1\": \"/web/statuses/new\",\n    \"ctrl+2\": \"/web/timelines/home\",\n    \"ctrl+3\": \"/web/notifications\",\n    \"ctrl+4\": \"/web/timelines/public/local\",\n    \"ctrl+5\": \"/web/timelines/public\",\n    \"ctrl+6\": \"/web/getting-started\",\n    \"j\": \"scroll-down\",\n    \"k\": \"scroll-up\",\n    \"i\": \"scroll-top\",\n    \"m\": \"scroll-bottom\",\n    \"n\": \"next-account\",\n    \"p\": \"prev-account\"\n  }\n}\n\u003c/code\u003e\u003c/pre\u003e\n\u003c/details\u003e\n\n## Multi account\n\nIf you add multiple accounts to the `accounts` array in `config.json`, an\n`Accounts` menu item will appear in the application menu.\n\n![multi account menu item](https://github.com/rhysd/ss/blob/master/Mstdn/multi-account.png?raw=true)\n\nIt will show the list of your accounts. The check mark indicates the current\nuser. When you click menu item of non-current user, application window will be\nrecreated and switch page to the account.\n\n## Key Shortcut Plugin\n\nBy specifying JavaScript file to action name in `keymaps` of `config.json`, you\ncan write your favorite behavior with JavaScript directly. Please note that\n`\"chromium_sandbox\" : true` is also required (if you don't know what happens\nwith `\"chromium_sandbox\" : true`, please read the above config section).\n\n```json\n{\n    ...\n\n    \"chromium_sandbox\": false,\n\n    ...\n\n    \"keymaps\": {\n        \"r\": \"hello.js\"\n    }\n}\n```\n\nThe script file path is a relative path from your `Mstdn` application directory.\nFor example, Specifying `hello.js` will run `/Users/You/Application\nSupport/Mstdn/hello.js` on Mac.\n\nThe plugin script MUST export one function. The function receives a\nconfiguration object and the current account object as its parameters. So the\nabove `hello.js` would look like:\n\n```js\nmodule.exports = function (config, account) {\n    alert('Hello, ' + account.name);\n}\n```\n\nWith above example config, typing `r` will show 'Hello, {your name}' alert\ndialog. You can use any DOM APIs, Node.js's standard libraries and Electron APIs\nin a plugin script.\n\n## User CSS\n\nWhen `user.css` is put in your `Mstdn` application directory, it will be loaded\nautomatically.  To enable this feature, `\"chromium_sandbox\" : true` is also\nrequired (if you don't know what happens with `\"chromium_sandbox\" : true`,\nplease read the above config section).\n\nFor example, the below `/Users/You/Application Support/Mstdn/user.css` will\nchange font color to red on Mac.\n\n```css\nbody {\n  color: red !important;\n}\n```\n\n## Plugin (experimental)\n\nYou can make a Node.js package which is run inner mastodon page.\n\nPlugin is enabled if `chromium_sandbox` option is set to `false`. Please read\nabove configuration section before using any plugin.\n\n### How to make a plugin\n\nCreate a `node_modules` directory in your application directory at first. And\nthen, please make `mstdn-plugin-hello` directory. It consists a node package.\n\nThe package name must start with `mastdn-plugin-`.\n\nMake `package.json` manually or by `$ npm init` in the directory.\n\n```json\n{\n  \"name\": \"mstdn-plugin-hello\",\n  \"version\": \"0.0.0\",\n  \"description\": \"Sample plugin of Mstdn.app\",\n  \"main\": \"index.js\",\n  \"author\": \"Your name\",\n  \"license\": \"Some license\"\n}\n```\n\nAnd make `index.js` as below:\n\n```javascript\nmodule.exports = {\n    preload(config, account) {\n        console.log('Hello from plugin!', config, account);\n    }\n};\n```\n\nEach package must export one object. If the object has a function as a value of\n`preload` key, it will be called when the page is being loaded. The function\nreceives two parameters `config` and `account`.\n\nBy defining `keymaps` key you can define plugin-defined key shortcut action.\n\n```javascript\nmodule.exports = {\n    preload(config, account) {\n        console.log('Hello from plugin!', config, account);\n    },\n    keymaps: {\n        'alert-hello'(event, config, account) {\n            event.preventDefault();\n            alert('Hello, ' + account.name);\n        }\n    }\n};\n```\n\nThe `keymaps` object has keymap action name (key) and its handler (value).\nHere 'alert-hello' key shortcut action is defined. Key shortcut handler takes 3\narguments. `config` and `account` is the same as `preload`'s. `event` is a\n`KeyboardEvent` browser event on the key shortcut being called. You can cancel\ndefault event behavior using the `.preventDefault()` method.\n\nUser can specify the key shortcut as `plugin:{plugin name}:{action name}`. In\nabove example, `plugin:hello:alert-hello` is available in `keymaps` section in\nconfig.json.\n\nNote that you can use below APIs in the script.\n\n- [Node.js standard libraries][] via `require` (e.g. `require('fs')`)\n- Dependant node packages listed in `package.json` of the plugin\n- [Electron Renderer APIs][Electron APIs]\n- All Web APIs on browser (including DOM API)\n\n#### !!! Security Notice !!!\n\nDo not leak Node.js stuff to global namespace like below.\n\n```javascript\n// Never do things like this!\nwindow.my_require = require;\n```\n\n### How to use\n\nIf you didn't try above 'How to make' section, please install plugin package at\nfirst.  Below will install 'hello' plugin to `{app\ndirectory}/node_modules/mstdn-plugin-hello`.\n\n```\n$ cd {Your application directory}\n$ npm install mstdn-plugin-hello\n```\n\nAnd then write what plugin should be loaded to `\"plugins\"` section of your\naccount in `config.json`. `\"hello\"` should be added to the list. If listed\nplugin defines some keymaps, you can specify it in `keymaps` section with\n`plugin:{name}:{action}` format.\n\n```json\n{\n    ...\n\n    \"accounts\": [\n        {\n            ...\n\n            \"plugins\": [\n                \"hello\"\n            ]\n        }\n    ],\n    \"keymaps\": {\n        ...\n\n        \"ctrl+h\": \"plugin:hello:alert-hello\"\n    },\n\n    ...\n}\n```\n\nNote that you can enable different plugin for each your accounts.\n\nFinally open Mstdn.app and open the DevTools via [Menu] -\u003e [View] -\u003e [Developper\nTools] -\u003e console. If window is too small to see DevTools, please make window\nsize bigger.\n\nIn the developer console, the message 'Hello from plugin!', config information\nand account information should be output.\n\n### List of Plugins\n\nTo be made\n\n## How to Debug\n\nBy setting `NODE_ENV` environment variable to `development`, Mstdn will start in\ndebug mode.\n\nIn debug mode, app outputs all logs to stdout and opens DevTools for a page\nrendered in a window automatically. You can also see logs in 'console' tab of\nDevTools for debugging renderer process.\n\n```sh\n# If you installed this app via npm or yarn\n$ NODE_ENV=development open-mstdn-app\n\n# Package on macOS\n$ NODE_ENV=development /path/to/Mstdn.app/Contents/MacOS/Mstdn\n\n# Package on Linux\n$ NODE_ENV=development /path/to/Mstdn-linux-xxx-x.y.z/Mstdn\n\n# Package on cmd.exe on Windows\n$ set NODE_ENV=development\n$ \\path\\to\\Mstdn-win32-xxx-x.y.z\\Mstdn.exe\n```\n\n## Contact to the Author\n\nPlease feel free to create an issue on GitHub or mention me on Mastodon/Twitter.\n\n- [@Linda\\_pp@mstdn.jp](https://mstdn.jp/@Linda_pp) (Japanese account. English\n  is also OK)\n- [@inudog@mastodon.social](https://mastodon.social/@inudog) (English account)\n\n[Mastodon]: https://github.com/tootsuite/mastodon\n[npm]: https://www.npmjs.com/package/mstdn\n[yarn]: https://yarnpkg.com/en/package/mstdn\n[AUR]: https://aur.archlinux.org/packages/mstdn/\n[Release page]: https://github.com/rhysd/Mstdn/releases\n[Electron]: https://electron.atom.io/\n[sandbox doc]: https://github.com/electron/electron/blob/master/docs/api/sandbox-option.md\n[npm version badge]: https://badge.fury.io/js/mstdn.svg\n[Node.js standard libraries]: https://nodejs.org/api/\n[Electron APIs]: https://electron.atom.io/docs/api/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frhysd%2Fmstdn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frhysd%2Fmstdn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frhysd%2Fmstdn/lists"}