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(opens in a new tab) repository.

The 'clerk-nextjs-app-quickstart' repository page with the 'Code' button clicked on and its drop down menu is opened. There is a red arrow pointing to the 'Code' button.

Create a Clerk application

Create a new Clerk application through the Clerk Dashboard. You can follow Clerk's setup guide(opens in a new tab) to help you get started.

Set the environment variables

Set the environment variables 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, sign 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

Last updated on March 8, 2024