React TanStarter

A minimal starter template for 🏝️ TanStack Start. → Preview here

• React 19 + React Compiler
• TanStack Start + Router + Query
• Tailwind CSS v4 + shadcn/ui
• Drizzle ORM + PostgreSQL
• Better Auth

Table of Contents

• Getting Started
• Project Structure
• Authentication
• Database
• Components
• Routing
• API Functions
• Homelab Setup
• Security Considerations
• Testing
• Deployment
• Scripts
• License

Getting Started

We use npm by default, but you can modify the scripts in package.json to use your preferred package manager.

1. Use this template or clone this repository with gitpick:

   npx gitpick dotnize/react-tanstarter myapp
   cd myapp

2. Install dependencies:

   npm install

3. Create a .env file based on .env.example.

4. Push the schema to your database with drizzle-kit:

   npm db push

   https://orm.drizzle.team/docs/migrations

5. Run the development server:

   npm dev

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

Project Structure

src/
├── components/          # Reusable UI components
├── lib/                 # Core application logic
│   ├── auth/            # Authentication logic
│   ├── db/              # Database operations
│   └── utils.ts         # Utility functions
├── routes/              # Application routes
│   ├── (auth)/          # Authentication routes
│   ├── api/             # API routes
│   ├── dashboard/       # Dashboard routes
│   ├── __root.tsx       # Root layout
│   └── index.tsx        # Home page
└── styles.css           # Global styles

Authentication

This project uses Better Auth for authentication. The authentication system includes:

• Email/password authentication
• Social authentication (GitHub, Google)
• Session management

Key files:

• src/lib/auth/auth.ts - Better Auth configuration
• src/lib/auth/auth-client.ts - Client-side authentication functions
• src/lib/auth/queries.ts - Authentication queries
• src/lib/auth/middleware.ts - Authentication middleware

Database

The project uses Drizzle ORM with PostgreSQL. Database operations are organized as follows:

• src/lib/db/schema/ - Database schema definitions
• src/lib/db/queries/ - Database queries
• src/lib/db/functions/ - Database functions

Apps Schema

The main database table is for storing applications in a homelab environment:

• id (text) - Unique identifier
• name (text) - Application name
• localIp (varchar) - Local IP address
• remoteIp (varchar, optional) - Remote IP address
• port (integer) - Port number
• domain (varchar, optional) - Domain name
• subdomain (varchar, optional) - Subdomain
• userId (text) - Reference to user
• description (text, optional) - Application description

Components

The project uses shadcn/ui components built on top of Tailwind CSS.

Key custom components:

• AppCard - Displays individual app information
• AppForm - Form for creating/editing apps
• AppGrid - Grid layout for displaying apps

Routing

The project uses TanStack Router for routing:

• / - Home page
• /login - Login page
• /signup - Signup page
• /dashboard - Dashboard page (requires authentication)

API Functions

Database operations are exposed through API functions:

• $createApp - Create a new app
• $updateApp - Update an existing app
• $deleteApp - Delete an app

Homelab Setup

This template is designed for managing homelab applications. After setting up the project:

1. Configure your .env for local Postgres (use docker-compose.yml for a local instance):

   DATABASE_URL=postgresql://user:pass@localhost:5432/homelabdb
   

2. Add your first app via the dashboard: Enter local IP (e.g., 192.168.1.100), port (e.g., 8080), and optional domain/subdomain for external access.

3. Integrate with your network: Ensure the app server runs on a trusted LAN; use reverse proxies like Nginx for domain routing.

Example entry: Name "Home Assistant", localIp "192.168.1.50", port 8123, domain "home.example.com".

Security Considerations

For homelab use cases:

• Data Protection: Stored IPs/ports/domains are sensitive; enable HTTPS and encrypt DB if exposing remotely. Use Zod for input validation in forms (add to AppForm).

• Access Controls: Apply auth middleware to all protected routes. Limit API exposure to authenticated users only. For local access, use VPN or firewall rules to restrict dashboard to LAN IPs.

• Risks: Avoid storing credentials in the apps table; use external secrets management. Regularly audit logs for unauthorized CRUD actions.

• Best Practices: Run in a containerized environment (Docker) for isolation. Update dependencies frequently to patch vulnerabilities in Better Auth/Drizzle.

Testing

Run tests with Vitest:

npm test

Current coverage: Basic integration test for AppCard. Add unit tests for queries/functions (e.g., createApp) and e2e for auth/CRUD flows using Testing Library. Goal: 80% coverage. Configure in vitest.config.ts for reports.

Issue watchlist

• React Compiler docs, Working Group - React Compiler is in RC.
• Start BETA Tracking - TanStack Start is in beta and may still undergo major changes.
• Devtools Releases - TanStack Devtools is in alpha and may still have breaking changes.

Goodies

Scripts

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

• auth:generate - Regenerate the auth db schema if you've made changes to your Better Auth config.
• db - Run drizzle-kit commands. (e.g. npm db generate to generate a migration)
• ui - The shadcn/ui CLI. (e.g. npm ui add button to add the button component)
• format, lint, check-types - Run Prettier, ESLint, and check TypeScript types respectively.
  • check - Run all three above. (e.g. npm check)
• deps - Selectively upgrade dependencies via taze.

Utilities

• auth/middleware.ts - Sample middleware for forcing authentication on server functions. (see #5 and #17)
• theme-toggle.tsx, theme-provider.tsx - A theme toggle and provider for toggling between light and dark mode. (#7)

License

Code in this template is public domain via Unlicense. Feel free to remove or replace for your own project.

Also check out

• create-tsrouter-app - The official CLI tool from the TanStack team to create Router/Start projects.
• CarlosZiegler/fullstack-start-template - A more batteries-included boilerplate that provides a solid foundation for building modern web apps.