mcpField
T
tanstack-start-auth

tanstack-start-auth

github.com/fixmyberlinDevelopment043 installsUpdated 1d ago
Repository

About tanstack-start-auth

A reference skill for configuring Better Auth and integrating it with TanStack Start. It is intended for developers working on FMC apps and emphasizes request-scoped session handling and separate route and data authorization.

Key features

  1. 01Better Auth configuration guidance
  2. 02TanStack Start route and cookie wiring
  3. 03Session and server-function patterns
  4. 04API key and session authorization
  5. 05Reference files for auth patterns

Use cases

  1. 01Set up Better Auth in a TanStack Start app
  2. 02Protect routes and API handlers
  3. 03Implement session checks in server functions

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/fixmyberlin/fixmyskills --skill tanstack-start-auth

After installing, type/tanstack-start-authin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

references/
auth.md
better-auth-config.md
endpoint-auth-lint.md

Details

From the project README

TanStack Start + Better Auth

Single skill for library configuration and Start-specific wiring in FMC apps (TILDA, Trassenscout migration, etc.).

When to apply

  • Creating or changing betterAuth() / createAuthClient() config
  • Mounting /api/auth/*, tanstackStartCookies() plugin, OAuth sign-in routes
  • beforeLoad gates, endpointAuth, session in server functions or API handlers
  • Public vs protected server functions (public*.functions.ts naming)
  • API key + session dual auth on automation endpoints

References (read as needed)

TopicFile
TanStack routes, cookies, session helpers, TILDA patternsreferences/auth.md
Trassenscout auth lint patternreferences/endpoint-auth-lint.md
betterAuth options, DB, plugins, sessions, hooksreferences/better-auth-config.md

Live docs: better-auth.com/docs · llms.txt

Related skills

  • tanstack-router-conventions — validateSearch, search serialization, loaders + Query
  • tanstack-start-conventions — layout, .server.ts / .functions.ts, boundaries, SSR
  • playwright-skill — E2E stubbed auth (TILDA)

Non-negotiable rules

  1. Session helpers always receive headers: Headers from the current request.
  2. Route beforeLoad does not call DB/session directly — server functions + getRequestHeaders().
  3. Use official tanstackStartCookies() as the last plugin; verify no client-bundle leak after better-auth version changes (auth.md).
  4. /api/auth/$ and other handler-only API routes: ssr: false (selective-ssr.md).
  5. API routes: auth inside each handler (no route-level beforeLoad).
  6. Admin/role checks with cookie cache: getSession({ query: { disableCookieCache: true } }).
  7. Compare API secrets with timing-safe equality.
  8. Two layers: beforeLoad = route UX only; endpointAuth / guards = data boundary. Never rely on beforeLoad alone.
  9. No auth middleware for route guarding — use layout beforeLoad. Global auth middleware breaks public RPCs (public*.functions.ts, getSessionForRouteFn) and is not the FMC auth-route pattern.

Quick patterns

// beforeLoad (via server fn)
await routeSessionFn({ data: location })

// API handler
const session = await endpointAuth.session(request.headers)

// Server function
const headers = getRequestHeaders()
await endpointAuth.admin(headers)

Setup snapshot

  1. betterAuth() in auth.server.ts (Prisma/Drizzle adapter, plugins)
  2. createAuthClient() with matching client plugins
  3. /api/auth/$ → auth.handler(request) (cookies via tanstackStartCookies() plugin)
  4. session.server.ts helpers taking Headers
  5. CLI migrate/generate after plugin changes — details in better-auth-config.md

Comments

Markdown supported