Contributing

Thank you for your interest in contributing to XState! Contributors like you make this project possible, and we welcome any contributions to the code base and the documentation.

There are several ways you can contribute to XState:

• 📥 Submit an issue
• ✨ Solve an issue or make a change
• 🖊️ Write documentation
• 💬 Respond to support questions in the GitHub discussions
• 🛟 Respond to questions in the Help channel on Discord

Please read our code of conduct.

Environment

• Use Node 24.16.0.
• Enable Corepack and run pnpm install. The repository pins pnpm 9.15.9.

Making changes

Pull requests are encouraged. If you want to add a feature or fix a bug:

1. Fork and clone the repository.
2. Create a separate branch for your changes.
3. Make your changes, and write tests that validate your change and/or fix.
4. Run pnpm test (for all packages) or pnpm test:core (for only changes to core XState).
5. Run pnpm lint and pnpm format:check.
6. Run pnpm typecheck to make sure that there are no type errors.
7. Create a changeset by running pnpm changeset. More about changesets.
8. Push your branch and open a PR 🚀

PRs are reviewed promptly and merged in within a day or two (or even within an hour) if everything looks good.

Contributing an example

Our examples are self-contained apps that show how to solve a common problem, integrate another framework (like Vue or Svelte) or build something fun with XState.

To contribute an example, please read the readme in the /examples folder.

Submit an issue

Issues and bug reports are also encouraged. If you want to submit an issue:

1. Search existing issues to check if your issue already exists or has been solved.
2. Create a new issue if your issue has not yet been submitted.
3. Ensure you fill out all the details in the issue template to help us understand the issue.

We’ll try to respond promptly and address your issue as soon as possible.

Contributing to our docs

Our new docs are now in their own docs repo. Read the contribution guide for our Stately Studio and XState docs.

Legacy docs and xstate.js.org

The docs at /docs in this repo are legacy XState docs. They are built using Vuepress and deployed to xstate.js.org/docs using GitHub pages from the gh-pages branch using the pages build and deployment workflow.

The xstate.js.org landing page is currently stored at index.html and deployed from the gh-pages branch using the pages build and deployment workflow.

Setup

Building

We are using preconstruct to build our packages. It comes with a handy trick which allows us to always use source files of packages contained in this monorepo. It creates hook/redirecting files in place of dist files during development. This always happens after installing packages (during postinstall step) and you shouldn't be worried about it, but if you actually build packages you destroy those redirecting files and to run tests, typechecking etc correctly you need to bring them back by running pnpm postinstall.

Publishing

We are using changesets to create "release intents" for our packages. When those pop up on master a release PR gets prepared automatically and once it gets merged actual release happen (also automatically).