When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change. Please note we have a code of conduct, please follow it in all your interactions with the project.
Table of contents
The current monorepo setup is based on:
- pnpm workspaces, used for managing all Clerk packages from within a single repository.
- Turborepo, used for task running and task output caching.
- Changesets, used for package versioning, publishing and changelog generation.
- GitHub Actions, used for quality checks and automated release orchestration.
- Yalc, used for to publish packages locally and test them in other local projects.
- Jest or Vitest, used for running unit tests.
- Playwright, used for running the integration test suite.
All packages of the monorepo are inside packages. For package specific details on installation, architecture and usage, you can refer to the package's README file.
@clerk/backend: Functionalities regarded as "core" for Clerk to operate with. Authentication resolution, API Resources etc.@clerk/clerk-js: Core JavaScript implementation used by Clerk in the browser.@clerk/clerk-reactClerk package for React applications.@clerk/types: Main TypeScript typings for Clerk libraries.- Browse packages to see more
Additionally there are packages which act as shared utilities or building blocks.
Ensure that you have Node.js installed (How to install Node.js). Its version should be equal or higher than the one defined in .nvmrc in the root of the repository.
To set up your development environment, please follow these steps:
- Clone the repo
git clone https://github.com/clerk/javascript- Enable
pnpmpackage manager.
corepack enable- Install the dependencies. We're using pnpm workspaces, so you should always run
pnpm installfrom the root of the monorepo, as it will install dependencies for all the packages:
cd javascript
pnpm install- Build all the packages in the monorepo by running:
pnpm buildImportant
Ensure you are using the latest or LTS version of Node.
This ensures that all internal TypeScript types are generated and any dependencies between packages are resolving.
Once you're ready to make changes, run pnpm dev from the monorepo root.
If you want to run the dev script of an individual package, navigate to the folder and run the script from there. This way you can also individually run the build script.
Updating documentation is an important part of the contribution process. If you are changing existing behavior or adding a new feature, make sure Clerk's documentation is also updated.
To improve the in-editor experience when using Clerk's SDKs, we do our best to add JSDoc comments to our package's public exports. The JSDoc comments should not attempt to duplicate any existing type information, but should provide meaningful additional context or references. If you are adding a new export, make sure it has a JSDoc comment. If you are updating an existing export, make sure any existing comments are updated appropriately.
When changing functionality or adding completely new code it's highly recommended to add/edit tests to verify the new behavior.
Inside the repository you'll find two types of tests:
- Unit tests
- Integration tests
While changing a file inside a package, check if e.g. a <name>.test.ts file or a test inside a __tests__ folder exists. If you add a completely new file, please add a unit test for it.
If your change can't only be tested by unit tests, you should add/edit an integration test. You can find all necessary information about this in the integration tests README.
- Search our repository for open or closed Pull Requests that relate to your submission. You don't want to duplicate effort.
- Fork the project
- Create your feature branch (
git checkout -b feat/amazing_feature) - It's highly recommended to write tests to ensure your change works and will continue to work in the future
- If required, create a
changesetthat describes your changes (pnpm changeset). In cases where a changeset is not required, an empty changeset can be created instead (pnpm changeset:empty) - an empty changeset will not generate a changelog entry for the change, so please use it as an escape hatch or for internal refactors only. - Commit your changes (
git commit -m 'feat: Add amazing_feature') - Push to the branch (
git push origin feat/amazing_feature) - Open a Pull Request. Make sure the description includes enough information for the reviewer to understand what the PR is about.
- Follow the instructions of the pull request template
For more details about changesets, see Adding a Changeset. A changeset is a piece of information about changes made in a branch or commit. It holds three bits of information:
- What we need to release
- What version we are releasing packages at (using a semver bump type)
- A changelog entry for the released packages
For example:
---
'@clerk/nextjs': minor
---
Description goes hereWill generate the following changelog entry:
## Minor Changes
- Description goes here (#123) by @johndoeChangelog entry framework:
Keep it concise and as information-rich as possible. The most comprehensive changelog entry may include:
- What’s the type of change? - type
- bug fix, feature, breaking change, chore, etc.
- What’s the TL;DR? - summary
- What more details can we share? - details
- What user benefit has this change? - benefit
- More information. Can we link to related things? - resources
A changelog entry should at least contain the type of change and a summary.
If your PR contains changes that require the user to update their code, explain how they can migrate.
Tips:
- Changesets are just markdown files. Feel free to add as much markdown as you want to better describe the change. If e.g. your changeset contains function or package names, use the
inline codesyntax to denote this. - Multiple changesets can be added in a single PR if needed, please see Tips on adding changesets
Great release notes and changelogs are an incredibly important trait of good software. We are always working hard at Clerk to bring updates and improvements to our libraries. And while we believe that this is a good thing, it also means we need to be responsible to our users in making clear what these changes are in a way that is as brief, clear, and understandable as possible. We have all seen libraries that publish changelogs as a list of commits, and I don't think many would argue that while this makes it easy for library developers, it's far from ideal for library users. To reach the standards we have for our library users' experience with Clerk, there is nothing that beats hand-written changelogs by the developers who worked on the features, and this is exactly what changesets empowers us to provide.
Changesets provides streamlined tooling and enforcement to ensure that developers working on features have as easy of a time as possible writing great changelogs, and puts together release notes for us at the quality bar that we strive for. Make sure to think from the perspective of a user when writing changesets to make it crystal clear what your feature is, what impact is has on the library, how to use it, and how to find more detail, if relevant.
Even though we don't use commit messages to track changes between releases, all commit messages need to respect the conventional-commits specification.
Use of a type and a scope in commit message is mandatory.
As per the conventional commits specification, the type can be one of the following: feat, fix, chore, docs. The scope can be one of the package names defined in packages/{package}/package.json, repo for repository level changes or release for releases.
All of these are used to describe changes in the codebase, but they have different purposes:
- Commit message: Briefly describe what the commit is about. Intended to be seen by contributors.
- Commit description: Describe in details why the change was made and include some details about the implementation if needed. Intended to be seen by contributors.
- PR description: Describe in details what the PR is about. This is the first thing a reviewer will see when reviewing a PR, so make sure to explain why the change is needed and offer plenty of details about the actual implementation. It's always useful to include a screen recording or steps to reproduce the issue if the PR is related to a bug fix. Also try to include resources and external documentation if required. Intended to be seen by contributors and will be used as future reference.
- Changeset description: The target audience for these changelogs are other developers. So don’t shy away on including technical details or describing it with words that are generally known among developers. The goal of the changelog entry is to convey the benefit of upgrading to this version in a concise way. Try to provide usage examples and migration steps if required. Read the changesets section to learn how to write great changesets.
- Prefer multiple small PRs with related changes (easier to review and provide feedback)
- Always add description in PRs (describe high level the issue and the solution)
- (issue related PRs) Add screen recording or steps to reproduce the issue
- (issue related PRs) Add screen recording or test to verify the fix
You've found a bug in the source code, a mistake in the documentation or maybe you'd like a new feature? You can help us by submitting an issue on GitHub. Before you create an issue, make sure to search the issue archive - your issue may have already been addressed! Please ensure that you have read and followed the bug report template, otherwise we will have to close the issue. You can submit a feature request by visiting feedback.clerk.com.
Issues that have the label needs-triage have been seen by our team and are queued for triage internally. Issues that have the label prioritized have been discussed and are either in our backlog or being worked on actively. We do our best to prioritize work across a wide variety of sources, only one of which is github issues. While we understand that it can be frustrating if it takes a while for a patch to land, we ask for your understanding in that we have quite a lot of things that need to be worked on at any given time and are still a small team. And remember, the best way to get something fixed in an open source library is to contribute the fix yourself!
If you are a paying Clerk customer looking for support, please reach out directly to our support team by heading to https://www.clerk.com, clicking the chat bubble in the bottom right corner, and selecting "contact support".
If you want to add or edit localizations (e.g. how a button text is translated to your language), you can check out the localizations README.
Note: Only Clerk employees can publish packages.
For more information visit publish documentation.
By contributing to Clerk, you agree that your contributions will be licensed under its MIT License.