Client initialization
Configure a browser-based Clerk client to connect to the application's Frontend API.
Clerk · Pipe
publishableKey
Clerk's publishable key identifies the application's dedicated Frontend API instance. It contains an environment prefix and a base64-encoded FAPI URL, followed by a $ delimiter.
How it works
A publishable key identifies the application's dedicated Frontend API instance. Its encoded URL lets the app locate and communicate with that instance; the key uses an environment prefix such as pk_test_ or pk_live_ and ends with a dollar delimiter.
Syntax
new Clerk(publishableKey)Parameters
| Name | Type | Description |
|---|---|---|
publishableKey | string | The Clerk Publishable Key used to initialize the Clerk instance. |
Returns
A publishable key is configuration data, not a function return value; when supplied to Clerk, it initializes the client for the corresponding Frontend API instance.
Key points
- It tells the app which Frontend API URL to use.
- Its main payload is a base64 representation of the FAPI URL preceded by an environment marker.
- A dollar sign terminates the current encoded portion and leaves room for future extensions.
- The format can be checked by removing the prefix and base64-decoding the remaining value.
Common mistakes
- The application cannot be configured without a publishable key.
- Treat the key as configuration that determines which Frontend API instance the app contacts.
Example: Initialize Clerk with a publishable key
import { Clerk } from '@clerk/clerk-js'
const publishableKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY
const clerk = new Clerk(publishableKey)
await clerk.load()Reads the key from the Vite environment, creates the Clerk client, and loads it.
When to use it
Environment targeting
Select the development or production Clerk environment through the key prefix.
Configuration diagnosis
Inspect or validate the key's encoded FAPI destination during configuration troubleshooting.
Interview questions
QWhat does a Clerk publishable key do?
A publishable key tells the application where its dedicated Frontend API instance is located. Clerk encodes that FAPI URL in base64 and prefixes it with an environment identifier.
Follow-up: What distinguishes development from production keys? The prefix identifies the environment, such as pk_test_ for development or pk_live_ for production.
QWhat is the structure of a publishable key?
The key contains an environment prefix, a base64-encoded FAPI URL, and a trailing dollar delimiter. The encoded URL allows the application to locate and communicate with its FAPI instance.
Follow-up: How can its structure be inspected? Remove the environment prefix, decode the remainder from base64, and inspect the resulting URL plus delimiter.
QHow is publishableKey used in Clerk initialization?
In the JavaScript SDK, pass the key to the Clerk constructor, then load the Clerk instance. A typical source is the Vite environment variable VITE_CLERK_PUBLISHABLE_KEY.
Follow-up: What should be validated before initialization? Check that the environment variable exists and fail early with a configuration error if it does not.
Related
ClerkFrontend API (FAPI)VITE_CLERK_PUBLISHABLE_KEYCLERK_SECRET_KEY