Шаблон TanStack Start + Drizzle + Tailwind v4

Опинионированный стартер на готовой инфраструктуре. FSD-структура, тёмная тема, auth (email + OIDC SSO), линтер, форматтер (Allman-style через AST-постпроцессор), импорт-конвертер, pre-commit хук — всё уже настроено.

Стек

• TanStack Start (SSR React 19) + TanStack Router (file-based) + TanStack Query v5
• Drizzle ORM + Postgres (Neon Launchpad для dev), миграции через drizzle-kit
• Tailwind CSS v4 через @tailwindcss/vite, токены в OKLCH
• Zod для серверной валидации
• openid-client v6 — OIDC SSO с админкой провайдеров
• Bun — рантайм и пакет-менеджер
• Vitest для тестов

Первичная настройка

После того как вы скопировали этот шаблон в свою папку:

bun install
bun run setup

Скрипт scripts/setup.ts:

1. Спросит имя проекта, slug, описание, ключевые слова → подменит в package.json, src/shared/lib/seo.ts, src/widgets/app-shell и src/routes/login.tsx.
2. Спросит базовый brand-hue (OKLCH H, 0..360) → подменит --brand-h в src/styles.css.
3. Сгенерирует .env с DATABASE_URL (опц.), рандомным APP_AUTH_SECRET и APP_PUBLIC_URL.
4. По желанию удалит .git/ и инициализирует новый репозиторий с первым коммитом.

После прогона scripts/setup.ts можно удалить — он одноразовый.

Затем:

bun run dev               # запуск (Neon Launchpad заклеймит БД при пустом DATABASE_URL)
bun run db:migrate        # накатить миграции
bun run db:seed           # применить системные сиды из db/init.sql
bun run create-admin      # создать первого админа

Скрипты

bun run dev            # vite dev, порт 3044
bun run build          # production-сборка
bun run check          # tsc -b (типы)
bun run lint           # eslint (включая FSD layer-direction guard)
bun run format         # форматирование (Prettier + Allman post-processor)
bun run format:check   # только проверка
bun run imports:fix    # переписать относительные ../../ на @/
bun run imports:check  # проверка для CI
bun run test           # vitest

bun run db:generate    # сгенерировать новую миграцию из изменений схемы
bun run db:migrate     # применить миграции
bun run db:seed        # применить db/init.sql (после migrate)
bun run db:setup       # migrate + seed одной командой
bun run db:studio      # drizzle-kit studio

bun run create-admin   # создать админа
bun run routes:gen     # перегенерировать routeTree.gen.ts
bun run count          # cloc по проекту
bun run doctor         # react-doctor

Что включено

Инфраструктура:

• FSD-структура (app → routes → widgets → features → entities → shared) + ESLint layer-direction guard через import/no-restricted-paths.
• TS-алиасы @/ (./src/*), #/ (./src/shared/*), $/ (./public/*) + скрипт-конвертер imports:fix (../../ → @/...).
• Собственный форматтер (scripts/format.ts): Prettier baseline + AST-постпроцессор для Allman-style фигурных скобок (Prettier/Biome это не умеют).
• Pre-commit хук Husky: check + lint + imports:check + format:check.
• Drizzle + кастомный scripts/migrate.ts (выносит ALTER TYPE ADD VALUE из транзакции, чтобы enum-значения можно было использовать в той же миграции).
• shadcn-конфиг с алиасами в src/shared/ui/ (bunx shadcn add <name> кладёт компоненты прямо туда).

Фичи:

• Auth: email/пароль + сессии (хэш в БД, sliding renewal), middleware (authMiddleware, adminMiddleware, roleMiddleware).
• OIDC SSO через openid-client v6: админка провайдеров на /admin/oidc-providers, PKCE+state+nonce в HMAC state-cookie, авто-регистрация по email.
• Тёмная тема (light/dark/system) с anti-FOUC inline-скриптом.
• Редактирование своего профиля (features/profile-edit).
• Админка: CRUD пользователей и SSO-провайдеров.

UI-атомы (shadcn-стиль в src/shared/ui/): button, input, field, select, textarea, modal (через portal, SSR-safe), color-picker, multi-select-combobox с пагинацией и поиском, load-more-footer, optimistic-toggle, theme-toggle.

Каноничные механизмы

См. CLAUDE.md — инструкции для AI-агентов с детальным разбором паттернов проекта (createServerOnlyFn, Modal через portal, OKLCH палитра вокруг --brand-h, anti-FOUC темы, и т.д.).

ENV

Переменная	Назначение
DATABASE_URL	Postgres connection string. В dev Neon Launchpad заклеймит автоматически.
APP_AUTH_SECRET	HMAC-секрет для OIDC state-cookie. openssl rand -hex 32. В dev есть fallback с console.warn.
APP_PUBLIC_URL	Публичный origin приложения (https://app.example.com). Используется для построения redirect_uri OIDC. В dev fallback localhost.

Префикс envPrefix настроен на APP_ — если хотите свой, замените в vite.config.ts и переименуйте переменные.

Структура

src/
  app/                         инициализация приложения
    providers/theme-provider   контекст темы
    tanstack-query/            queryClient + devtools
  routes/                      file-based routing TanStack Router
    __root.tsx                 корневой документ + anti-FOUC + ThemeProvider
    _authed.tsx                гард авторизации
    _authed/                   защищённые роуты (index, admin/...)
    api/auth/oidc/             OIDC login/callback
    login.tsx                  страница входа
  widgets/app-shell            хедер + сайдбар
  features/
    profile-edit               редактирование своего профиля
    sso-auth                   OIDC хелперы (config, state-cookie, user-link)
  entities/
    user                       CRUD пользователей
    oidc-provider              CRUD SSO-провайдеров
  shared/
    ui/                        shadcn-атомики
    lib/                       инфра (dates, pagination, theme, utils...)
    auth/                      cookie, middleware, password, session, token
    db/                        Drizzle client + schema/
  router.tsx                   TanStack Start entry
  styles.css                   палитра (light + dark)
db/init.sql                    системный seed (пустой по умолчанию)
drizzle/                       сгенерированные миграции (пусто - сгенерируйте сами)
scripts/                       format, migrate, seed, create-admin, setup, ...