Create a minimal reproduction
Software development is hard, and there are an infinite number of different ways that you can configure and code a given application. Additionally, with large and complex applications, the cause of an error can be traced back to a wide variety of different things, making issues even more difficult to debug. The creation of minimal reproductions is an essential tool in any seasoned developer’s belt for resolving difficult issues, as this process gradually eliminates causes of an issue, narrowing it down to only the root cause.
What is a minimal reproduction?
A minimal reproduction is a small test case to demonstrate a problem - often this problem is caused by a bug in the library or user code. Your minimal reproduction should contain the bare minimum code needed to clearly demonstrate that bug.
Templates
The best way to create a minimal reproduction is to start fresh, with a minimal functional template. Clerk provides minimal functional templates for each of the frameworks we have SDKs for, which are great starting points:
Steps to create a minimal reproduction
Clone a template
Clone down one of the templates listed above in order to have the application locally on your machine.
In the example below, you can see options for cloning the Clerk Next.js App Router repository.
Create a Clerk application
Create a new Clerk application through the Clerk Dashboard. You can follow Clerk's setup guide to help you get started.
Set the environment keys
Set the environment keys in your Clerk application. You can find instructions on how to do so in the appropriate quickstart guide.
Run the app
Run the application locally and verify that it’s functional. For example, if you used npm to install the dependencies, you can run the app's development instance with the command npm run dev. The app should then be running on http://localhost:3000 with no errors.
Add code to reproduce the issue
Adjust your template project by adding code gradually until you get to the point where you are running into the same error.
Add a README file (optional)
Add a README file to the root of the repository that contains the steps that must be taken in the app in order to produce the error (click X button, log in using Y provider, etc).
This step is only required if you are submitting the minimal reproduction to the Clerk support team.
It’s important throughout this process to be vigilant about removing code that is not necessary to produce the issue. The ideal result is that the repository gets to the state where the exact same issue is able to be produced, with the fewest lines of code possible to get to that point (beyond the baseline included in the templates).
Often times, the process of creating the minimal reproduction will clarify or resolve the original issue. This is great, if it does happen! That is the magic of minimal reproductions.
Submitting a minimal reproduction
The Clerk support team requires minimal reproductions in order to start looking into reported bugs or issues for any users or customers that are not on an enterprise plan.
Submission requirements
Before submitting a minimal reproduction to the Clerk support team, ensure that the repository:
- Is based off one of the templates above and contains a minimal reproduction or has been stripped down to the bare minimum code needed to reproduce the issue
- Contains a README file with the steps that must be taken in the app in order to produce the error
Submission do's
You can submit either of these options to the Clerk support team:
- A link to a github/bitbucket/gitlab/etc repository.
- A zip file containing a repository.
Submission don'ts
What is not acceptable to submit to the Clerk support team:
- A list of steps that we can take to produce the error
- A pasted error message or error trace
- A link/zip of a full featured app or branch within an app were an error is occurring
- A link to a line in your, or our codebase where an error is presumed to be
- A document containing code blocks that, if combined, describe an app that produces a minimal reproduction
- A link to a repository with a minimal reproduction but no information on how to produce the issue
- A link to a repository with a minimal reproduction that contains a bunch of other third party libraries that are required to produce the issue