Skip to main content
Articles

Add Clerk authentication to a TanStack Start app with the Clerk CLI - Part 2

Author: Roy Anger
Published: (last updated )

Part 2 of 2. Start with Add Clerk authentication to a TanStack Start app with the Clerk CLI.

How do I wire up Clerk UI components and configure settings in TanStack Start?

This is part 2 of a two-part series on adding Clerk authentication to a TanStack Start app using the Clerk CLI. This part focuses on wiring up the landing page UI, starting the dev server, and performing operational tasks using the Clerk CLI such as configuring instance settings and querying the instance via clerk api.

Wire up the landing page

clerk init deliberately leaves src/routes/index.tsx alone — it's your landing page, and the CLI doesn't make assumptions about your layout. That means out of the box the app has no sign-in affordance on the home page. Add one:

import { Show, SignInButton, SignUpButton, UserButton } from '@clerk/tanstack-react-start'
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/')({ component: Home })

function Home() {
  return (
    <div className="p-8">
      <header className="mb-8 flex items-center justify-end gap-3">
        <Show when="signed-out">
          <SignInButton mode="modal" />
          <SignUpButton mode="modal" />
        </Show>
        <Show when="signed-in">
          <UserButton />
        </Show>
      </header>
      <h1 className="text-4xl font-bold">Welcome to TanStack Start</h1>
      <p className="mt-4 text-lg">
        Edit <code>src/routes/index.tsx</code> to get started.
      </p>
    </div>
  )
}

Important

Clerk Core 3 (released 2026-03-03) removed <SignedIn>, <SignedOut>, and <Protect> and replaced them with a single <Show> component. Any older TanStack Start tutorial you find on the internet still showing <SignedIn> / <SignedOut> is pre-Core-3 — port it. The Core 3 upgrade guide has a npx @clerk/upgrade codemod that handles most call sites automatically.

This is the minimum viable landing page. The mode="modal" prop opens the sign-in/sign-up components in a modal rather than routing to /sign-in or /sign-up. Drop mode="modal" if you prefer full-page navigation to the catch-all routes clerk init generated.

Start the dev server and sign up a test user

pnpm dev

Open http://localhost:3000. You should see the "Welcome to TanStack Start" header with Sign in / Sign up buttons in the top right. Click Sign up, run through the flow, and you'll land back on the home page with a <UserButton /> in place of the sign-in/sign-up pair.

If the buttons don't render, two things to check before anything else:

  1. Restart the dev server. Vite caches aggressively and new env vars don't always hot-reload.
  2. clerk doctor. Missing publishable key is the single most common cause, and doctor catches it in one shot.

Configure Clerk as code: clerk config

clerk config treats your Clerk instance configuration as data. You can pull the current state, diff it, patch fields, and audit the result. It's the same surface whether you're on dev or prod — add --instance prod when you're ready to push changes upstream.

Start by inspecting the schema:

clerk config schema
clerk config schema --keys auth_passkey session auth_attack_protection

clerk config schema prints the entire config surface. --keys scopes it — useful when you know the key names and just want the shape.

Pull the current config as a baseline:

clerk config pull --output config.before.json

Four patches follow. Run each --dry-run first; the dry run prints the exact shape that would be sent without making changes. Drop --dry-run and add --yes to commit.

Patch 1: block disposable email domains (no paid-plan gate):

clerk config patch --dry-run --json '{"auth_access_control":{"block_disposable_email_domains":true}}'
clerk config patch --json '{"auth_access_control":{"block_disposable_email_domains":true}}' --yes

Patch 2: tighten lockout to 10 failed attempts (no paid-plan gate — the default is 100):

clerk config patch --dry-run --json '{"auth_attack_protection":{"user_lockout":{"max_attempts":10}}}'
clerk config patch --json '{"auth_attack_protection":{"user_lockout":{"max_attempts":10}}}' --yes

Patch 3: enable passkeys as a sign-in factor (paid plan required):

clerk config patch --dry-run --json '{"auth_passkey":{"used_for_sign_in":true}}'
clerk config patch --json '{"auth_passkey":{"used_for_sign_in":true}}' --yes

Important

Passkeys can be registered on any plan; using them as a sign-in factor is a paid-plan feature. The used_for_sign_in: true flip is what unlocks the sign-in affordance in the <SignIn /> component. See pricing.

Patch 4: tune session config (paid plan required):

clerk config patch --dry-run --json '{"session":{"allowed_clock_skew":5,"claims":{},"lifetime":3600}}'
clerk config patch --json '{"session":{"allowed_clock_skew":5,"claims":{},"lifetime":3600}}' --yes

