Skip to main content
Docs

JavaScript Quickstart

Before you start

Example repository

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

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

Use the following tabs to choose your preferred method.

Create a new JavaScript app

To install Clerk's JavaScript SDK, you need to use a bundler like Vite or Webpack.

If you don't already have a JavaScript app, run the following commands to create a new one 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
terminal
pnpm create vite clerk-javascript
cd clerk-javascript
pnpm install
terminal
yarn create vite clerk-javascript
cd clerk-javascript
yarn install
terminal
bunx create-vite clerk-javascript
cd clerk-javascript
bun install

Install @clerk/clerk-js

The Clerk JavaScript SDK gives you access to a set of classes and methods to make user authentication easier.

Run the following command to install the SDK:

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

Set your Clerk API keys

It's recommended to use environment variables to store your Clerk . In JavaScript projects, you can add these values in an .env file and load them into your app using a package like dotenv. For Vite projects, environment variables in an .env file at the project root are automatically accessible through the import.meta.env object.

.env
VITE_CLERK_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY

Initialize Clerk

To initialize Clerk, add the following code to your main.js file. This code imports your , creates a new Clerk instance, and calls the load() method to initialize Clerk.

src/main.js
import { Clerk } from '@clerk/clerk-js'

const publishableKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY

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

Add Clerk components to your app

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

To get started, add the following components to your app:

  • <SignIn />: Renders a user interface for signing in.
  • <UserButton />: Shows the signed-in user's avatar. Selecting it opens a dropdown menu with account management options.

Your main.js file should look something like this:

src/main.js
import { Clerk } from '@clerk/clerk-js'

const publishableKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY

const clerk = new Clerk(publishableKey)
await clerk.load()

if (clerk.isSignedIn) {
  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="/src/main.js"></script>
  </body>
</html>

Run your project

Run your project with the following command:

terminal
npm run dev
terminal
pnpm run dev
terminal
yarn dev
terminal
bun run dev

Create your first user

  1. Visit your app's homepage at http://localhost:5173.
  2. Select "Sign up" on the page and authenticate to create your first user.

Add the SDK using a <script> tag

This <script> tag will load Clerk's JavaScript SDK from our CDN and initialize it with your Clerk and . It should be placed before any other <script> tags that use the JavaScript SDK.

  1. In the Clerk Dashboard, navigate to the API keys page.
  2. In the Quick Copy section, select JavaScript from the dropdown menu.
  3. Copy the <script> tag and paste it into your HTML file, as shown in the following example:
index.html
<!-- Rest of your HTML file -->

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

Listen for the load event

Below the <script> tag that initializes the SDK, create another <script> tag that listens for the load event and call Clerk's load() method to load the SDK, as shown in the following example:

index.html
<!-- Rest of your HTML file -->

<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 app. They come styled out-of-the-box and are customizable to fit your app's design.

To get started, you will use:

  • <SignIn />: renders a user interface for signing in.
  • <UserButton />: Shows the signed-in user's avatar. Selecting it opens a dropdown menu with account management options.
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@5/dist/clerk.browser.js"
  type="text/javascript"
></script>

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

    if (Clerk.isSignedIn) {
      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>

Next steps

Learn more about Clerk components, how to customize them, and how to use Clerk's JavaScript classes using the following guides.

Clerk class reference

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

Prebuilt components

Learn more about Clerk's suite of components that let you quickly add authentication to your app.

Customization & localization

Learn how to customize and localize Clerk components.

JavaScript SDK Reference

Learn more about additional JavaScript methods.

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub