🌴 TanStack Start Template

This is a template repository for a frontend web application powered by TanStack Start.

Features

• 🚀 Modern React Stack: Built with TanStack Start and TypeScript for optimal developer experience and performance
• 🔐 Authentication & Authorization:
  • Better Auth integration with OAuth2/OpenID Connect support
  • JWT-based authentication with remote JWKS validation via jose
  • Protected routes with automatic redirects
  • Server-side authentication middleware
• 💳 Payments & Subscriptions:
  • Stripe integration for payment processing
  • Subscription management with billing portal
  • Pricing pages with tier comparison
  • Customer portal for subscription updates and cancellations
• 🎨 UI/UX:
  • Modern component library with Ark UI and shadcn/ui patterns
  • Tailwind CSS v4 with optimized class sorting
  • tw-animate-css for Tailwind-powered animations
  • Dark/light theme support with persistent preferences
  • Responsive design with mobile-first approach
  • Toast notifications with Sonner
  • Lucide React and Simple Icons for iconography
• 📱 Progressive Web App (PWA):
  • Serwist service worker for offline functionality
  • App installation with native-like experience
  • Automatic updates with user notifications
  • Offline status indicators and caching strategies
  • Web app manifest for app store distribution
  • Background sync and push notification ready
• 📊 Data Management:
  • TanStack Query for server state management
  • TanStack Table for data visualization
  • GraphQL integration with code generation
  • Type-safe API calls with GraphQL Request
  • Zod for runtime schema validation
• 📈 GraphQL Integration:
  • GraphQL Code Generator for type-safe queries
  • React Query hooks generation
  • TypeScript SDK generation
  • MSW mocks for testing
• 🧪 Testing:
  • Unit tests with Bun test runner
  • Testing Library for component testing
  • Happy DOM for fast DOM simulation
  • E2E tests with Playwright
  • MSW (Mock Service Worker) for API mocking
  • Coverage reporting
• 🛠️ Developer Experience:
  • Hot module replacement during development
  • TanStack Devtools for Query, Router, and React debugging
  • Code quality with Biome for linting and formatting
  • Git hooks with Husky
  • TypeScript strict mode with comprehensive type safety
  • Knip for unused dependency detection
  • Easy spin up with Tilt
• 🚢 Production Ready:
  • Server-side rendering (SSR) support
  • Environment-specific configurations
  • TLS/HTTPS support with mkcert
  • Optimized build process with Vite
  • Route-based code splitting

Local Development

First, cp .env.local.template .env.local and fill in the values.

Building and Running

Run tilt up, or:

bun i

bun dev

PWA (Optional Tasks)

Generate Icons

Generate PWA icons:

bun icons:generate

Audit

Run a comprehensive PWA audit with Unlighthouse:

# first, start the dev server
bun dev

# in another terminal, run the audit
bun pwa:audit

This crawls the entire site and runs Google Lighthouse audits on each page, providing a dashboard with:

• Performance scores
• Accessibility checks
• Best practices
• SEO analysis
• PWA compliance

Docker

Build and run with Docker:

docker build -t app .
docker run -p 3000:3000 app

The Dockerfile uses a multi-stage build:

1. deps - Install dependencies with bun install --frozen-lockfile
2. builder - Build the application with bun run build
3. runner - Production image with only .output and node_modules

Key configuration:

• NODE_PATH is set to resolve modules from both /app/node_modules and /app/.output/server/node_modules
• Runs Bun directly (bun .output/server/index.mjs) to avoid node shim compatibility issues

Testing

The project includes a comprehensive test suite with unit tests and E2E tests.

Unit Tests

bun test

# or in watch mode
bun test:watch

# or test with coverage reporting
bun test:coverage

E2E Tests

# first, ensure Playwright browsers are installed
bunx playwright install

# run E2E tests
bun test:e2e

# or run with UI
bun test:e2e:ui

Tests use MSW (Mock Service Worker) to mock API calls. GraphQL mocks are auto-generated in src/generated/graphql.mock.ts via GraphQL Code Generator.

License

The code in this repository is licensed under MIT, © Omni LLC. See LICENSE.md for more information.