Navigating the Tanstack Start Supabase SaaS Kit Codebase

Understand the Turborepo monorepo structure, key directories, and where to add your custom code.

The kit uses Turborepo to organize code into reusable packages. Understanding this structure helps you know where to find things and where to add your own code.

Top-Level Structure

├── apps/
│   ├── web/          # Main Tanstack Start application
│   └── e2e/          # Playwright end-to-end tests
├── packages/
│   ├── features/     # Feature modules (auth, accounts, admin)
│   ├── ui/           # Shared UI components
│   ├── supabase/     # Database client and types
│   ├── billing/      # Payment integrations
│   ├── mailers/      # Email providers
│   └── ...           # Other shared packages
└── turbo.json        # Turborepo configuration

Where You'll Work Most

90% of your work happens in apps/web/. The packages provide infrastructure; you build your product in the app.

apps/web/ Directory

apps/web/
├── src/
│   ├── routes/       # File-based routes (TanStack Router)
│   ├── components/   # App-specific components
│   ├── config/       # Application configuration
│   ├── lib/          # App-specific utilities
│   └── styles/       # Global CSS
├── content/          # CMS content (Keystatic)
└── supabase/         # Migrations and database tests

Directory	What Goes Here
`src/routes/`	All routes and pages
`src/components/`	Components specific to this app
`src/config/`	App settings, feature flags, navigation
`src/lib/`	Utilities that don't belong in packages
`supabase/`	Database migrations and seed data

Routing Structure

Routes use TanStack Router file-based routing under src/routes/. The route tree is generated into src/routeTree.gen.ts (run pnpm --filter web generate-routes) — never edit that file by hand.

src/routes/
├── __root.tsx            # Root layout (wraps every route)
├── _marketing/           # Public pages — pathless layout (landing, pricing, blog)
├── auth/                 # Authentication pages
├── home/                 # Authenticated dashboard
│   ├── _user/            # Personal account routes — pathless layout
│   └── $account/         # Team account routes — dynamic segment
├── admin/                # Super admin dashboard
├── join/                 # Team invitation acceptance
├── docs/                 # Documentation
├── api/                  # API route handlers
├── update-password.tsx   # Password reset completion
└── identities.tsx        # OAuth identity linking

File Conventions Explained

A folder with an underscore prefix (e.g. _marketing, _user) is a pathless layout route: it shares a layout across its children but does not add a URL segment. A $-prefixed folder (e.g. $account) is a dynamic segment. route.tsx defines a layout for a folder, and index.tsx defines its index page.

_marketing — Pathless layout for public pages. URLs don't include "_marketing":

src/routes/_marketing/index.tsx → /
src/routes/_marketing/pricing.tsx → /pricing

home/_user — Personal account dashboard. Pathless layout under /home:

src/routes/home/_user/index.tsx → /home
src/routes/home/_user/settings.tsx → /home/settings

home/$account — Team account dashboard. Dynamic segment for the team slug:

src/routes/home/$account/index.tsx → /home/acme-corp
src/routes/home/$account/settings.tsx → /home/acme-corp/settings

Internationalization is handled by use-intl with the active locale stored in a cookie — locales are not encoded in the URL path.

Packages Overview

Packages provide reusable functionality. Import from them; don't modify unless necessary.

Feature Packages (`packages/features/`)

Package	Import	Contains
`@kit/auth`	`@kit/auth/*`	Sign in/up forms, auth hooks
`@kit/accounts`	`@kit/accounts/*`	Personal account components
`@kit/team-accounts`	`@kit/team-accounts/*`	Team management, invitations
`@kit/admin`	`@kit/admin/*`	Super admin dashboard
`@kit/notifications`	`@kit/notifications/*`	In-app notifications

Infrastructure Packages

Package	Import	Contains
`@kit/ui`	`@kit/ui/*`	Shadcn components, design system
`@kit/supabase`	`@kit/supabase/*`	Database clients, types
`@kit/billing`	`@kit/billing/*`	Subscription logic
`@kit/mailers`	`@kit/mailers/*`	Email sending

Adding Your Own Code

New Pages

Add routes in apps/web/src/routes/:

# Public page
apps/web/src/routes/_marketing/features.tsx → /features
# Authenticated page (personal)
apps/web/src/routes/home/_user/dashboard.tsx → /home/dashboard
# Authenticated page (team)
apps/web/src/routes/home/$account/projects.tsx → /home/acme-corp/projects

After adding or renaming route files, regenerate the route tree with pnpm --filter web generate-routes (or let the dev server do it automatically).

New Components

Add to apps/web/src/components/ for app-specific components:

apps/web/src/components/
├── dashboard/
│   ├── stats-card.tsx
│   └── activity-feed.tsx
└── projects/
    ├── project-list.tsx
    └── project-form.tsx

New Database Tables

Create migration in apps/web/supabase/migrations/
Run pnpm run supabase:web:reset to apply
Run pnpm run supabase:web:typegen to update types

Configuration Files

Located in apps/web/src/config/:

File	Purpose	When to Edit
`app.config.ts`	App name, URLs	During initial setup
`auth.config.ts`	Auth providers	Adding OAuth providers
`billing.config.ts`	Plans, prices	Setting up billing
`feature-flags.config.ts`	Feature toggles	Enabling/disabling features
`paths.config.ts`	Route constants	Adding new routes
`*-navigation.config.tsx`	Sidebar menus	Customizing navigation

Next Steps

Review common commands for daily development
Configure the app for your product
Add marketing pages to start building