Remix Quickstart

Warning

The Remix SDK is in maintenance mode and will only receive security updates. Please migrate to the React Router SDK for continued development and new features.

Before you start

Set up a Clerk application

Example repository

Remix Quickstart Repo

Learn how to use Clerk to quickly and easily add secure authentication and user management to your Remix app. This guide assumes that you are using Remix v2 or later.

Note

If you are using Remix SPA mode, follow the Remix SPA mode guide.

Create a new Remix app

If you don't already have a Remix app, run the following commands to create a new one.

npm

pnpm

yarn

bun

terminal

npx create-remix@latest clerk-remix
cd clerk-remix
npm install

terminal

pnpm dlx create-remix@latest clerk-remix
cd clerk-remix
pnpm install

terminal

yarn dlx create-remix@latest clerk-remix
cd clerk-remix
yarn install

terminal

bun x create-remix@latest clerk-remix
cd clerk-remix
bun install

Install `@clerk/remix`

The Clerk Remix SDK gives you access to prebuilt components, hooks, and helpers to make user authentication easier.

Run the following command to install the SDK:

npm

pnpm

yarn

bun

terminal

npm install @clerk/remix

terminal

pnpm add @clerk/remix

terminal

yarn add @clerk/remix

terminal

bun add @clerk/remix

Set your Clerk API keys

.env

CLERK_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY
CLERK_SECRET_KEY=YOUR_SECRET_KEY

Configure `rootAuthLoader()`

The rootAuthLoader() function is a helper function that provides the authentication state to your Remix application. You must export rootAuthLoader() as the root loader() function.

Update your root.tsx file with the following code:

app/root.tsx

import type { MetaFunction, LoaderFunction } from '@remix-run/node'
import { Links, Meta, Outlet, Scripts, ScrollRestoration } from '@remix-run/react'

// Import `rootAuthLoader()`
import { rootAuthLoader } from '@clerk/remix/ssr.server'

export const meta: MetaFunction = () => [
  {
    charset: 'utf-8',
    title: 'New Remix App',
    viewport: 'width=device-width,initial-scale=1',
  },
]

// Export `rootAuthLoader()` as the root route `loader`
export const loader: LoaderFunction = (args) => rootAuthLoader(args)

export function Layout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <Meta />
        <Links />
      </head>
      <body>
        {children}
        <ScrollRestoration />
        <Scripts />
      </body>
    </html>
  )
}

export default function App() {
  return <Outlet />
}

Configure `ClerkApp`

Clerk provides a ClerkApp wrapper to provide the authentication state to your React tree. This helper works with Remix SSR out-of-the-box and follows the "higher-order component" paradigm.

Update your root.tsx file with the following code:

app/root.tsx

import type { MetaFunction, LoaderFunction } from '@remix-run/node'

import { Links, Meta, Outlet, Scripts, ScrollRestoration } from '@remix-run/react'

import { rootAuthLoader } from '@clerk/remix/ssr.server'
// Import ClerkApp
import { ClerkApp } from '@clerk/remix'

export const meta: MetaFunction = () => [
  {
    charset: 'utf-8',
    title: 'New Remix App',
    viewport: 'width=device-width,initial-scale=1',
  },
]

export const loader: LoaderFunction = (args) => rootAuthLoader(args)

export function Layout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <Meta />
        <Links />
      </head>
      <body>
        {children}
        <ScrollRestoration />
        <Scripts />
      </body>
    </html>
  )
}

function App() {
  return <Outlet />
}

// Wrap your app with `ClerkApp`
export default ClerkApp(App)

Protect your pages

Client-side

To protect your pages on the client-side, you can use Clerk's prebuilt control components that control the visibility of content based on the user's authentication state.

The following example uses the following components:

<SignedIn>: Children of this component can only be seen while signed in.
<SignedOut>: Children of this component can only be seen while signed out.
<UserButton />: Shows the signed-in user's avatar. Selecting it opens a dropdown menu with account management options.
<SignInButton />: An unstyled component that links to the sign-in page. In this example, since no props or environment variables are set for the sign-in URL, this component links to the Account Portal sign-in page.
<SignUpButton />: An unstyled component that links to the sign-up page. In this example, since no props or environment variables are set for the sign-up URL, this component links to the Account Portal sign-up page.

routes/_index.tsx

import { SignInButton, SignUpButton, SignedIn, SignedOut, UserButton } from '@clerk/remix'

export default function Index() {
  return (
    <div>
      <h1>Index Route</h1>
      <header>
        {/* Show the sign-in and sign-up buttons when the user is signed out */}
        <SignedOut>
          <SignInButton />
          <SignUpButton />
        </SignedOut>
        {/* Show the user button when the user is signed in */}
        <SignedIn>
          <UserButton />
        </SignedIn>
      </header>
    </div>
  )
}

To protect your routes, use the getAuth() function in your loader. This function retrieves the authentication state from the request object, returning an Auth object that includes the isAuthenticated, allowing you to determine if the user is authenticated.

routes/_index.tsx

import { UserButton } from '@clerk/remix'
import { getAuth } from '@clerk/remix/ssr.server'
import { LoaderFunction, redirect } from '@remix-run/node'

export const loader: LoaderFunction = async (args) => {
  const { isAuthenticated } = await getAuth(args)
  if (!isAuthenticated) {
    return redirect('/sign-in')
  }
  return {}
}

export default function Index() {
  return (
    <div>
      <h1>Index route</h1>
      <p>You are signed in!</p>
      <UserButton />
    </div>
  )
}

Run your project

Run your project with the following command:

npm

pnpm

yarn

bun

terminal

npm run dev

terminal

pnpm run dev

terminal

yarn dev

terminal

bun run dev

Create your first user

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

Edit on GitHub

Remix Quickstart

Before you start

Example repository

Create a new Remix app

Install `@clerk/remix`

Set your Clerk API keys

Configure `rootAuthLoader()`

Configure `ClerkApp`

Protect your pages

Client-side

Server-side

Run your project

Create your first user

Next steps

Create a custom sign-in-or-up page

Protect content and read user data

Customization & localization

Prebuilt components

Remix Quickstart

Before you start

Example repository

Feedback