# Next.js boilerplate with Clerk

> Hosted authentication: Clerk's sign-in, sign-up and account settings, restyled with your design's tokens in light and dark, with Google, GitHub and Microsoft switched on from the Clerk dashboard. With a database selected, a Svix-signed webhook mirrors users into your own tables.

Hosted auth with prebuilt sign-in UI in your design's colours and a user sync webhook.

- **Category:** Sign in
- **Pricing:** Free Hobby plan up to 50,000 monthly retained users per app. Pro is $25/month, or $20/month billed yearly, then $0.02 per extra user. MFA needs Pro. Pro includes one enterprise SSO connection.
- **Best for:** Teams who want finished auth UI and Clerk's hosted user dashboard on day one, with organisations there when they need them. The trade: the user record lives in Clerk's database. With a database selected, a webhook keeps a copy in yours.
- **Conflicts with:** better-auth, supabase-auth
- **Vendor docs:** https://clerk.com/docs/nextjs/getting-started/quickstart

## Trade-offs

- Prebuilt <SignIn /> and <SignUp /> components cover email, OAuth and account management out of the box. MFA needs the Pro plan.
- Users live in Clerk, not in your Postgres. Anything that joins users to your tables needs the webhook mirror this battery ships with a database. The mirror is eventually consistent: a signup can reach your app a beat before the webhook lands.
- Roles live in publicMetadata by default. Convenient, but it is vendor state. Moving to a local roles table later is a migration, not a config change.
- Every server render that needs auth runs behind clerkMiddleware. Forget the proxy matcher and auth() throws at runtime instead of failing the build.
- Pricing counts monthly retained users: people who come back 24+ hours after signing up. A large free consumer product costs more here than self-hosted auth.
- Lock-in is real but bounded. Clerk exports users, and with a database selected this battery already keeps a copy in your own tables, keyed on your own id.

## Known fixes it ships

- [Clerk impersonation, the act claim, and what to lock while it is on](https://agenticboilerplate.com/cookbook/clerk/clerk-impersonation-and-the-act-claim): When an admin signs in as a user from the Clerk dashboard, the session token carries an act claim. Read it on the server, show a banner, and refuse account changes until it ends.
- [Protecting route handlers is not the same as protecting pages](https://agenticboilerplate.com/cookbook/clerk/protecting-handlers-vs-pages): A redirect is the right answer for a page and a terrible answer for fetch. Use 401 and 403 in route handlers, and never let the proxy be the only check.
- [Clerk roles: publicMetadata or your own table?](https://agenticboilerplate.com/cookbook/clerk/roles-publicmetadata-vs-local-table): publicMetadata is free and instant but vendor state you cannot join on. A local roles table joins and audits but must be kept in sync. Pick per what you need to query.
- [Make Clerk's sign-in look native, in light and dark, with CSS variables](https://agenticboilerplate.com/cookbook/clerk/styling-clerk-with-css-variables): Point Clerk's appearance variables at your design's CSS custom properties so the prebuilt components follow your theme and your dark mode, with no copied hex values.
- [Testing a Clerk webhook locally without a tunnel round trip](https://agenticboilerplate.com/cookbook/clerk/testing-clerk-webhooks-locally): Sign the payload yourself and POST it at localhost. You get replays, retry ids and bad-signature cases in one second instead of thirty.
- [The proxy matcher that also matches your static assets](https://agenticboilerplate.com/cookbook/clerk/the-matcher-that-ate-your-static-assets): A matcher like "/(.*)" runs auth on every CSS file, image and font. The symptoms are an unstyled site, a redirect loop, or a surprising invocation bill.
- [Clerk user-sync webhooks: duplicates, retries and out-of-order events](https://agenticboilerplate.com/cookbook/clerk/webhook-idempotency-and-ordering): Svix retries and can deliver twice, and updates can arrive before creates. Make the write idempotent on the user id and reject stale payloads by timestamp.

## Generate it

[Build a repo with Clerk](https://agenticboilerplate.com/build?b=clerk)

---

Agentic Boilerplate: A Next.js repo your agent already knows. Free during launch, then $99 once.

- Site map for agents: https://agenticboilerplate.com/llms.txt
- Public API: https://agenticboilerplate.com/openapi.json
- Contact: agenticstudio@gmail.com