TanStarter Documentation

TanStarter is a minimal starter template for TanStack Start featuring the following stack:

• Core: React 19 + React Compiler, TanStack Start, TanStack Router, TanStack Query.
• Styling: Tailwind CSS, shadcn/ui, Base UI.
• Runtime/Build: Vite 8, Nitro v3, Vite Plus (vp).
• Database/ORM: Drizzle ORM, PostgreSQL.
• Authentication: Better Auth.
• Linting/Formatting: Oxlint, Oxfmt.

To use this template, ensure you have the following installed:

• Node.js >= 24
• pnpm >= 11
• Vite Plus (vp)

Note: This template uses pnpm by default and requires Vite+ vp to be installed.

After scaffolding your project, follow these steps to complete the setup:

1. Environment Variables: Create a .env file based on the provided .env.example file in your project root.
2. Database Migrations: Generate and apply your initial Drizzle ORM migrations using the vpr CLI:
   • vpr db generate to generate the migration.
   • vpr db migrate to apply it to your database.
3. Development Server: Start the local development server with:

   vpr dev

   The server will be available at `http://localhost:3000`.

When you need access to the authenticated user's data within other loaders or beforeLoad hooks, do not rely on passing the user object through the router context. Instead, use authQueryOptions() in conjunction with context.queryClient.

This pattern leverages TanStack Query's centralized revalidation and caching, ensuring that authentication state is consistent across the application and minimizing unnecessary client-to-server calls.

// Example pattern for accessing auth data in a child route
const user = await context.queryClient.ensureQueryData({
  ...authQueryOptions(),
  revalidateIfStale: true,
});

The docker-compose.yml file defines a db service using the postgres:alpine image. This service is used to provide a local PostgreSQL database instance for the TanStarter application.

Key configuration details:

• Port: Maps host port 5432 to container port 5432.
• Persistence: Uses a named volume postgres_data_tanstarter mapped to /var/lib/postgresql to ensure data persists across container restarts.
• Credentials:
  • POSTGRES_USER: postgres
  • POSTGRES_PASSWORD: password
  • POSTGRES_DB: tanstarter

services:
  db:
    image: postgres:alpine
    ports:
      - 5432:5432
    volumes:
      - postgres_data_tanstarter:/var/lib/postgresql
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=tanstarter

volumes:
  postgres_data_tanstarter:

TanStarter uses the vpr CLI to wrap common tasks. Use these commands to manage your project:

Dependency Management

• vpr deps: Selectively upgrade dependencies using taze.
• vpx taze@latest -Ilw --maturity-period 3: An alternative way to upgrade packages.

Database and Auth

• vpr db <command>: Run drizzle-kit commands (e.g., vpr db generate, vpr db studio).
• vpr auth:generate: Regenerate the auth database schema located at src/lib/db/schema/auth.schema.ts if you have modified your Better Auth configuration.

UI and Code Quality

• vpr ui <command>: Access the shadcn/ui CLI (e.g., vpr ui add button).
• vpr check: Run both Oxfmt and Oxlint for formatting and linting.
• vpr format: Run Oxfmt.
• vpr lint: Run Oxlint.

vpr db generate
vpr db migrate
vpr dev
vpr ui add button
vpr check
vpr deps

Use authMiddleware to enforce authentication on server requests and server functions. This middleware checks for an active user session and, if found, injects the user object into the request context. If no user is found, it sets the response status to 401 and throws an "Unauthorized" error.

This middleware utilizes the cookieCache option from your auth configuration (defaulting to 5 minutes in this template), making it suitable for route-level data fetching where slight staleness is acceptable in exchange for reduced database load.