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. If you don't have node installed, install it. And if you don't know if you do, you probably don't. It won't hurt to install it again. This allows you to install all the packages that Wordplay depends on to run. Ensure you give Node proper permissions to update and delete packages as necessary; read each prompt carefully.
• 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. At a minimum, you'll want "Prettier" (which ensures consistent code formatting) and "Svelte for VS Code" (which adds Svelte language features to VS Code).

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 https://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 likely also want to rebase your branch on main:

git rebase main

This will replay commits since the last time you fetched from the main. If you change something, someone else changes, and you might have conflicts. Talk to the person you had a conflict with to figure out how to resolve the conflict. (Don't just revert all their changes; you might break something).

If you've published your branch, do not use rebase. Instead, merge main into your branch by checking out your break, and doing github merge main. This will integrate all of the new commits in main into your local branch.

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.