What is Tanstack Starter

TanStack Starter is a minimal starter template designed for building applications using TanStack Start with Supabase authentication. It is a fork of the dotnize/tanstarter project.

Use cases

Use cases for TanStack Starter include building single-page applications (SPAs), dashboards, and any application that requires user authentication and data management through Supabase.

How to use

To use TanStack Starter, clone the repository, install dependencies, set up your Supabase credentials in a .env file, and run the development server. Follow the instructions in the README for database seeding and authentication setup.

Key features

Key features include integration with React 19, TanStack Start, Router, Query, Tailwind CSS v4, and Supabase for authentication and database management with server-side rendering.

Where to use

TanStack Starter can be used in web application development, particularly for projects that require user authentication and real-time database interactions.

TanStack Starter

A minimal starter template for 🏝️ TanStack Start with Supabase authentication, forked from dotnize/tanstarter.

• React 19 + React Compiler
• TanStack Start + Router + Query
• Tailwind CSS v4 + shadcn/ui
• Supabase Authentication and Database with SSR

Getting Started

1. Clone this repository:

   git clone https://github.com/mwolf1989/tanstack-starter.git
   

2. Install dependencies:

   pnpm install # npm install
   

3. Create a .env file based on .env.example and add your Supabase credentials:

   VITE_SUPABASE_URL=your_supabase_project_url
   VITE_SUPABASE_ANON_KEY=your_supabase_anon_key
   SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key
   

4. Run the development server:

   pnpm dev # npm run dev
   

   The development server should be now running at http://localhost:3000.

Database Seeding

This template includes a database seeding system using Supabase. To seed the database with sample data:

1. Link your project (if not already linked):

   pnpm supabase link --project-ref your-project-ref
   

2. Run the seed command:

   pnpm db:seed
   

This will reset your database and apply the seed data defined in supabase/seed.sql. The seed file includes sample todos that you can use as a starting point.

Note: The seed data uses a placeholder user ID. You’ll need to replace the user IDs in supabase/seed.sql with actual user IDs from your Supabase auth system.

Authentication with Supabase

This template uses Supabase for authentication with server-side rendering (SSR) support. Key features:

• Server-side authentication using @supabase/ssr
• Proper cookie handling for authentication tokens
• Protected routes with automatic redirection
• Email/Password and OAuth authentication support
• Type-safe authentication functions

Authentication Flow

1. Sign In: Server-side authentication with proper cookie management

   const signInFn = createServerFn()
     .validator((d) => d as SignInCredentials)
     .handler(async ({ data }) => {
       const supabase = getSupabaseServerClient();
       const { error } = await supabase.auth.signInWithPassword(data);
       // Cookies are automatically handled
       return error ? { error: true } : { success: true };
     });
   

2. Protected Routes: Automatic authentication checks and redirects

   export const Route = createFileRoute("/dashboard")({
     loader: async ({ context }) => {
       const result = await context.queryClient.fetchQuery({
         queryKey: ["dashboard-auth"],
         queryFn: () => checkAuth(),
       });
       if (!result.authenticated) {
         throw redirect({ to: "/signin" });
       }
       return { user: result.user };
     },
   });
   

Model Context Protocol (MCP)

This template includes support for the Model Context Protocol (MCP), which allows AI tools to interact with your Supabase database using natural language commands. To set up MCP:

1. Create a .cursor directory in your project root if it doesn’t exist
2. Create a .cursor/mcp.json file with the following configuration:

   {
     "mcpServers": {
       "supabase": {
         "command": "npx",
         "args": [
           "-y",
           "@modelcontextprotocol/server-postgres",
           "<connection-string>"
         ]
       }
     }
   }
   

3. Replace <connection-string> with your Supabase database connection string from your project’s Connection settings

Once configured, you can use AI tools to:

• Query your database using natural language
• Create and modify tables
• Perform SQL operations
• Get insights about your data structure

For more information, read the Supabase MCP Article.

Issue watchlist

• React Compiler docs, Working Group - React Compiler is still in beta. You can disable it in app.config.ts if you prefer.
• https://github.com/TanStack/router/discussions/2863 - TanStack Start is currently in beta and may still undergo major changes.
• https://github.com/shadcn-ui/ui/discussions/6714 - We’re using the canary version of shadcn/ui for Tailwind v4 support.

Scripts

These scripts in package.json use pnpm by default, but you can modify them to use your preferred package manager.

• ui - The shadcn/ui CLI. (e.g. pnpm ui add button to add the button component)
• format and lint - Run Prettier and ESLint.

Building for production

Read the hosting docs for information on how to deploy your TanStack Start app.

Acknowledgements

• dotnize/tanstarter - The original template this project is based on
• nekochan0122/tanstack-boilerplate - A batteries-included TanStack Start boilerplate that inspired some patterns
• Supabase Auth Helpers for SSR authentication implementation