TanStack Starter is a batteries-included starter template for TanStack Start that combines routing, server functions, and full-stack React development with essential production features.
The template integrates Drizzle ORM for type-safe database operations, Better Auth for authentication with multiple OAuth providers, shadcn/ui for component styling, and i18next for internationalization.
Features
Full-Stack React Framework: Built on TanStack Start for server-side rendering, routing, and server functions in a unified React application.
Type-Safe ORM Integration: Uses Drizzle ORM to define database schemas with TypeScript types that propagate through your entire application.
Multi-Provider Authentication: Better Auth implementation supports Discord, Google, and GitHub OAuth out of the box with JWT session management.
Production-Ready UI Components: shadcn/ui components provide accessible, customizable building blocks styled with Tailwind CSS.
Internationalization Support: i18next handles multi-language content with React Suspense boundaries for loading states.
Flexible Runtime Support: Compatible with Node.js, Bun, Deno, or Docker containers for development and deployment.
Use Cases
SaaS Application Foundation: The template provides user authentication, database persistence, and internationalization required for multi-tenant applications. You can extend the user schema with subscription models and start building your core features without authentication boilerplate.
Internal Tools with SSO: The OAuth provider integration makes this template suitable for building internal dashboards or admin panels that authenticate against your organization’s identity provider. The Better Auth configuration accepts custom OAuth endpoints beyond the included social providers.
Content Management Systems: The combination of Drizzle ORM’s migration system and shadcn/ui’s form components accelerates development of content editing interfaces. The i18next integration supports content localization across multiple languages with minimal code changes.
API-First Applications: TanStack Start’s server function architecture lets you build API endpoints with the same TypeScript functions you use for server-side rendering. The template’s authentication layer protects these endpoints while Drizzle handles data validation at the database boundary.
How to Use It
The template requires a PostgreSQL database and OAuth credentials from your chosen authentication providers. You’ll configure environment variables, run database migrations, and start the development server with your preferred JavaScript runtime.
1. Install one of these runtimes on your development machine. The template supports Node.js version 18 or higher, Bun 1.0 or higher, Deno 1.37 or higher, or Docker with Docker Compose. Each runtime executes the same application code with runtime-specific package managers for dependency installation.
dockernodedenobun
2. Create a .env file in the root of the project and populate it with the necessary credentials and configuration.
Set APP_PORT and APP_HOST for the main application server, NITRO_PORT for the Nitro backend, and VITE_APP_PORT for the Vite development server. The VITE_BASE_URL defines your application’s public URL for OAuth callbacks.
Configure database connection parameters with DATABASE_URL as a PostgreSQL connection string or separate variables for DATABASE_HOST, DATABASE_PORT, DATABASE_NAME, DATABASE_USER, and DATABASE_PASSWORD. The DATABASE_SCHEMA variable defaults to “public” but you can specify a custom schema for multi-tenant setups.
Better Auth requires three variables. Set BETTER_AUTH_URL to match your VITE_BASE_URL, generate a random string for BETTER_AUTH_SECRET (use openssl rand -base64 32), and create another random string for BETTER_AUTH_JWT_SECRET to sign JSON Web Tokens.
Each OAuth provider needs a client ID and secret. Register your application with Discord, Google, or GitHub to obtain these credentials. Set DISCORD_CLIENT_ID and DISCORD_CLIENT_SECRET for Discord authentication, GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET for Google, and GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET for GitHub. The Better Auth documentation provides specific instructions for configuring OAuth callbacks with each provider.
# app config - see https://nitro.build/config and https://vite.dev/config/
APP_PORT=
APP_HOST=
NITRO_PORT=
VITE_APP_PORT=
VITE_BASE_URL=
VITE_NITRO_PRESET=
VITE_COOKIE_EXPIRY_DATE=
# database credentials - see https://hub.docker.com/_/postgres#environment-variables
DATABASE_URL=
DATABASE_NAME=
DATABASE_USER=
DATABASE_PORT=
DATABASE_HOST=
DATABASE_SCHEMA=
DATABASE_PASSWORD=
# auth config - see https://www.better-auth.com/docs/installation
BETTER_AUTH_URL=
BETTER_AUTH_SECRET=
BETTER_AUTH_JWT_SECRET=
# discord oauth - see https://www.better-auth.com/docs/authentication/discord
DISCORD_CLIENT_ID=
DISCORD_CLIENT_SECRET=
# google oauth - see https://www.better-auth.com/docs/authentication/google
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
# github oauth - see https://www.better-auth.com/docs/authentication/github
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
3. The template requires a running PostgreSQL instance before you execute migrations. If you have Docker installed, run docker compose -f docker-compose.yaml up --build -d to start a containerized PostgreSQL database with the configuration from your .env file. The Docker Compose configuration mounts a volume for persistent data storage across container restarts.
You can also connect to an existing PostgreSQL server by updating the database connection variables in your .env file. Ensure your database user has permissions to create tables and run migrations in the specified schema.
4. Install dependencies and launch the development server. The commands are slightly different depending on your chosen package manager.
NPM
Execute npm install && npx drizzle-kit migrate && npm run dev. The installation pulls all package dependencies, the migration command applies database schema changes, and the dev command starts both the Vite development server and Nitro backend.
PNPM
Run pnpm install && pnpm exec drizzle-kit migrate && pnpm dev. This follows the same pattern with pnpm’s faster dependency resolution and stricter package hoisting.
Deno
Use deno install && deno run -A npm:drizzle-kit migrate && deno task dev. The -A flag grants all permissions to the Drizzle migration runner. Deno’s npm compatibility layer executes the migration tooling.
Bun
Execute bun install && bunx drizzle-kit migrate && bun run dev. Bun’s native JavaScript runtime provides faster cold starts compared to Node.js-based alternatives.
Windows PowerShell
Chain these commands with error checking. For npm: npm install; if ($?) { npx drizzle-kit migrate }; if ($?) { npm run dev }. This pattern prevents subsequent commands from running if a previous step fails.
Docker
This approach requires an additional step. After running docker compose -f docker-compose.yaml up --build -d, you still need to install dependencies and run migrations with your chosen package manager from outside the container. The Docker Compose configuration starts the database but not the application server.
Alternatives
- Next.js Boilerplates: Discover more general-purpose starters for Next.js projects.
- dotnize/react-tanstarter: The project that inspired this template, which may be a good choice if you’re looking for a slightly different configuration within the TanStack ecosystem.
FAQs
Q: Can I use a different database besides PostgreSQL?
A: Yes, but it requires some configuration changes. You’ll need to update the Drizzle ORM setup to use the correct adapter for your database (e.g., MySQL or SQLite), install the corresponding database driver, and adjust the DATABASE_URL in your .env file. The schema definitions in the project might also need slight modifications depending on the SQL dialect.
Q: How do I add a new authentication provider with better-auth?
A: To add a new provider, you’ll first need to obtain a client ID and secret from the provider’s developer portal. Next, add these credentials to your .env file. Finally, you’ll need to configure the new provider in the better-auth setup file, following the patterns used for the existing Google, GitHub, and Discord integrations.
Q: I’m getting an error during the drizzle-kit migrate step. What’s wrong?
A: This error almost always points to a database connection issue. First, verify that your PostgreSQL Docker container is running. You can check this with docker ps. Second, double-check that the DATABASE_URL in your .env file is correct and that the credentials match what’s defined in your docker-compose.yaml file.
Q: Can I replace shadcn/ui with a different UI library?
A: Absolutely. shadcn/ui is not deeply coupled to the application logic. You can remove its dependencies and install a different component library like Material-UI or Mantine. You would then need to go through the existing UI components in the project and replace the shadcn/ui components with your new ones.
Q: Is this template suitable for production?
A: Yes, the underlying technologies are all production-grade. tanstack-start itself is stable and ready for production use. As with any starter template, you should review the default configurations for security and performance and tailor them to your specific needs before deploying.
