Docs

You are viewing an archived version of the docs.Go to latest version

JavaScript Quickstart

You will learn the following:

  • Add the ClerkJS SDK to your JavaScript application
  • Use Clerk components to allow users to sign in or out

Note

The next major version of the Clerk Javascript SDK is coming soon! If you're just starting a project, consider trying out the Core 2 beta instead.

To add the ClerkJS SDK to your JavaScript application, you have two options:

  1. Install the package using a package manager, like npm, yarn, or pnpm.
  2. Use the <script> tag to load the ClerkJS package from our CDN.

Select your preferred method below to get started.

Set up a JavaScript application using Vite

To install the ClerkJS SDK, you will need to use a bundler like Vite or Webpack to use this method.

For the sake of this guide, scaffold your new JavaScript application using Vite. From the prompts, choose the Vanilla framework, and then choose the JavaScript variant.

terminal
npm create vite@latest clerk-javascript
cd clerk-javascript
npm install
npm run dev
terminal
yarn create vite clerk-javascript
cd clerk-javascript
yarn install
yarn dev
terminal
pnpm create vite clerk-javascript
cd clerk-javascript
pnpm install
pnpm dev

Install @clerk/clerk-js

At the root of your project, install the ClerkJS package using your package manager of choice:

terminal
npm install @clerk/clerk-js
terminal
yarn add @clerk/clerk-js
terminal
pnpm add @clerk/clerk-js

Set environment variables

It's recommended to use environment variables to store your Clerk Publishable Key. A common way to use environment variables in a JavaScript project is by putting the values in an .env file and then loading them into your application using a package like dotenv. However, when using Vite, environment variables stored in an .env file at the project root are automatically exposed through the import.meta.env object.

  1. Create an .env file at the root of your project, and add your Clerk Publishable Key. If you're signed into Clerk, the .env snippet below will contain your key. Otherwise, you can copy it from the Clerk Dashboard by navigating to the API Keys page.
.env
VITE_CLERK_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY
  1. In your main.js file, import the publishable key using Vite's import.meta.env object.
main.js
const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY;

Initialize ClerkJS

To initialize the ClerkJS SDK, import the Clerk class and instantiate it with your Publishable Key. Then, call the load() method to initialize ClerkJS.

main.js
import Clerk from "@clerk/clerk-js";

const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY;

const clerk = new Clerk(clerkPubKey);
await clerk.load({
  // Set load options here
});

Note

Calling the load() method initializes ClerkJS. For more information on the load() method and what options you can pass to it, check out the reference documentation.

Allow users to sign in and out

Clerk's prebuilt components are the easiest way to add authentication and user management to your application. They come styled out of the box and are customizable to fit your application's design.

To get started, you will use:

  • <SignIn />: renders a user interface for signing in.
  • <UserButton />: shows the avatar from the account the user is signed in with. When clicked, it opens a dropdown menu with options to sign out.

Your main.js file should look something like this:

main.js
import Clerk from "@clerk/clerk-js";

const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY;

const clerk = new Clerk(clerkPubKey);
await clerk.load();

if (clerk.user) {
  document.getElementById("app").innerHTML = `
    <div id="user-button"></div>
  `;

  const userButtonDiv =
    document.getElementById("user-button");

  clerk.mountUserButton(userButtonDiv);
} else {
  document.getElementById("app").innerHTML = `
    <div id="sign-in"></div>
  `;

  const signInDiv =
    document.getElementById("sign-in");

  clerk.mountSignIn(signInDiv);
}

And your index.html file should look something like this:

index.html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Vite App</title>
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/main.js"></script>
  </body>
</html>

Add the ClerkJS package using a <script> tag

This <script> tag will load the ClerkJS package from our CDN and initialize it with your Clerk Publishable Key and Frontend API URL. It should be placed before any other <script> tags that use ClerkJS.

  1. Navigate to the Clerk Dashboard and select your application.
  2. In the navigation sidebar, select API Keys.
  3. In the Quick Copy section, select JavaScript from the dropdown menu.
  4. Copy the <script> tag and paste it into your HTML file.

It should look something like this:

index.html
<script
  async
  crossorigin="anonymous"
  data-clerk-publishable-key="YOUR_PUBLISHABLE_KEY"
  src="https://YOUR_FRONTEND_API_URL/npm/@clerk/clerk-js@latest/dist/clerk.browser.js"
  type="text/javascript"
></script>

In the <script> tag, the onload attribute is used to call the load() method when the ClerkJS package is loaded. This is necessary to initialize ClerkJS. For more information on the load() method and what options you can pass to it, check out the reference documentation.

Listen for the load event

After the ClerkJS package is loaded, you can listen for the load event to ensure that ClerkJS is ready to use.

Below the <script> tag that initializes ClerkJS, add another <script> tag to listen for the load event:

index.html
<script>
  window.addEventListener("load", async function () {
    await Clerk.load();

    console.log("ClerkJS is loaded");
  });
</script>

Allow users to sign in or out

Clerk's prebuilt components are the easiest way to add authentication and user management to your application. They come styled out of the box and are customizable to fit your application's design.

To get started, you will use:

  • <SignIn />: renders a user interface for signing in.
  • <UserButton />: shows the avatar from the account the user is signed in with. When clicked, it opens a dropdown menu with options to sign out.
index.html
<div id="app"></div>

<!-- Initialize Clerk with your
Clerk Publishable key and Frontend API URL -->
<script
  async
  crossorigin="anonymous"
  data-clerk-publishable-key="YOUR_PUBLISHABLE_KEY"
  src="https://YOUR_FRONTEND_API_URL/npm/@clerk/clerk-js@latest/dist/clerk.browser.js"
  type="text/javascript"
></script>

<script>
  window.addEventListener("load", async function () {
    await Clerk.load();

    if (Clerk.user) {
      document.getElementById("app").innerHTML = `
        <div id="user-button"></div>
      `;

      const userButtonDiv = document.getElementById("user-button");

      Clerk.mountUserButton(userButtonDiv);
    } else {
      document.getElementById("app").innerHTML = `
        <div id="sign-in"></div>
      `;

      const signInDiv = document.getElementById("sign-in");

      Clerk.mountSignIn(signInDiv);
    }
  });
</script>

Clerk Class Reference

Learn more about the Clerk class and how to use it.

Authentication Components

Learn more about all our authentication components.

Customization & Localization

Learn how to customize and localize the Clerk components.

Feedback

What did you think of this content?

Last updated on