Contributing to Pinafore
To contribute or change translations for Pinafore, look in the src/intl directory. Create a new file or edit an existing file based on its two-letter language code and optionally, a region. For instance,
en-US.js is American English, and
fr.js is French.
The default is
en-US.js, and any strings not defined in a language file will fall back to the strings from that file.
To install with dev dependencies, run:
To run a dev server with hot reloading:
yarn run dev
Now it's running at
Linux users: for file changes to work,
you'll probably want to run
because of this issue.
yarn run lint
Automatically fix most linting issues:
yarn run lint-fix
Integration tests use TestCafé and a live local Mastodon instance
Running integration tests
The integration tests require running Mastodon itself,
meaning the Mastodon development guide
is relevant here. In particular, you'll need a recent
version of Ruby, Redis, and Postgres running. For a full list of deps, see
Run integration tests, using headless Chrome by default:
Run tests for a particular browser:
BROWSER=chrome yarn run test-browser BROWSER=chrome:headless yarn run test-browser BROWSER=firefox yarn run test-browser BROWSER=firefox:headless yarn run test-browser BROWSER=safari yarn run test-browser BROWSER=edge yarn run test-browser
If the script isn't able to set up the Postgres database, try running:
sudo su - postgres
psql -d template1 -c "CREATE USER pinafore WITH PASSWORD 'pinafore' CREATEDB;"
Testing in development mode
In separate terminals:
1. Run a Mastodon dev server:
yarn run run-mastodon
2. Run a Pinafore dev server:
yarn run dev
3. Run a debuggable TestCafé instance:
npx testcafe --debug-mode chrome tests/spec
The tests have a naming convention:
0xx-test-name.js: tests that don't modify the Mastodon database (read-only)
1xx-test-name.js: tests that do modify the Mastodon database (read-write)
In principle the
0- tests don't have to worry about
clobbering each other, whereas the
1- ones do.
Mastodon used for testing
There are two parts to the Mastodon data used for testing:
- A Postgres dump and a tgz containing the media files, located in
- A script that populates the Mastodon backend with test data (
The reason we don't use a Postgres dump for everything is that Mastodon will ignore changes made after a certain period of time, and we don't want our tests to randomly start breaking one day. Running the script ensures that statuses, favorites, boosts, etc. are all "fresh".
Updating the test data
You probably don't want to do this, as the
0xx tests are pretty rigidly defined against the test data.
1xx test instead and insert what you need on-the-fly.
If you really need to, though, you can either:
- Add new test data to
- Comment out
- Make your changes manually to the live Mastodon
- Run the steps in the next section to back it up to
Updating the Mastodon version
rm -fr mastodonto clear out all Mastodon data
- Comment out
run-mastodon.jsto avoid actually populating the database with statuses/favorites/etc.
- Update the
run-mastodon.jsto whatever you want
- If the Ruby version changed, install it and update
yarn backup-mastodon-datato overwrite the data in
- Commit all changed files
rm -fr mastodon/and
yarn run run-mastodonto confirm everything's working
mastodon.log if you have any issues.
Note that we also run
db:migrate just to play it safe, but
fixtures/ should make that a no-op.
There are also some unit tests that run in Node using Mocha. You can find them in
run them using
yarn run test-unit.
To disable minification in a production build (for debugging purposes), you can run:
DEBUG=1 yarn build
The Webpack Bundle Analyzer
stats.json are available publicly via e.g.:
This is also available locally after
yarn run build at
template.html is itself templated. The "template template" has some inline scripts, CSS, and SVGs
injected into it during the build process. SCSS is used for global CSS and themed CSS, but inside of the
components themselves, it's just vanilla CSS because I couldn't figure out how to get Svelte to run a SCSS
Lots of small files
Highly modular, highly functional, lots of single-function files. Tends to help with tree-shaking and code-splitting, as well as avoiding circular dependencies.
emoji-picker-element is loaded as a third-party bundle
emoji-picker-element uses Svelte 3, whereas we use Svelte 2. So it's just imported
as a bundled custom element, not as a Svelte component.
Some third-party code is bundled
For various reasons,
timeago are forked and bundled into the source code.
This was either because something needed to be tweaked or fixed, or I was trimming unused code and didn't
see much value in contributing it back, because it was too Pinafore-specific.
Every Sapper page is "duplicated"
To get a nice animation on the nav bar when you switch columns, every page is lazy-loaded as
This "lazy page" is merely delayed a few frames to let the animation run. Therefore there is a duplication
src/routes/_pages. The "lazy page" is in the former, and the actual page is in the
latter. One imports the other.
There are multiple stores
Originally I conceived of separating out the virtual list into a separate npm package, so I gave it its
own Svelte store (
virtualListStore.js). This never happened, but it still has its own store. This is useful
anyway, because each store has its state maintained in an LRU cache that allows us to keep the scroll position
in the virtual list e.g. when the user hits the back button.
Also, the main
store.js store is explicitly
loaded by every component that uses it. So there's no
store inheritance; every component just declares
whatever store it uses. The main
store.js is the primary one.
There is a global event bus
eventBus.js. This is useful for some stuff that is hard to do with standard Svelte or DOM events.