Docs

JavaScript Quickstart

You will learn the following:

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

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.

Set up a JavaScript app using Vite

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

For this tutorial, run the following commands to create a JavaScript app 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

Run the following command to add the JavaScript SDK to your project:

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

Set your Clerk API keys

It's recommended to use environment variables to store your Clerk Publishable Key. 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

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 Clerk

To initialize Clerk, import the Clerk class and instantiate it with your Clerk Publishable Key. Then, call the load() method, as shown in the following example:

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
})

Note

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

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:

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>

Create your first user

Run your project with the following command:

terminal
npm run dev
terminal
yarn dev
terminal
pnpm dev

Now visit your app's homepage at http://localhost:5173. Sign up 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 Publishable Key and Frontend API URL. 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@latest/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@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>

More resources

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?
Edit this page on GitHub

Last updated on