Contributing
Branches, pull requests, conventional commits, releases and the code conventions reviewers check.
NextCRM is MIT-licensed. Contributions of code, translations and docs are welcome. Report bugs and propose features in GitHub issues.
Workflow
Fork and set up
Fork the repository on GitHub, clone your fork, and follow Local setup.
Create a branch
Branch from the latest main. Name it after the change:
git checkout -b feat/target-list-export
git checkout -b fix/invoice-roundingMake the change
Keep a pull request to one concern. Follow the conventions below. Add or update tests.
Check locally
pnpm lint
pnpm exec tsc --noEmit
pnpm test
pnpm test:e2e --project=chromium # when you changed UI flowsIf you added a plugin, also run pnpm plugins:generate --public-only and commit the generated registry.
Commit with conventional commits
See below. The commit type decides how the change appears in the changelog.
Open a pull request
Push the branch to your fork and open a PR. Describe what changed and why, link the issue, and list anything a reviewer must test by hand. CI runs on every PR into dev or main (see Testing and CI).
Branches in the main repository
mainis the release branch. Releases are cut from it.- Branch from
mainand open the pull request againstmain. - Changes reach
mainonly through reviewed pull requests. Nobody force-pushesmain.
Conventional commits
Commit messages follow Conventional Commits: type(scope): summary. The scope is optional and names the area, for example plugins, invoices or docker.
feat(campaigns): add CSV export to the targets table
fix(plugins): cap take for ctx.data reads
security: scope MCP campaign tools by rolerelease-please-config.json maps types to changelog sections:
| Type | Changelog section |
|---|---|
feat | Added |
fix | Fixed |
security | Security |
refactor, perf | Changed |
docs, chore, test | Hidden |
Releases
Releases are automated with release-please (.github/workflows/release-please.yml):
- Every push to
mainruns release-please. - It opens or updates a release PR that bumps the version in
package.jsonand.release-please-manifest.jsonand adds an entry toCHANGELOG.md. - Merging that PR creates the tag (
vX.Y.Z) and the GitHub release.
Do not edit CHANGELOG.md or the version field in package.json by hand.
Code conventions
General
- TypeScript in strict mode. Avoid
any; replacing existinganytypes is welcome cleanup. - Use the
@/path alias for imports. - UI uses shadcn/ui components from
components/uiand Tailwind CSS classes. - Keep changes focused. Do not reformat or refactor code your change does not need.
Data and security
- Check access in every server action, route handler and MCP tool with
@/lib/authz. See Auth and permissions. - Write through
prismadbfrom@/lib/prisma, notprismaBase, so plugin rules apply. - Soft-delete business records (
deletedAt,deletedBy) and filterdeletedAt: nullon reads. - Write an audit log entry for changes to CRM records.
- Send the
crm/<entity>.savedevent after creating or updating accounts, contacts, leads or opportunities. - Serialise Prisma
Decimalvalues withserializeDecimals()before they reach Client Components. - Schema changes need a committed migration. See Data model.
Product scope
NextCRM is one generic product used by many independent instances. Core changes must work for every instance and be configurable where behaviour differs. Do not add code for a single installation to the core. Build instance-specific behaviour as a plugin, and keep non-public plugins in plugins-private/.
Translations
User-facing strings go through next-intl. Add every new key to all four files in locales/. See Internationalization.
Security issues
Do not report vulnerabilities in public issues. Use GitHub's private vulnerability reporting for the repository ("Report a vulnerability" on the Security tab).
Getting help
Ask in GitHub Discussions or on the project's Discord server (linked from the README).