CONTRIBUTING.md

Contributing to next-safe-action

Code contributions are very welcome, so if you decide to help improve the library code, thank you! First of all, though, please read the guidelines below.

Information about the project

This is a monorepo, that uses:

• pnpm as package manager;
• Turborepo as build system;
• TypeScript as primary language;
• ESLint as linter;
• Prettier as formatter;
• Husky as Git hooks manager;
• Commitizen as commit message manager;
• Commitlint as commit message linter;
• semantic-release as release manager.
• Docusaurus for the documentation website.

What you need to install

• git;
• Node.js LTS version specified in .nvmrc. Highly recommended to use fnm or nvm for easy management of Node.js versions;
• a code editor: VS Code is the recommended one, as it enables workspace specific settings and extensions to make the development more user-friendly;
• pnpm as package manager.

Repository structure

• packages/next-safe-action: contains the source code of the library;
• apps/playground: contains the source code of the Next.js playground app, which is a basic implementation of the library;
• website: contains the source code of the next-safe-action website.

How to contribute

Getting started

Before opening a pull request, please follow the general rule of opening an issue or discussion first, using the issue templates, that will guide you through the process. You can avoid opening a new issue or discussion if:

• You're correcting a trivial error, like a typo;
• The issue or discussion for the bug you're fixing/feature you're implementing with the PR is already open.

Development setup

After forking, cloning the repository and optionally creating a new branch from the base one, you can install the dependencies using pnpm in the project root directory:

pnpm install

Then, you can run the build:lib command to rebuild the library code, and then test it in the playground app:

pnpm run build:lib && pnpm run pg

Tip

If you see many type errors in the playground app after running the build:lib command, try to restart the TS Server of VS Code. This should fix the errors.

If you updated user facing APIs of the library, you're not required, but highly incouraged to:

• update the documentation of the library to reflect the changes you've made.
• write tests for the changes you've made. They should be placed in the appropriate file inside __tests__ directory (next-safe-action package).

These steps can be done in later stages of the PR too, for instance when a maintainer already approved your code updates.

Note that the website project is not part of the monorepo packages, so you need to cd into it and then run this command to install its dependencies:

pnpm install

Then you can start the Docusaurus development server with:

pnpm run start

Committing changes

Once you're done with your code changes, you can finally commit and push them to the remote repository.

Committing is very easy, thanks to both commitizen and commitlint utilities. Each commit message must follow the Conventional Commits format, to allow for automated release management via semantic-release. You can commit your code using:

git commit --no-edit

This command will bring up the commitizen interface to help you write a proper commit message, without also bringing up the default editor. If you want to, you can set up an alias for it, to make it easier to type and remember. The commit message is then run through commitlint to validate it.

Changes made in website or playground scopes must be typed chore(<scope>), since they are not part of the library code.