allowed_clock_skew tolerates small time drift between client and server (seconds). claims is where you inject custom session claims. lifetime is the session token lifetime in seconds (3600 = 1 hour).

Important

Session config changes are gated on a paid plan. If you hit a 403 on this patch, that's the plan gate — not a CLI bug.

Pull the new config and diff it:

clerk config pull --output config.after.json
diff config.before.json config.after.json

You should see four blocks: block_disposable_email_domains flipped, max_attempts dropped from 100 to 10, used_for_sign_in flipped to true, and a full session object materialized (it was null before Patch 4).

Warning

clerk config put replaces your entire config with the contents of a JSON file. It's destructive — use patch for day-to-day changes. put is for bootstrapping a new environment from a template, not for tuning.

Verify the config changes worked

Reload the app and walk the sign-up flow again. A few things to confirm:

  • Disposable-email blocking. Try signing up with a @mailinator.com address. The signup should be rejected at the email step.
  • Lockout. Fail sign-in 10 times on purpose. The account should lock.
  • Passkey sign-in. Sign in with your test user, open <UserProfile /> (add a /user route rendering <UserProfile /> if you don't have one yet), go to the Security tab, and register a passkey. Sign out, then sign in again — "Continue with passkey" should appear above the email field. Validated with platform authenticators (Touch ID, Windows Hello) and Bitwarden.
  • Session lifetime. Signed-in sessions now expire after 1 hour instead of the default. Easy to verify in a long-running tab; easy to forget in dev unless you leave one open.

Inspect your instance with clerk api

clerk api is a direct wrapper around the Clerk Backend API and (with --platform) the Clerk Platform API. It authenticates with your linked app's keys, so you don't need to craft curl commands or copy CLERK_SECRET_KEY into Postman.

List available endpoints and commands:

clerk api ls
clerk api ls users

List users:

clerk api /users
clerk api /users?limit=5

Fetch a single user:

clerk api /users/<user_id>

The Platform API (cross-instance application management) lives behind --platform. The CLI auto-prepends /v1 and points at the Platform API host (api.clerk.com). Platform resources are namespaced under /platform/, so the full path for listing applications is /platform/applications — the CLI resolves this to api.clerk.com/v1/platform/applications:

clerk api --platform /platform/applications

Backend API calls (no --platform) hit api.clerk.dev instead, and their paths do not need the /platform/ prefix — /users resolves to api.clerk.dev/v1/users, /organizations to api.clerk.dev/v1/organizations.

Note

If a --platform call returns clerk_key_invalid, the usual cause is a missing auth token rather than a bad path — clerk api --platform uses the OAuth token from clerk auth login, not CLERK_SECRET_KEY. Re-run clerk auth login if the token has expired. If you get 404, double-check the path against the Platform API spec: Platform resources need the /platform/ segment, Backend resources do not.

clerk api isn't a replacement for the full Backend SDK in application code — it's for one-off inspection, ops, and scripts.

Appendix: what clerk init wrote for you

If you ever need to reproduce clerk init's output by hand — porting to a non-supported framework, or just curious — here's the exact surface. Validated against TanStack Start 1.167.42 + @clerk/tanstack-react-start@1.1.5.

package.json — one dependency added:

{
  "dependencies": {
    "@clerk/tanstack-react-start": "^1.1.5"
  }
}

src/routes/__root.tsx — existing content wrapped in <ClerkProvider> (reformatted by pnpm format):

import { ClerkProvider } from '@clerk/tanstack-react-start'
import { HeadContent, Scripts, createRootRoute } from '@tanstack/react-router'
import { TanStackRouterDevtoolsPanel } from '@tanstack/react-router-devtools'
import { TanStackDevtools } from '@tanstack/react-devtools'

import appCss from '../styles.css?url'

export const Route = createRootRoute({
  head: () => ({
    meta: [
      { charSet: 'utf-8' },
      { name: 'viewport', content: 'width=device-width, initial-scale=1' },
      { title: 'TanStack Start Starter' },
    ],
    links: [{ rel: 'stylesheet', href: appCss }],
  }),
  shellComponent: RootDocument,
})

function RootDocument({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <HeadContent />
      </head>
      <body>
        <ClerkProvider>
          {children}
          <TanStackDevtools
            config={{ position: 'bottom-right' }}
            plugins={[
              {
                name: 'Tanstack Router',
                render: <TanStackRouterDevtoolsPanel />,
              },
            ]}
          />
          <Scripts />
        </ClerkProvider>
      </body>
    </html>
  )
}

src/routes/sign-in.$.tsx (new) — catch-all route so <SignIn /> handles any sub-path (Clerk uses this for flow steps like /sign-in/factor-two):

import { SignIn } from '@clerk/tanstack-react-start'
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/sign-in/$')({
  component: Page,
})

