TypeScript 544 FILES 14 FINDINGS

HOW CREATE T3 APP
ACTUALLY WORKS

The best way to start a full-stack, typesafe Next.js app. Conventions, patterns, and architecture extracted from the t3-oss/create-t3-app repository by sourcebook.

VIEW_REPO north_east

QUICK_REF:

Routing: tRPC routers Validation: Zod schemas Data: React Query Auth: better-auth. Styling: Tailwind CSS utility classes. Custom design tokens defined in www/tailwind.config.ts — use these instead of arbitrary values. Database: Prisma. Look

WHAT_MATTERS

→
This is a monorepo — check workspace dependencies before modifying shared code
→
Uses tRPC routers for routing — follow this pattern, don't add REST routes directly
→
Generated files detected — editing them directly will break builds
→
www/src/config.ts is a hub file (imported by 6 files) — changes here ripple everywhere

KEY_FINDINGS

This is a monorepo. Changes may affect multiple packages. Check workspace dependencies before modifying shared code.

HIGH

Project strongly prefers path alias imports (@/ or ~/) over relative imports. Use aliases for cross-directory imports.

HIGH

61 alias imports vs 17 relative imports in sampled files

Project strongly prefers named exports over default exports. Use `export function` / `export const`, not `export default`.

HIGH

82 named vs 16 default exports in sampled files

Use Zod schemas for validation. This is the project's standard validation approach.

HIGH

8 files use Zod

Data fetching uses React Query (useQuery/useMutation). Follow this pattern for new data operations.

HIGH

9 files

Auth uses better-auth.

HIGH

19 files

Styling uses Tailwind CSS utility classes. Custom design tokens defined in www/tailwind.config.ts — use these instead of arbitrary values.

HIGH

11 files

Database access uses Prisma. Look for schemas in prisma/schema.prisma.

HIGH

8 files

Generated files detected (cli/template/extras/src/app/layout/with-tw.tsx, cli/template/extras/src/pages/index/with-better-auth-trpc.tsx, cli/template/extras/src/pages/index/with-tw.tsx, cli/template/extras/src/app/layout/base.tsx, cli/template/extras/src/app/layout/with-trpc-tw.tsx, ...). Do NOT edit these directly — modify the source/schema they are generated from.

HIGH

14 generated files

Route definitions live in: cli/template/extras/src/server/api, cli/template/extras/src/server/api/trpc-pages, cli/template/extras/src/server/api/trpc-app. Add new endpoints here.

HIGH

3 route directories

Hub files (most depended on): www/src/config.ts (imported by 6 files). Changes here have the widest blast radius.

HIGH

+ 2 MORE FINDINGS (MEDIUM CONFIDENCE)

API endpoints use tRPC routers. Follow this pattern for new routes.

MED

5 files use tRPC routers

UI components live in: www/src/components. Add new components here.

MED

1 component directories

smart_toy USING_AI_TOOLS

→don't guess routing patterns — check first
→avoid editing generated files — modify the source/schema instead
→check file importance before editing hub files
→follow existing patterns listed in quick reference

CLAUDE.MD expand_more

# CLAUDE.md

This file provides guidance to Claude Code when working with this codebase.
Generated by [sourcebook](https://github.com/maroondlabs/sourcebook). Review and edit — the best context comes from human + machine together.

## Quick Reference

- **routing:** API endpoints use tRPC routers
- **validation:** Use Zod schemas for validation
- **data fetching:** Data fetching uses React Query (useQuery/useMutation)
- **auth:** Auth uses better-auth.
- **styling:** Styling uses Tailwind CSS utility classes. Custom design tokens defined in www/tailwind.config.ts — use these instead of arbitrary values.
- **components:** UI components live in: www/src/components. Add new components here.

## Commands

- **Build:** `turbo build`
- **Lint:** `turbo lint && manypkg check`
- **typecheck:** `turbo typecheck`

## Critical Constraints

- **Critical constraints:** Generated files detected (cli/template/extras/src/app/layout/with-tw.tsx, cli/template/extras/src/pages/index/with-better-auth-trpc.tsx, cli/template/extras/src/pages/index/with-tw.tsx, cli/template/extras/src/app/layout/base.tsx, cli/template/extras/src/app/layout/with-trpc-tw.tsx, ...). Do NOT edit these directly — modify the source/schema they are generated from.
- **Core modules:** Hub files (most depended on): www/src/config.ts (imported by 6 files). Changes here have the widest blast radius.

## Stack

Next.js, Tailwind CSS, TypeScript

## Core Modules (by structural importance)

- `www/src/config.ts`
- `cli/template/extras/src/trpc/query-client.ts`
- `cli/src/utils/removeTrailingSlash.ts`
- `www/src/languages.ts`
- `cli/src/installers/dependencyVersionMap.ts`

## Conventions & Patterns

- **Project structure:** This is a monorepo. Changes may affect multiple packages. Check workspace dependencies before modifying shared code.
- **Import conventions:** Project strongly prefers path alias imports (@/ or ~/) over relative imports. Use aliases for cross-directory imports.
- **Export conventions:** Project strongly prefers named exports over default exports. Use `export function` / `export const`, not `export default`.
- **Dominant patterns:**
- Use Zod schemas for validation. This is the project's standard validation approach.
- Data fetching uses React Query (useQuery/useMutation). Follow this pattern for new data operations.
- Auth uses better-auth.
- Styling uses Tailwind CSS utility classes. Custom design tokens defined in www/tailwind.config.ts — use these instead of arbitrary values.
- Database access uses Prisma. Look for schemas in prisma/schema.prisma.
- Route definitions live in: cli/template/extras/src/server/api, cli/template/extras/src/server/api/trpc-pages, cli/template/extras/src/server/api/trpc-app. Add new endpoints here.

## Additional Context

- **Dominant patterns:**
- API endpoints use tRPC routers. Follow this pattern for new routes.
- UI components live in: www/src/components. Add new components here.

## Before Making Changes

- **Check file importance** before editing. Hub files (listed in Core Modules) affect many other files — changes here have the widest blast radius.
- **Follow existing patterns.** This project has established conventions (listed above). Match them instead of introducing new approaches.
- **Respect constraints.** Review the Critical Constraints section before making structural changes.

If the sourcebook MCP server is available (`sourcebook serve`), verify before acting:
- `get_blast_radius` — check what breaks if you edit a hub file
- `query_conventions` — confirm the right pattern before adding new code
- `get_pressing_questions` — get a briefing before editing an unfamiliar file

## What to Add Manually

The most valuable context is what only you know. Add:

- Architectural decisions and why they were made
- Past incidents that shaped current conventions
- Deprecated patterns to avoid in new code
- Domain-specific rules or terminology
- Environment setup beyond what .env.example shows

GENERATED IN ~3 SECONDS WITH

npx sourcebook init

VIEW ON GITHUB star

FROM_THE_BLOG

Why AI agents fail on real codebases arrow_forward Why auto-generated context makes agents worse arrow_forward

RELATED_REPOS

NEXT.JS SHADCN/UI

HOW CREATE T3 APPACTUALLY WORKS

WHAT_MATTERS

KEY_FINDINGS

npx sourcebook init

FROM_THE_BLOG

RELATED_REPOS

HOW CREATE T3 APP
ACTUALLY WORKS