Hey there! Glad you’re interested in helping us with this project. Below are some guidelines and important things to note when contributing to the
glitch-socfrontend (the “web view” app). If you have any questions, don’t be afraid to reach out!!
Mastodon’s frontend is developed with React and Redux and served using Webpack. Depending on what you’re hoping to work on, you can get by without understanding the specifics of Redux or Webpack but knowledge of React is a must. That said, React isn’t too difficult to pick up and they have some very nice reference materials on their website .
Mastodon runs its code through a linter to make sure it maintains some semblance of order and consistency, and you should run these tests before you push.
You can use
npm test to do this; on Vagrant, that’s
vagrant ssh -c "cd /vagrant && npm test" (assuming you have already called
In general, it’s best if you have a development environment so that you can test your code, and you should reach out to someone on the
glitch-soc development team if you need help setting that up.
Mastodon uses two (2) spaces for indentation everywhere.
camelCased, except in the case of global constants, which are often in
JSX components are naturally
PascalCased, as JSX requires a leading capital letter.
With regard to HTML
class names, everything is lowercase and components are typically separated with a double-underscore, with hyphens betwen words.
.status__header-button__smile would describe the “smile” component inside of the “header button” component inside of “status”.
class names are kinda arbitrary so don’t worry about it too much lol.
Try to make sure every file ends in a blank line to keep Git happy . Also try to make sure lines don’t have trailing spaces to keep things clean. Many editors have plugins that will do this for you.
There are a few other rules that you’ll notice when linting because they’ll throw errors; for example, curly braces need whitespace around them and list items should terminate in a comma when they’re on their own line (even if they’re the last item). You’ll pick these up as you go along and just try to make everything look consistent.
Generally, I like to avoid long lines. It’s possible to go too far with this (and I probably have in places ) but just try to keep things looking nice. It’s less of a big deal with code, but with documentation especially you should make an effort to keep it readable.
I tend to wrap lines after 71 characters (such that the terminal
LF is № 72) if anyone is wondering.
I think upstream development favours a number closer to 80.
Components and structure
All of the frontend assets which Mastodon uses are stored in the
There are a few places of interest here:
mastodon folder contains components from upstream (vanilla) Mastodon.
These components might have some glitch modifications, but if so they should be kept small.
Not all of these files are used .
In certain cases, we have replaced Mastodon’s vanilla components with our own.
You’ll find a number of subfolders inside the
mastodon folder with various scripts and components.
This folder follows the same basic structure as our own
glitch folder (see below), but ours is better-organized.
glitch folder contains our custom in-house components.
You can change these files as much as you want, since they will never conflict with anything upstream.
If you’re creating a new file to add to the frontend, you should create it here.
glitch folder, there are the following subfolders:
actions: These are Redux action scripts.
components: These are all of the React components. The components in this folder must not have direct access to the Redux store, with the exception of files with the name
container, which must not have render methods of their own.
Components should be placed into one or more subfolders according to where they appear. The name of the component should reflect this structure; for example the component at
Ideally, each file should contain (and export) only a single component.
locales: Here live Glitchsoc custom translations and overrides to the original mastodon messages. We decided to split this off from
mastodon/localesto avoid merge conflicts. We have adjusted the locale script, so messages in
glitch/localesare added to, and replace if needed, messages with matching keys from
Please try to avoid modifying the original files (eg. by running
yarn manage:translationsand commiting the changes). Don’t worry about
defaultMessages.json, it’s presently not used for anything—all the important stuff goes in
en.json(or other languages, if you like).
reducers: These are Redux reducers, to complement the actions provided by the
util: These are generic scripts which do not fit into any of the categories above.
styles folder contains all of Mastodon’s styles, for both the frontend application and its static pages.
98% of the time the only file you’ll be interested in here is
It’s incredibly disorganized but try to make do .
With respect to files in the
styles folder, try to document your code, but keep things somewhat minimal so that we don’t have conflicts with upstream.
With files in the
glitch folder, document everything liberally.
I favour Markdown syntax inside of block comments, personally.
If you feel up to it, include a OStatus username by your code so that people know who to contact if they have any questions .
I am of the opinion that someone should be able to figure out more-or-less everything a file does just by reading the comments (ie, without understanding a line of code), and this will make it much easier for others who come along to do
glitch-soc/docs documentation work, who might not be fluent programmers.
Open-source is only open to those people who can read the source, and having a well-commented codebase greatly improves accessibility and helps users stay informed about what the application is doing behind their back .