function Page() {
  return (
    <div className="flex min-h-screen items-center justify-center">
      <SignIn />
    </div>
  )
}

src/routes/sign-up.$.tsx (new) — mirror of sign-in for sign-up:

import { SignUp } from '@clerk/tanstack-react-start'
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/sign-up/$')({
  component: Page,
})

function Page() {
  return (
    <div className="flex min-h-screen items-center justify-center">
      <SignUp />
    </div>
  )
}

src/start.ts (modified) — Clerk's request middleware slotted into TanStack Start's server instance (TanStack's scaffold creates this file; clerk init adds the clerkMiddleware() call and the @clerk/tanstack-react-start/server import):

import { clerkMiddleware } from '@clerk/tanstack-react-start/server'
import { createStart } from '@tanstack/react-start'

export const startInstance = createStart(() => {
  return {
    requestMiddleware: [clerkMiddleware()],
  }
})

This is the TanStack Start equivalent of Next's proxy.ts / middleware — the hook-point where Clerk resolves the session for every server-side request. createStart takes a callback that returns the config, not a plain object. clerkMiddleware() populates the request context that auth() from @clerk/tanstack-react-start/server reads inside server functions and loaders, so you can gate them with beforeLoad or by checking userId from await auth() before returning data.

.env.local — the four route URL vars come from the framework scaffold step, the two key vars come from clerk init's built-in env pull (real values land whenever you pre-link an app with clerk link --app <id> or pick an app at the interactive prompt):

VITE_CLERK_SIGN_IN_URL=/sign-in
VITE_CLERK_SIGN_UP_URL=/sign-up
VITE_CLERK_SIGN_IN_FALLBACK_REDIRECT_URL=/
VITE_CLERK_SIGN_UP_FALLBACK_REDIRECT_URL=/

# Clerk
VITE_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...

What clerk init does not touch: src/routes/index.tsx (landing page), vite.config.ts, src/router.tsx, src/styles.css, README.md. That's why the "wire up the landing page" step exists — you're filling in the piece the CLI intentionally left under your control.

CLI reference (quick skim)

Commands the article touched:

CommandWhat it does
clerk auth loginOAuth login, persists to the OS-standard CLI config directory (override with CLERK_CONFIG_DIR).
clerk whoamiShow current user + linked app.
clerk apps listList apps in your org (add --json for machine-readable output).
clerk apps create <name>Create a new app from the CLI.
clerk init --framework tanstack-startInstall SDK + wire providers/routes/middleware. Auto-detects framework/package manager when the flag is omitted.
clerk link --app app_xxxPoint the CLI at an existing app (run before clerk init to skip the app-picker).
clerk unlinkUnlink the current app (add --yes to skip the confirmation prompt).
clerk env pullWrite env vars to .env.local (or .env.production.local with --instance prod; target a specific app with --app <id>).
clerk doctorValidate auth + linked app + env vars.
clerk config schemaPrint the full config schema.
clerk config pull --output file.jsonSnapshot current config.
clerk config patch --json '...' --dry-runPreview a partial update.
clerk config patch --json '...' --yesCommit the update.
clerk config put --file file.jsonDestructive — replace config from file.
clerk api /usersQuery the Clerk Backend API at api.clerk.dev (CLI auto-prepends /v1).
clerk api --platform /platform/applicationsQuery the Platform API at api.clerk.com (CLI auto-prepends /v1; Platform resources live under /platform/).
clerk completion zshPrint shell completion (pipe to your completion dir).
npx skills add clerk/skillsInstall/refresh the Clerk agent skills. Run inside clerk init or manually.

Flags worth memorizing:

  • --yes / -y — non-interactive; accept defaults.
  • --dry-run — print the operation without executing (config patch, config put, api).
  • --instance prod — target production instead of dev.
  • --app app_xxx — scope the command to a specific app (valid on link, env pull, config *, api — not on init).
  • --no-skills — skip the agent-skills prompt inside clerk init.

To upgrade the CLI itself, rerun the installer (curl -fsSL https://clerk.com/install | sh, clerk update, or npm install -g clerk@latest). There is no clerk update subcommand in 1.0.2.

Full reference: Clerk CLI docs.

Further reading

Conclusion

In this series, we used the Clerk CLI to add authentication to a TanStack Start application. We covered scaffolding the app, running clerk init, pulling environment variables, verifying the setup, adding the UI components, and managing Clerk instance configurations as code.

FAQ

In this series

  1. Add Clerk authentication to a TanStack Start app with the Clerk CLI
  2. Add Clerk authentication to a TanStack Start app with the Clerk CLI - Part 2 (you are here)