These are the guidelines we use to write our docs.
Clerk is an American company and the epicenter of our development community is located in America's tech community. For that reason, we use the American flavor of English (as opposed to British English).
You might not realize it, but you can change the colors of your Clerk components with global CSS.
You might not realise it, but you can change the colours of your Clerk components with global CSS.
Tech has created many new words by associating two words with each other like "front end" and "web site." On a long enough timeline, these migrate to hyphenated forms: "web site" became "web-site." And finally they become concatenated words: "website." We use the concatenated forms.
Frontend and fullstack developers often build websites with React.
Front-end and full stack developers often build web-sites with React.
When mentioning a documented component, function, etc, multiple times on a page, link to the reference documentation on the first mention of that item. The exception to this rule is when the reference is mentioned under a different heading. In that case, link to the reference documentation again.
The
currentUser()
helper will return theUser
object of the currently active user. The following example uses thecurrentUser()
helper to access theUser
object for the authenticated user.
The
currentUser()
helper will return theUser
object of the currently active user. The following example uses thecurrentUser()
helper to access theUser
object for the authenticated user.
If you want to abbreviate a term in your article, write it out fully first, then put the abbreviation in parentheses. If you want to make an abbreviation plural treat them as regular words, e.g. APIs, IDEs or OSes.
An abstract syntax tree (AST) is a tree representation of code. ASTs are a fundamental part of the way a compiler works.
An AST is a tree representation of code. AST's are a fundamental part of the way a compiler works.
"Middleware," "Server Actions," "Server Components," "Route Handlers" are capitalized in the Next.js docs and in Clerk's docs where referring to a Next.js project or code.
Add it to your app's Middleware.
Add it to your app's middleware.
When referring to Clerk's SDKs, components, and dashboard, use "sign in" and "sign out" rather than "log in" or "log out". This is consistent with our <SignIn />
component and SignIn
class.
<SignInButton />
creates a button that allows users to sign into your Clerk application.
<SignInButton />
creates a button that allows users to log into your Clerk application.
Clerk is the entity writing these docs and providing these services. The learner is the person consuming these things and building their own projects. To distinguish between the two and write with clarity, we refer to the learner with "you/your/yours." We objectively refer to Clerk as "Clerk," not "we/us/our/ours."
Clerk's
<ClerkProvider>
provides active session and user context to Clerk's hooks and other components. Import it into your app by addingimport { ClerkProvider } from '@clerk/nextjs'
at the top of your file.
Our
<ClerkProvider>
provides active session and user context to our hooks and other components. Let's import it into our app by addingimport { ClerkProvider } from '@clerk/nextjs'
at the top of the file.
People building with clerk are building for other people to make it clear whether we are talking about the builder or their users, we call builders "developers" and the peoeple they are building for "users."
Clerk helps developers overcome as many challenges as possible without additional configuration. This ensures their users have a secure, safe session.
Clerk helps users overcome as many challenges as possible without additional configuration. This ensures their users have a secure, safe session.
Write short sentences. Short sentences are easier for both human and robots to translate. Concise writing is understandable writing. Look for commas that string together different thoughts. These are often good places to shorten and clarify content.
Clerk is now installed and mounted in your application. You can decide which pages are public or require authentication to access.
Now that Clerk is installed and mounted in your application, you can decide which pages are public and which should require authentication to access.
English gerunds ("-ing" words like "running") turn verbs into nouns ("run" becomes "running"). This makes the sentence sound passive ("They run" becomes "they are running") and makes it harder to translate. Use an active voice as much as possible and avoid these words.
How to use a routing library with Clerk
Using a routing library with Clerk
Tell the learner what they will learn from diving into the content.
How to read session and user data
How user sessions and user data work
Clearly explains what information the learner will find, helping them decide which to choose.
User session and user data
Obscure. Doesn't convey whether this is the conceptual or task-based content the learner is looking for. They may pass over it or look briefly, then bounce out. This increases friction.
When learners are performing an order of operations, it helps for them to start with where they need to be to perform the action.
In your Next.js project's root folder, open your
.env.local file
.
The learner navigates to the project folder first, opens the file second.
Open your
.env.local file
in your Next.js project's folder.
The learner must remember the file they need to open before finding out which folder to navigate to. This uses more mental energy.
English speakers may find themselves using phrases which cultural meaning may be different around the world.
Something that is difficult for someone new to programming may not be for a senior engineer.
Something that is difficult for someone new to programming may be child's play for a senior engineer.
Some learners may not have heard this expression before. It may be difficult for machine translation as well.
Use active verbs that put the reader in the first person instead of passive verbs; "be" verbs that describe the learners actions as a state of being, like "is/was/to be".
Create the
middleware.ts
file in the root folder of your application or inside thesrc/
if that is how your app is set up.
The
middleware.ts
file should be created in the root folder of your application or insidesrc/
if that is how you set up your app.
Avoid using language that assumes someone's level of proficiency. Something that is difficult for someone new to programming may not be difficult for a senior engineer. This language can inadvertently alienate or insult a learner. Avoid words like "just," "easy," "simple," "senior," "hard."
Use as little jargon as necessary. Describe jargon in parentheses on first reference or link to a trusted definition.
You can authenticate your app with Clerk in three steps. Install Clerk with
npm install @clerk/nextjs
, add your environment variables, and then wrap your app in<ClerkProvider>
, and add control components. Visit our Quickstarts for a step-by-step guide written for your framework.
Clerk supports offline mode, a feature that lets users use an app without being connected to data or wifi. This means Clerk works great with progressive web apps, apps built with web platform technologies that provide similar experiences to platform-specific apps. You can use the dynamic import pattern to improve loading speeds.
It's easy to authenticate your app with Clerk! Just install Clerk with
npm install @clerk/nextjs
, add your environment variables, wrap your app in<ClerkProvider>
, and simply add control components.
Clerk works great with PWA as it supports offline mode. You can use the dynamic import pattern to improve loading speeds.
It's tempting to use things that are familiar to us to explain things to others—our favorite TV shows, books, and memes are entertaining and rich sources of metaphors. However, they assume a shared context between author and reader. A joke that mainstream American audiences understand may be completely misunderstood to a learner in Chile.
const updateUser = async () => {
await user.update({
firstName: 'John',
lastName: 'Doe',
})
}
const updateUser = async () => {
await user.update({
firstName: 'Twilight',
lastName: 'Sparkle',
})
}
This assumes the learner is familiar with the cartoon My Little Pony: Friendship is Magic, which is irrelevant.
For many years it was common to write with "he/him/his" pronouns in English technical documentation. But pronouns are difficult to translate into some languages. Gendering learners also sends the message that some genders are "default"—and this might not be the learner's gender. We use the neutral "they/them/theirs" pronouns.
When the user logs out using the button, they will be taken to the sign-in page.
When he logs out using the button, he will be taken to the sign-in page.
"Click" is an outdated term that assumes the learner is using a mouse. But learners may be navigating by touchscreen, keyboard, or assistive technology. Often there are better words than "click"—like "select" and "open".
Open the Settings tab.
Select the Google social connection.
Click the Settings tab.
Click the Google social connection.
4.1 Use monospace fonts for code, commands, file names, copy-ables, and URLs; use bold for menus, and other UI copy.
In your Clerk Dashboard, go to User & Authentication > Social Connections and open the Settings tab.
In your browser, open
http://localhost:3000/
.
In your Clerk Dashboard, go to
User & Authentication > Social Connections
and open the "Settings tab."
In your browser, open
http://localhost:3000/
.
Use carets to nest operations of the same type like menu navigation.
In your Clerk Dashboard, go to User & Authentication > Social Connections and open the Settings tab.
In your Clerk Dashboard, go to User & Authentication, click on Social Connections, and open the Settings tab.
Conform to the JSON standard:
- Key names are enclosed in double quotes (
"
) - Values are between double quotes (
"
), not single quotes ('
) - No comments, neither
//
nor/* */
This is the user's primary email address in the User object
{
"email": "{{user.primary_email_address}}"
}
{
// this is the user's primary email address in the User object
"email": "{{user.primary_email_address}}"
}
We use 2-space indents to conserve horizontal space in code blocks.
export const config = {
matcher: ['/((?!.+\\.[\\w]+$|_next).*)', '/', '/(api|trpc)(.*)'],
}
export const config = {
matcher: ['/((?!.+\\.[\\w]+$|_next).*)', '/', '/(api|trpc)(.*)'],
}
Clerk authentication states signed-in, signed-out, and unknown should be hyphenated and bold to distinguish them from general states of being.
Once you have a signed-in user, you need to give them a way to sign out.
Once you have a signed-in user, you need to give them a way to sign out.
When presenting things in a series of tabs, ensure that similar things are grouped together.
Next.js is a platform with two different implementations grouped underneath it.
Next.js's two implementations are given equal weight to the other members of the tab bar. Someone unfamiliar with Next.js may become confused, and the ever growing tab bar is harder to navigate at smaller sizes.
Component references should be wrapped in < />
if they are self closing. Otherwise, they should be wrapped in < >
.
Use the
<SignIn />
component.
Use the
<ClerkProvider>
component.
Use the
<SignIn/>
component.
Use the "SignIn component".
Use the
SignIn
component.
Use the
<SignIn>
component.
The last case is incorrect because the <SignIn />
component will never wrap children, and therefore, should have a self-closing tag.
Use the
<ClerkProvider />
component.
The last case is incorrect because the <ClerkProvider>
component will always wrap children and will never be self-closing.
If the code should run in a terminal, set the code block's syntax highlighting and filename with sh filename="terminal"
.
```sh {{ filename: 'terminal' }}
npm i @clerk/nextjs
```
```
npm i @clerk/nextjs
```
Be sure to use the correct term with components vs functions.
Be sure to use the appropriate terms on reference page headings.
Pass the
signUpProps
property to<SignUp />
.buildUrlWithAuth()
accepts astring
for theto
parameter.
The
<SignUp />
component accepts thesignUpProps
parameter. ThebuildUrlWithAuth()
function accepts theto
property.
When telling learners to perform an operation in the Clerk Dashboard, begin with "In your Clerk Dashboard". Then, end with a link to the page you are directing them to with this URL syntax: https://dashboard.clerk.com/last-active?path=PAGE
In your Clerk Dashboard, navigate to User & Authentication.
To specify the fallback redirects, in the Clerk Dashboard, go to the Account Portal page and open the Redirects tab.
Go to User & Authentication in your dashboard.
Find fallback redirects in the Redirect tab on the Account Portal in the Clerk Dashboard.