- Install Node.js v20 - we recommend using a Node version manager like nvm or volta.
- Install a code editor - we recommend using VS Code.
- Install the git version control tool.
- Install the pnpm package manager tool.
Any contributions you make will be via Pull Requests on GitHub developed in a local git repository and pushed to your own fork of the repository.
-
Ensure you have created an account on GitHub.
-
Clone your fork to your local machine
> git clone https://github.com/<your-github-username>/opennextjs-cloudflare > cd opennextjs-cloudflare
You can see that your fork is setup as the
origin
remote repository. Any changes you wish to make should be in a local branch that is then pushed to this origin remote.> git remote -v origin https://github.com/<your-github-username>/opennextjs-cloudflare (fetch) origin https://github.com/<your-github-username>/opennextjs-cloudflare (push)
-
Add
opennextjs/opennextjs-cloudflare
as theupstream
remote repository.> git remote add upstream https://github.com/opennextjs/opennextjs-cloudflare > git remote -v origin https://github.com/<your-github-username>/opennextjs-cloudflare (fetch) origin https://github.com/<your-github-username>/opennextjs-cloudflare (push) upstream https://github.com/opennextjs/opennextjs-cloudflare (fetch) upstream https://github.com/opennextjs/opennextjs-cloudflare (push)
-
You should regularly pull from the
main
branch of theupstream
repository to keep up to date with the latest changes to the project.> git switch main > git pull upstream main From https://github.com/opennextjs/opennextjs-cloudflare * branch main -> FETCH_HEAD Already up to date.
The Node.js dependencies of the project are managed by the pnpm
tool.
This repository is setup as a mono-repo of workspaces. The workspaces are stored in the packages
directory.
While each workspace has its own dependencies, you install the dependencies using pnpm
at the root of the project.
-
Install all the dependencies
> cd opennextjs-cloudflare > pnpm install
Build the cloudflare adaptor tool with:
pnpm --filter cloudflare build
or in watch mode with:
pnpm --filter cloudflare build:watch
Build and preview a Next.js sample application. For example, the api
application:
pnpm --filter api preview:worker
You can skip building the Next.js app when it has not been modified, and only run the Cloudflare adaptor tool:
SKIP_NEXT_APP_BUILD=true pnpm --filter api preview:worker
Run the format, lint and type checks on the code:
pnpm run code:checks
Attempt to auto-fix any issues with the format, lint and type checks:
pnpm run code:fixes
Run all the unit tests, via Vitest:
pnpm run test
Run all the e2e tests, via Playwright:
pnpm run e2e
Every non-trivial change to the project - those that should appear in the changelog - must be captured in a "changeset".
We use the changesets
tool for creating changesets, publishing versions and updating the changelog.
-
Create a changeset for the current change.
> pnpm changeset
-
Select which workspaces are affected by the change and whether the version requires a major, minor or patch release.
-
Update the generated changeset with a description of the change.
-
Include the generate changeset in the current commit.
> git add ./changeset/*.md
Each changeset is a file that describes the change being merged. This file is used to generate the changelog when the changes are released.
To help maintain consistency in the changelog, changesets should have the following format:
<TYPE>: <TITLE>
<BODY>
[BREAKING CHANGES <BREAKING_CHANGE_NOTES>]
TYPE
should be a single word describing the "type" of the change. For example, one offeature
,fix
,refactor
,docs
orchore
.TITLE
should be a single sentence containing an imperative description of the change.BODY
should be one or more paragraphs that go into more detail about the reason for the change and anything notable about the approach taken.BREAKING_CHANGE_NOTES
(optional) should be one or more paragraphs describing how this change breaks current usage and how to migrate to the new usage.
The generated changeset file will contain the package name and type of change (eg. patch
, minor
, or major
), followed by our changeset format described above.
Here's an example of a patch
to the @opennextjs/cloudflare
package, which provides a fix
:
---
"@opennextjs/cloudflare": patch
---
fix: replace the word "publish" with "deploy" everywhere.
We should be consistent with the word that describes how we get a worker to the edge. The command is `deploy`, so let's use that everywhere.
We use the following guidelines to determine the kind of change for a PR:
- Bugfixes and experimental features are considered to be 'patch' changes. Be sure to log warnings when experimental features are used.
- New stable features and new deprecation warnings for future breaking changes are considered 'minor' changes. These changes shouldn't break existing code, but the deprecation warnings should suggest alternate solutions to not trigger the warning.
- Breaking changes are considered to be 'major' changes. These are usually when deprecations take effect, or functional breaking behaviour is added with relevant logs (either as errors or warnings.)