---

React + TanStack Router Starter

Opinionated React starter using Vite, TanStack Router (File Routes), TanStack Query, shadcn/ui, Tailwind CSS v4, Zustand, and Bun.

This project is designed for large, scalable admin dashboards with strict structure, routing discipline, and reusable screen patterns.

Prerequisites

Bun (required)

This project uses Bun as both the package manager and runtime.

Install Bun

macOS / Linux

curl -fsSL https://bun.sh/install | bash

Restart your terminal and verify:

bun --version

Windows

powershell -c "irm bun.sh/install.ps1 | iex"

Restart PowerShell and verify:

bun --version

---

Quick Start

1. Install dependencies

bun install

2. Configure environment variables

Create .env.local:

VITE_API_BASE_URL=https://<your-supabase>.supabase.co
VITE_API_KEY=<your-supabase-anon-key>
MODE=development

3. Run development server

bun dev

4. Build the project

bun run build

---

Project Structure

src/
├─ main.tsx                 # App bootstrap (router + providers)
├─ routes.ts                # Virtual route config
├─ routeTree.gen.ts         # Generated – DO NOT EDIT
├─ pages/                   # File-based routes
│  ├─ auth/                 # Login / forgot password
│  ├─ middlewares/          # Route guards
│  ├─ app/(_authenticated)/ # Protected area
│  ├─ error/                # Error pages
│  └─ public/               # Public pages
├─ components/
│  ├─ ui/                   # shadcn primitives
│  └─ screens-component/    # Screen-level UI (web/mobile)
├─ hooks/
│  ├─ apis/                 # TanStack Query APIs
│  └─ store/                # Zustand stores
├─ layouts/                 # App shell layouts
├─ config/                  # env + request wrapper
├─ lib/utils/               # Utilities
└─ styles/                  # Tailwind + theme tokens

---

Routing System

• Uses TanStack Router + virtual routes
• Routes defined in src/routes.ts
• Generated tree in routeTree.gen.ts (do not edit)

Middlewares

Middleware	Purpose
restrict-login-signup	Prevent logged-in users from auth pages
authenticate	Protects authenticated routes
require-admin	Admin-only routes

Protected Layout

src/pages/app/(_authenticated)/layout.tsx

Wraps sidebar + header + <Outlet />.

---

API Layer

• All API calls go through request() from:

  src / config / request.ts;

• Automatically injects:

  • apikey
  • Authorization
  • handles expiry + logout

• Use TanStack Query for all data fetching.

---

Screen Scaffolding (Highly Recommended)

To keep routing, screens, and APIs consistent, this project includes a screen scaffolding script.

Script Location

/scripts/scaffold-screen.ts

Register Script

Add to package.json:

{
	"scripts": {
		"new:screen": "bun scripts/scaffold-screen.ts"
	}
}

---

What the Script Generates

Screen UI

src/components/screens-component/<screen-name>/
├─ components/
│  └─ index.ts
├─ web-layout/
│  └─ index.tsx
├─ mob-layout/
│  └─ index.tsx
└─ index.ts

Page Route (unless --no-pages)

src/pages/<parent>/<screen-name>/
├─ index.tsx
└─ routes.ts

API Layer (with --api)

src/hooks/apis/<screen-name>/
├─ queries.ts
├─ mutations.ts
├─ type.ts
└─ index.ts

Also auto-updates:

src / hooks / apis / index.ts;

export * from "./<screen-name>";

---

Screen Script Usage

Basic screen

bun run new:screen netskill-lp-modules

Screen with API hooks

bun run new:screen assessment-performance-report --api

Create under authenticated area

bun run new:screen my-screen --parent=app/(_authenticated)

Create under reports

IMPORTANT: zsh requires escaping parentheses.

bun run new:screen learning-path-report --api --parent=app/\(_authenticated\)/reports

Create under settings

bun run new:screen platform-customization --parent=app/\(_authenticated\)/settings

Skip page creation (UI only)

bun run new:screen my-shared-screen --no-pages

Force overwrite existing files

bun run new:screen my-screen --force

Combine flags

bun run new:screen completion-ratio \
  --api \
  --force \
  --parent=app/\(_authenticated\)/reports

---

zsh Users: IMPORTANT

zsh treats parentheses as glob patterns.

Always escape or quote paths containing:

(_authenticated)

Correct examples:

--parent=app/\(_authenticated\)/reports

or

--parent="app/(_authenticated)/reports"

---

Generated Page Pattern

import { ScreenWebLayout } from "@/components/screens-component/screen/web-layout";
import { ScreenMobileLayout } from "@/components/screens-component/screen/mob-layout";
import { useIsMobile } from "@/hooks/use-mobile";

function Screen() {
	const isMobile = useIsMobile();
	return isMobile ? <ScreenMobileLayout /> : <ScreenWebLayout />;
}

export default Screen;

---

Scripts Reference

Command	Description
bun dev	Start dev server
bun run build	Typecheck + build
bun preview	Preview production build
bun lint	Run ESLint
bun run lint:fix	Auto-fix lint
bun run typecheck	TypeScript check
bun run new:screen	Scaffold new screen

---

Rules & Best Practices

• Do not edit routeTree.gen.ts
• Always use the screen scaffold script
• Screens live in screens-component
• Pages are thin route wrappers only
• APIs must live under hooks/apis
• Prefer query + mutation hooks
• Do not place logic inside layouts

---