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.
- Ensure you have the latest version of Node and Yarn.
- Run
yarn
to install all needed dev dependencies.
Pull requests are encouraged. If you want to add a feature or fix a bug:
- Fork and clone the repository.
- Create a separate branch for your changes.
- Make your changes, and write tests that validate your change and/or fix.
- Run
yarn test
(for all packages) oryarn test:core
(for only changes to core XState). - Run
yarn typecheck
to make sure that there are no type errors. - Create a changeset by running
yarn changeset
. More about changesets. - 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.
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.
Issues and bug reports are also encouraged. If you want to submit an issue:
- Search existing issues to check if your issue already exists or has been solved.
- Create a new issue if your issue has not yet been submitted.
- 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.
Our new docs are now in their own docs repo. Read the contribution guide for our Stately Studio and XState docs.
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.
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 yarn postinstall
.
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).