Contributing to Remix

Our goal is for Remix development to be steady, stable, and open. We can't do that without our wonderful community of users!

This document will familiarize you with our development process as well as how to get your environment set up.

To ensure your work has the best chance of being accepted, please read this before contributing anything!

Contributor License Agreement

All contributors sending Pull Request need to sign the Contributor License Agreement (CLA) that explicitly assigns ownership of the contribution to us.

When you start a pull request, the remix-cla-bot will prompt you to review the CLA and sign it by adding your name to contributors.yml

Read the CLA

Roles

This document refers to contributors with the following roles:


Development Process

Feature Development

If you have an idea for a new feature, please don't send a Pull Request, but follow this process instead:

  1. Contributors add a Proposal to GitHub Discussions.
  2. The Remix Admin Team accepts Proposals in the Roadmap Planning meeting.
  3. The Admins assign an Owner to the issue.
  4. Owners create an RFC from the Proposal and development can begin.
  5. Pairing is highly encouraged, particularly at the start.

Bug Fix Pull Requests

If you think you've found a bug we'd love a PR that fixes it! Please follow these guidelines:

  1. Contributors add a failing test along with the fix in a Pull Request
  2. The Admins will review open bugfix PRs as part of Roadmap Planning.

Bug fix PRs without a test case might be closed immediately (some things are hard to test, we’ll use discretion here)

Bug Report Issues

If you think you've found a bug but don't have the time to send a PR, please follow these guidelines:

  1. Create a minimal reproduction of the issue somewhere like Stackblitz, Replit, Codesandbox, etc. that we can visit and observe the bug:

  2. If this is not possible (related to some hosting setup, etc.) please create a GitHub repo that we can run with clear instructions in the README to observe the bug

  3. Open an issue and link to the reproduction.

Bug reports without a reproduction will be immediately closed asking for a reproduction.

Roadmap Planning Meeting

You can always check in on Remix development in our live streamed planning meeting:

Issue Tracking

If a Roadmap Issue is expected to be large (involving multiple tasks, authors, PRs, etc.) a temporary project board will be created by the Admin team.

RFCs

Support for Owners

Weekly Roadmap Reviews

Once a week, the Remix team and any external Owners are invited to review the Roadmap

Collaborator's Role

To help keep the repositories clean and organized, Collaborators will take the following actions:

Issues Tab

Pull Requests Tab


Development Setup

Before you can contribute to the codebase, you will need to fork the repo. This will look a bit different depending on what type of contribution you are making:

The following steps will get you setup to contribute changes to this repo:

  1. Fork the repo (click the Fork button at the top right of this page)

  2. Clone your fork locally

    # in a terminal, cd to parent directory where you want your clone to be, then
    git clone https://github.com/<your_github_username>/remix.git
    cd remix
    
    # if you are making *any* code changes, make sure to checkout the dev branch
    git checkout dev
    
  3. Install dependencies by running yarn. Remix uses Yarn (version 1), so you should too. If you install using npm, unnecessary package-lock.json files will be generated.

  4. Install Playwright to be able to run tests properly by running npx playwright install, or use the Visual Studio Code plugin

  5. Verify you've got everything set up for local development by running yarn test

Branches

Important: When creating the PR in GitHub, make sure that you set the base to the correct branch.

You can set the base in GitHub when authoring the PR with the dropdown below the "Compare changes" heading:

Tests

We use a mix of jest and playwright for our testing in this project. We have a suite of integration tests in the integration folder and packages have their own jest configuration, which are then referenced by the primary jest config in the root of the project.

The integration tests, and the primary tests can be run in parallel using npm-run-all to make the tests run as quickly and efficiently as possible. To run these two sets of tests independently you'll need to run the individual script:

We also support watch plugins for project, file, and test filtering. To filter things down, you can use a combination of --testNamePattern, --testPathPattern, and --selectProjects. For example:

yarn test:primary --selectProjects react --testPathPattern transition --testNamePattern "initial values"

We also have watch mode plugins for these. So, you can run yarn test:primary --watch and hit w to see the available watch commands.

Alternatively, you can run a project completely independently by cd-ing into that project and running yarn jest which will pick up that project's jest config.

Development Workflow

Packages

Remix uses a monorepo to host code for multiple packages. These packages live in the packages directory.

We use Yarn workspaces to manage installation of dependencies and running various scripts. To get everything installed, make sure you have Yarn (version 1) installed, and then run yarn or yarn install from the repo root.

Building

Running yarn build from the root directory will run the build. You can run the build in watch mode with yarn watch.

Playground

It's often really useful to be able to interact with a real app while developing features for apps. So you can place an app in the playground directory and the build process will automatically copy all the output to the node_modules of all the apps in the playground directory for you. It will even trigger a live reload event for you!

To generate a new playground, simply run:

yarn playground:new <?name>

Where the name of the playground is optional and defaults to playground-${Date.now()}. Then you can cd into the directory that's generated for you and run npm run dev. In another terminal window have yarn watch running and you're ready to work on whatever Remix features you like with live reload magic 🧙‍♂️

The playground generated from yarn playground:new is based on a template in scripts/playground/template. If you'd like to change anything about the template, you can create a custom one in scripts/playground/template.local which is .gitignored so you can customize it to your heart's content.

Testing

Before running the tests, you need to run a build. After you build, running yarn test from the root directory will run every package's tests. If you want to run tests for a specific package, use yarn test --selectProjects <display-name>:

# Test all packages
yarn test

# Test only @remix-run/express
yarn test --selectProjects express

Repository Branching

This repo maintains separate branches for different purposes. They will look something like this:

- main   > the most recent release and current docs
- dev    > code under active development between stable releases

There may be other branches for various features and experimentation, but all of the magic happens from these branches.

How the heck do nightly releases work?

Nightly releases will run the action files from the main branch as scheduled workflows will always use the latest commit to the default branch, signified by this comment on the nightly action file and the explicit branch appended to the reusable workflows in the postrelease action, however they checkout the dev branch during their set up as that's where we want our nightly releases to be cut from. From there, we check if the git sha is the same and only cut a new nightly if something has changed.

End to end testing

For every release of Remix (stable, experimental, nightly, and pre-releases), we will do a complete end-to-end test of Remix apps on each of our official adapters from create-remix, all the way to deploying them to production. We do this by utilizing the default templates and the CLIs for Fly, Vercel, Netlify, and Arc. We'll then run some simple Cypress assertions to make sure everything is running properly for both development and the deployed app.

Conclusion

Thanks