setup

This page is for anyone in a develop, verify, or localize roles, as these roles require interacting with the Wordplay GitHub repository and running Wordplay on your device. This requires installing many things, including a code editor, the Wordplay repository, and Wordplay's dependencies. Here is the current list of required installs.

Install tools

Note

Please do each of these steps carefully, reading every prompt and error message. Don't rush. Developer tools tend to be poorly designed and assume much prior knowledge, so it's essential to understand each step and decision in these setups.

• Install Node. Node is what runs Wordplay's build tools and installs the libraries it depends on. Wordplay needs Node 24.12.0 or newer. To find out what you have, open a terminal (on macOS, the Terminal app; on Windows, PowerShell) and type node --version. If it prints v24.12.0 or anything higher in the v24 line, you're set. If it prints something older, or says the command isn't found, install Node 24 — reinstalling won't hurt anything. Give Node proper permissions to update and delete packages when it asks; read each prompt carefully.
  • The project also has a file named .nvmrc that records the exact Node version our automated checks run on. If you use nvm to manage Node versions, typing nvm use inside the project folder switches you to that exact version, so what happens on your computer matches what happens when you open a pull request. If you don't use nvm, you can ignore this file — any Node 24.12.0 or newer will work.
• Install VS Code. If you don't have VS Code installed, install it. It's a popular code editor and the one we most recommend for contributing. It also has the best support for TypeScript and Svelte of any editor.
• Install VS Code Extensions. When you first open the project, VS Code will offer its recommended extensions — accept them. "Prettier" (consistent code formatting) and "Svelte for VS Code" (Svelte language features) are the important ones. Prettier is genuinely required, not just recommended: the project formats on save, and without it VS Code falls back to its own built-in JSON formatter, which expands every inline array. One save reformats roughly ten thousand lines of a locale file, and from then on your branch conflicts with every change anyone else makes to it.

If you'll work with accounts, galleries, or end-to-end tests

Most of Wordplay runs on your computer without any of this, so skip this section for now if you're just getting started and come back when you need it.

Wordplay stores accounts and projects in a Google service called Firebase. To try out anything that needs an account — logging in, galleries, sharing — or to run our end-to-end tests, you run a local stand-in for that service called the emulator. It pretends to be Firebase on your own machine, so you can experiment without touching real people's data.

Two more installs make that possible:

• Install the Firebase command line tools. These start and stop the emulator. Follow Firebase's install instructions. To check whether you already have them, type firebase --version in a terminal; if it prints a version number, you're set.
• Install Java. The emulator is written in Java, so it won't start without it, and the error message it gives you when Java is missing is not obvious. To check, type java -version in a terminal. If it says the command isn't found, install a Java Development Kit (any recent version is fine) and then check again.

Once both are installed, see the Firebase page for how to start the emulator and what behaves differently when you're using it.

Learn about Pull Requests

Wordplay uses a collaboration model called Fork and Pull, which involves you following three main steps:

• Fork the Wordplay repository
• Make changes in your fork (while keeping in sync with the Wordplay repository)
• Submit a pull request proposing to merge your changes into the central Wordplay repository and iterate with feedback until it's approved and merged.

Before you do any of this, it's helpful to understand this model at a high level. Read the following before proceeding if you don't know this collaboration model yet:

• Learn about Fork and Pull
• Learn about Best Practices for Pull Requests.
• Learn about How to Fork a Repository.
• Learn about Creating Pull Requests.

Git and GitHub are overly complicated, but you'll get it once you go through a few examples. You can just go slowly and ask questions.

Fork Wordplay and install its dependencies

• Fork the Wordplay repository. The easiest way to do this is to go to the GitHub website, make sure you're logged in, visit the Wordplay repository in a browser, and then find the "Fork" drop-down button. You'll see a command called + Create a new fork... in the drop-down. You'll see a dialog asking what you want to name your fork; all defaults are fine unless you're picky about what it's called. Press the Create a fork button to create the fork in your own personal account.
• Clone your fork to your computer. Open VS Code, then find the toolbar icon called "Source Control." Click it, and make sure you're logged in to GitHub. Then, you'll see a panel with a few buttons, one labeled "Clone Repository." Click it, choose "Clone from GitHub," and then find the name of the fork you created. Choose a place on your computer where you want to store it. Remember that this is just a local copy of the repository; any changes you make are local until you push them to the cloud, and all changes are specific to your fork until you create a pull request that's successfully merged into the Wordplay repository.
• Open a terminal. Now that you have a copy of your fork on your computer and it's open in VS Code, we want to do some commands in the terminal. Find the menu item Terminal > New Terminal to open up a command line so we can work with some commands. Keep this open; you'll be using it later. You may have many open at once.
• Install dependencies. Wordplay requires a few other libraries to run locally. Type npm ci. This will install all of the code that Wordplay needs to run. If you run into problems, it's likely an issue with how Node was installed and, quite often, permissions issues. Many things can go wrong here, so web search on the error you're seeing, or write in #chat for help.
• Add a link to the upstream repository. To tell git that your local clone of your fork should point to the original Wordplay repository, type git remote add upstream https://github.com/wordplaydev/wordplay.git.

Once everything above is installed, try this command in a terminal to run Wordplay locally on your computer:

npm run dev

That should start a local Vite web server and give you a URL like http://localhost:5173 to visit in your browser. You should now see the Wordplay website running on your device. If you don't, there's either a problem with your setup above or Wordplay. Don't worry; it's not your fault. Read any error messages you see, and ask if you need help.

Stay in Sync

Wordplay's code and dependencies are constantly changing, so it's important to run these two commands every once in a while to make sure you're in sync with the main branch:

git fetch upstream
npm ci

The first command pulls new Wordplay code from GitHub and ensures your fork has its updates. (Think of this like a software update). The second command installs any new library updates that Wordplay depends on locally on your machine. Do this regularly (e.g., every time you do some work), so you don't fall so far behind that you have many conflicts between your code and the main repository.

If you made a local branch in your fork for the issue you're working on, then you'll also want to bring main's changes into it:

git merge main

This integrates all of the new commits in main into your branch. If you changed something that someone else also changed, you might have conflicts. Talk to the person you had a conflict with to figure out how to resolve it. (Don't just revert all their changes; you might break something).

You may see git rebase main recommended elsewhere. It replays your commits on top of main and keeps history tidy, but only use it on a branch you have not published — rebasing rewrites commits, so it breaks anyone who has already pulled your branch. Two more reasons to prefer merging: rebase stops once per conflicting commit rather than once in total, and it swaps the sides, so VS Code labels the project's content "Current" and your own commit "Incoming" — the reverse of what you'd expect. If you're working on locale files, see localize; merging is clearly the better choice there.

Finally, don't do a npm update: that will change the versions of installed dependencies, and we want to do that intentionally. npm ci is the only way to preserve dependencies.

Next steps

If you made it this far, you should be all set up! Follow your role's process guidelines for next steps.