Hey there! We are really excited that you are interested in contributing. This is a general contribution guide for most of Anthony's projects.
Before submitting your contribution, please make sure to take a moment and read through the following guide:
You're welcome to use AI tools to help you contribute. But there are two important ground rules:
When you write a comment, issue, or PR description, use your own words. Grammar and spelling don't matter – real connection does. AI-generated summaries tend to be long-winded, dense, and often inaccurate. Simplicity is an art. The goal is not to sound impressive, but to communicate clearly.
Feel free to use AI to write code, tests, or point you in the right direction. But always understand what it's written before contributing it. Take personal responsibility for your contributions. Don't say "ChatGPT says..." – tell us what you think.
PRs that we consider fully vibe-coded may be closed without further explanation.
For more context, see Using AI in open source.
We use pnpm for most of the projects, and maybe a few with yarn. We highly recommend you install ni so you don't need to worry about the package manager when switching across different projects.
We will use ni's commands in the following code snippets. If you are not using it, you can do the conversion yourself: ni = pnpm install, nr = pnpm run.
To set the repository up:
| Step | Command |
|---|---|
| 1. Install Node.js, using the latest LTS | - |
| 2. Enable Corepack | corepack enable |
3. Install @antfu/ni |
npm i -g @antfu/ni |
| 4. Install dependencies under the project root | ni |
Start the development environment.
If it's a Node.js package, it will start the build process in watch mode, or stub the passive watcher when using unbuild.
If it's a frontend project, it usually starts the dev server. You can then develop and see the changes in real time.
If it's a Node.js package, it starts a dev server for the playground. The code is usually under playground/.
Build the project for production. The result is usually under dist/.
We use ESLint for both linting and formatting. It also lints for JSON, YAML, and Markdown files if they exist.
You can run nr lint --fix to let ESLint format and lint the code.
Learn more about the ESLint Setup.
Run the tests. We mostly use Vitest - a replacement of Jest.
You can filter the tests to be run by nr test [match], for example, nr test foo will only run test files that contain foo.
Config options are often under the test field of vitest.config.ts or vite.config.ts.
Vitest runs in watch mode by default, so you can modify the code and see the test result automatically, which is great for test-driven development. To run the test only once, you can do nr test --run.
For some projects, we might have multiple types of tests set up. For example, nr test:unit for unit tests, nr test:e2e for end-to-end tests. nr test commonly runs them together; you can run them separately as needed.
If the project contains documentation, you can run nr docs to start the documentation dev server. Use nr docs:build to build the docs for production.
For more, you can run bare nr, which will prompt a list of all available scripts.
Before you start to work on a feature pull request, it's always better to open a feature request issue first to discuss with the maintainers whether the feature is desired and the design of those features. This would help save time for both the maintainers and the contributors and help features to be shipped faster.
For typo fixes, it's recommended to batch multiple typo fixes into one pull request to maintain a cleaner commit history.
We use Conventional Commits for commit messages, which allows the changelog to be auto-generated based on the commits. Please read the guide through if you aren't familiar with it already.
Only fix: and feat: will be presented in the changelog.
Note that fix: and feat: are for actual code changes (that might affect logic).
For typo or document changes, use docs: or chore: instead:
fix: typodocs: fix typo
Before you submit a pull request, make sure to complete the following steps:
- Run
nr lint --fixto fix any linting issues - Run
nr testto ensure all tests pass - If the project has type checking, run
nr typecheck(or equivalent) - For packages, verify the build succeeds with
nr build
If you don't know how to send a Pull Request, we recommend reading the guide.
When sending a pull request, make sure your PR's title also follows the Commit Convention.
If your PR fixes or resolves an existing issue, please add the following line in your PR description (replace 123 with a real issue number):
fix #123This will let GitHub know the issues are linked, and automatically close them once the PR gets merged. Learn more at the guide.
It's ok to have multiple commits in a single PR, you don't need to rebase or force push for your changes as we will use Squash and Merge to squash the commits into one commit when merging.
This section is for maintainers with write access, or if you want to maintain your own forks.
Keeping dependencies up-to-date is one of the important aspects to keep projects alive and getting the latest bug fixes on time. We recommend updating dependencies in weekly or bi-weekly intervals.
We use taze to update the dependencies manually most of the time. As deps updating bots like Dependabot or Renovate could be a bit annoying when you have a lot of projects.
With taze, you can run taze major -Ir to check and select the versions to update interactively. -I stands for --interactive, -r stands for --recursive for monorepo.
After bumping, we install them, run build and test to verify nothing breaks before pushing to main.
Before you do, make sure you have the latest git commit from upstream and all CI passes.
For most of the time, we do nr release. It will prompt a list for the target version you want to release. After selecting, it will bump your package.json and commit the changes with a git tag, powered by bumpp.
There are two kinds of publishing setup, both of which are handled by nr release.
|
For this type of setup, the building and publishing process is done on your local machine. Make sure you have your local In {
"scripts": {
"prepublishOnly": "nr build"
}
}So whenever you run |
For complex projects that take a long time to build, we might move the building and publishing process to CI. So it doesn't block your local workflow. They will be triggered by the
|
Changelogs are always generated by GitHub Actions.
To enable it, run
corepack enableYou only need to do it once after Node.js is installed.
|
Corepack makes sure you are using the correct version of the package manager when you run corresponding commands. Projects might have Under projects with configuration as shown on the right, corepack will install |
|
We use ESLint for both linting and formatting with @antfu/eslint-config.
|
We recommend using VS Code along with the ESLint extension. With the settings on the right, you can have auto fix and formatting when you save the code you are editing. | VS Code's {
"editor.codeActionsOnSave": {
"source.fixAll": false,
"source.fixAll.eslint": true
}
} |
Since ESLint is already configured to format the code, there is no need to duplicate the functionality with Prettier (Why I don't Use Prettier). To format the code, you can run nr lint --fix or refer to the ESLint section for IDE Setup.
If you have Prettier installed in your editor, we recommend you disable it when working on the project to avoid conflict.
In case you are interested, here are Anthony's personal configurations and setups:
- antfu/dotfiles - ZSH configs and other dotfiles
- antfu/vscode-settings - VS Code settings
- antfu/eslint-config - ESLint config
CLI Tools
- ni - package manager alias
- esno - TypeScript runner
- taze - dependency updater
- bumpp - version bumper
In addition to ni, here are a few shell aliases to be even lazier:
alias d="nr dev"
alias b="nr build"
alias t="nr test"
alias tu="nr test -u"
alias p="nr play"
alias c="nr typecheck"
alias lint="nr lint"
alias lintf="nr lint --fix"
alias release="nr release"
{ "packageManager": "pnpm@7.1.5" }