Thanks for that you are interested in contributing to Modern.js. Before starting your contribution, please take a moment to read the following guidelines.
Fork this repository to your own GitHub account and then clone it to your local.
We recommend using Node.js 16 or 18. You can check your currently used Node.js version with the following command:
node -v
#v16.18.0
If you do not have Node.js installed in your current environment, you can use nvm or fnm to install it.
Here is an example of how to install the Node.js 16 LTS version via nvm:
# Install the LTS version of Node.js 16
nvm install 16 --lts
# Make the newly installed Node.js 16 as the default version
nvm alias default 16
# Switch to the newly installed Node.js 16
nvm use 16
# Enable pnpm with corepack, only available on Node.js >= `v14.19.0`
corepack enable
pnpm install
What this will do:
prepare
script to build all packages (this will take some time, but is necessary to make ensure all packages are built)A full rebuild of all packages is generally not required after this. If a new feature you are developing requires an updated version of another package, it is usually sufficient to build the changed dependencies.
Please make sure you have your email set up in <https://github.com/settings/emails>
. This will be needed later when you want to submit a pull request.
Check that your git client is already configured the email:
git config --list | grep email
Set the email to global config:
git config --global user.email "SOME_EMAIL@example.com"
Set the email for local repo:
git config user.email "SOME_EMAIL@example.com"
Once you have set up the local development environment in your forked repo, we can start development.
It is recommended to develop on a new branch, as it will make things easier later when you submit a pull request:
git checkout -b MY_BRANCH_NAME
To build the package you want to change, first open the package directory, then run the build
command:
# Replace some-path with the path of the package you want to work on
cd ./packages/some-path
pnpm run build
Alternatively, you can build the package from the root directory of the repository using the --filter
option:
pnpm run --filter @modern-js/some-package build
Build all packages:
pnpm run prepare
If you need to clean all node_modules/*
in the project, run the reset
command:
pnpm run reset
If you've fixed a bug or added code that should be tested, then add some tests.
You can add unit test cases in the <PACKAGE_DIR>/tests
folder. The test syntax is based on Jest and Vitest.
Before submitting a pull request, it's important to make sure that the changes haven't introduced any regressions or bugs. You can run the unit tests for the project by executing the following command:
pnpm run test
Alternatively, you can run the unit tests of single package using the --filter
option:
pnpm run --filter @modern-js/some-package test
In addition to the unit tests, the Modern.js also includes end-to-end (E2E) tests, which checks the functionality of the application as a whole.
You can run the test:e2e
command to run the E2E tests:
pnpm run test:e2e
If you need to run a specified test, you can add keywords to filter:
# Only run test cases with the copy-assets keyword
npx jest copy-assets
To help maintain consistency and readability of the codebase, we use a ESLint to lint the codes.
You can run the Linter by executing the following command:
pnpm run lint
Currently Modern.js provides documentation in English and Chinese. If you can use Chinese, please update both documents at the same time. Otherwise, just update the English documentation.
You can find all the documentation in the packages/document
folder:
root
└─ packages
└─ document
├─ builder-doc # Documentation for Modern.js Builder
├─ doc-tools-doc # Documentation for Modern.js Doc
├─ main-doc # Documentation for Modern.js Framework
└─ module-doc # Documentation for Modern.js Module
This website is built with Modern.js Doc, the document content can be written using markdown or mdx syntax. You can refer to the Modern.js Doc Website for detailed usage.
The source code of Modern.js Doc can be found in this folder.
Modern.js is using Changesets to manage the versioning and changelogs.
If you've changed some packages, you need add a new changeset for the changes. Please run change
command to select the changed packages and add the changeset info.
pnpm run change
Commit your changes to your forked repo, and create a pull request.
The format of PR titles follow Conventional Commits.
An example:
feat(plugin-swc): Add `xxx` config
^ ^ ^
| | |__ Subject
| |_______ Scope
|____________ Type
We use Modern.js Monorepo Solution to manage version and changelog.
Repository maintainers can publish a new version of all packages to npm.
Here are the steps to publish (we generally use CI for releases and avoid publishing npm packages locally):
main
branch.pnpm i
pnpm run prepare
pnpm run bump
git add .
git commit -m "Release va.b.c"