t3-oss/create-t3-app
The best way to start a full-stack, typesafe Next.js app
Generates full-stack TypeScript Next.js apps with user-selected packages
The CLI collects user preferences through interactive prompts, builds a map of package installers based on selections, creates the target project directory, copies base template files, executes each selected installer to add package-specific files and dependencies, then optionally installs dependencies and initializes git. Each installer modifies the project by copying templates, updating package.json, and adding configuration files specific to its package.
Under the hood, the system uses 3 data pools, 4 control points to manage its runtime behavior.
A 8-component cli tool. 182 files analyzed. Data flows through 8 distinct pipeline stages.
How Data Flows Through the System
The CLI collects user preferences through interactive prompts, builds a map of package installers based on selections, creates the target project directory, copies base template files, executes each selected installer to add package-specific files and dependencies, then optionally installs dependencies and initializes git. Each installer modifies the project by copying templates, updating package.json, and adding configuration files specific to its package.
- Collect User Preferences — runCli() presents interactive prompts asking for app name, which packages to include (tRPC, Tailwind, Prisma/Drizzle, NextAuth/BetterAuth), database provider, and other options, returning a CliResults object with all selections
- Parse Project Path — parseNameAndPath() splits the app name into scoped name and directory path, handling cases like '@mono/app' which becomes scopedAppName='@mono/app' and appDir='dir/app' [CliResults]
- Build Installer Map — buildPkgInstallerMap() creates a PkgInstallerMap where each available package (nextAuth, prisma, tailwind, etc.) is mapped to its installer function and marked as inUse based on user selections [CliResults → PkgInstallerMap]
- Create Project Directory — createProject() creates the target directory, copies base Next.js template files from cli/template/, then iterates through the PkgInstallerMap calling each inUse installer with InstallerOptions context [PkgInstallerMap]
- Execute Package Installers — Each installer (prismaInstaller, trpcInstaller, etc.) adds its package-specific files, modifies package.json dependencies, creates configuration files, and sets up code templates based on the InstallerOptions context [InstallerOptions]
- Update Package Metadata — The generated package.json is updated with the user-provided app name, current CLI version in ct3aMetadata.initVersion, and package manager version in packageManager field
- Install Dependencies — installDependencies() executes the package manager (npm/pnpm/yarn/bun) to install all dependencies that were added by the various package installers, unless --no-install flag was used
- Initialize Git Repository — initializeGit() runs git init, adds all generated files, and creates an initial commit with message 'Initial commit from Create T3 App', unless --no-git flag was used
Data Models
The data structures that flow between stages — the contracts that hold the system together.
cli/src/cli/index.tsinterface with appName: string, packages: AvailablePackages[], flags: CliFlags (contains boolean flags for each package plus dbProvider), databaseProvider: DatabaseProvider
Created by CLI prompts, passed to installer system to configure which packages to include in generated project
cli/src/installers/index.tsRecord<AvailablePackages, {inUse: boolean, installer: Installer}> where Installer is a function that takes InstallerOptions and modifies the project directory
Built from user selections, then each installer function is called to add its package's files and dependencies to the project
cli/src/installers/index.tsinterface with projectDir: string, pkgManager: PackageManager, noInstall: boolean, packages: PkgInstallerMap, appRouter: boolean, projectName: string, scopedAppName: string, databaseProvider: DatabaseProvider
Passed to each installer function containing all context needed to modify the generated project
www/src/config.tsinterface with title: string, description: string, layout: string, optional image: {src: string, alt: string}, dir: 'ltr'|'rtl', ogLocale: string, lang: KnownLanguageCode, isMdx: boolean
Extracted from markdown files during Astro build process, used to configure page metadata and layout
Hidden Assumptions
Things this code relies on but never validates. These are the things that cause silent failures when the system changes.
Package managers (npm, pnpm, yarn, bun) return version strings in stdout when called with '-v' flag and process execution will not hang or error
If this fails: If package manager is corrupted or returns non-version output, the packageManager field in package.json gets malformed data, potentially breaking future dependency operations
cli/src/index.ts:main
createProject() must complete successfully before package.json can be safely read and modified - file operations are sequentially consistent
If this fails: If createProject() fails partially or another process modifies files concurrently, fs.readJSONSync() could read corrupted JSON or the writeJSONSync() could overwrite unexpected changes
cli/src/index.ts:main
All installer functions are synchronous and complete their file modifications before returning - no installer returns a Promise
If this fails: If any installer becomes async (e.g., downloading templates from remote), the createProject() orchestration will continue before files are written, leading to incomplete or missing configuration
cli/src/installers/index.ts:Installer
The NextAuth() result has an 'auth' property that is a function suitable for React's cache() wrapper
If this fails: If NextAuth changes its API shape or auth is not a function, the cache() call fails at runtime with unclear errors in generated projects
cli/template/extras/src/server/auth/index.ts:cache
App names containing '@' follow npm scoped package naming conventions where the scope ends at the first '/' character
If this fails: Input like '@invalid@scope/app' or '@scope@version/app' gets incorrectly parsed, creating malformed directory structures or invalid package.json names
cli/src/utils/parseNameAndPath.js
The system has sufficient disk space, network connectivity, and npm registry access to install all accumulated dependencies from all selected installers
If this fails: Partial dependency installation leaves the generated project in an unusable state with no clean recovery mechanism - user must manually fix or regenerate
cli/src/helpers/installDependencies.js
Git is installed, accessible in PATH, and the target directory is not already inside a git repository or has conflicting git configuration
If this fails: Git initialization fails silently or creates nested repositories, but project generation continues, leaving users with unexpected version control setup
cli/src/helpers/git.js:initializeGit
The hardcoded default package selection ('nextAuth', 'prisma', 'tailwind', 'trpc', 'eslint') will always be valid entries in availablePackages array
If this fails: If availablePackages is refactored or package names change, buildPkgInstallerMap() receives invalid package names and generates incomplete installer maps
cli/src/cli/index.ts:defaultOptions
SidebarItem links follow the pattern `${TCode}/${string}` where TCode exactly matches a key in KNOWN_LANGUAGES
If this fails: Mismatched language codes in sidebar links create broken navigation - users clicking sidebar items get 404s or wrong language content
www/src/config.ts:SIDEBAR
The getVersion() function returns the current CLI version that remains stable throughout the project generation process
If this fails: If version detection fails or changes mid-generation, ct3aMetadata.initVersion gets incorrect data, making debugging and support harder
cli/src/index.ts:CT3APackageJSON
System Behavior
How the system operates at runtime — where data accumulates, what loops, what waits, and what controls what.
Data Pools
Static template files and directories that form the base Next.js project structure before package-specific modifications
The output directory where all template files, package configurations, and dependencies accumulate as each installer executes
Markdown and MDX files containing documentation that gets processed by Astro into static HTML with internationalization
Delays
- Dependency Installation (async-processing, ~30-120 seconds) — User waits while npm/pnpm/yarn downloads and installs all packages added by the installers
- File System Operations (async-processing, ~1-5 seconds) — Directory creation and file copying operations execute sequentially as each installer runs
Control Points
- Package Selection Flags (runtime-toggle) — Controls: Which package installers are executed and which dependencies/configuration files are added to the generated project. Default: user-selected via prompts or CLI flags
- Database Provider (architecture-switch) — Controls: Which database configuration is generated for Prisma/Drizzle installations (SQLite, PostgreSQL, MySQL, PlanetScale). Default: sqlite (default) or user-selected
- App Router Toggle (feature-flag) — Controls: Whether to generate Next.js 13+ app directory structure or traditional pages directory structure. Default: true (default app router)
- Git Initialization (feature-flag) — Controls: Whether to initialize git repository and create initial commit after project generation. Default: true unless --no-git flag
Technology Stack
Provides interactive CLI prompts with modern styling for collecting user preferences during project generation
Parses command-line arguments and flags passed to the create-t3-app CLI
Enhanced file system operations for copying template files and creating project directories
Executes shell commands for package installation, git operations, and package manager detection
Static site generator that builds the documentation website from markdown files with internationalization support
Monorepo build system that coordinates builds and caching between the CLI and documentation packages
Key Components
- runCli (orchestrator) — Presents interactive prompts to collect user preferences for project generation including app name, packages to include, and database provider
cli/src/cli/index.ts - buildPkgInstallerMap (factory) — Creates a map of package installers based on user selections, enabling modular addition of features like tRPC, Prisma, Tailwind to the generated project
cli/src/installers/index.ts - createProject (executor) — Creates the target directory structure, copies base template files, and orchestrates execution of all selected package installers to build the final project
cli/src/helpers/createProject.js - prismaInstaller (transformer) — Adds Prisma ORM to the project by installing dependencies, creating schema file, and adding database configuration based on selected provider
cli/src/installers/prisma.js - trpcInstaller (transformer) — Sets up tRPC for type-safe API calls by adding client/server configuration, router setup, and React Query integration
cli/src/installers/trpc.js - nextAuthInstaller (transformer) — Configures NextAuth.js for authentication by adding provider setup, session management, and database adapter configuration
cli/src/installers/nextAuth.js - installDependencies (executor) — Executes package manager commands to install all dependencies that were added by the various package installers
cli/src/helpers/installDependencies.js - initializeGit (executor) — Initializes git repository in the generated project directory and creates initial commit with all scaffolded files
cli/src/helpers/git.js
Package Structure
Interactive CLI that scaffolds Next.js applications with user-selected packages from the T3 stack (TypeScript, tRPC, Tailwind, Prisma/Drizzle, NextAuth/BetterAuth).
Documentation website built with Astro that provides guides and API documentation for create-t3-app.
Explore the interactive analysis
See the full architecture map, data flow, and code patterns visualization.
Analyze on CodeSeaRelated Cli Tool Repositories
Frequently Asked Questions
What is create-t3-app used for?
Generates full-stack TypeScript Next.js apps with user-selected packages t3-oss/create-t3-app is a 8-component cli tool written in TypeScript. Data flows through 8 distinct pipeline stages. The codebase contains 182 files.
How is create-t3-app architected?
create-t3-app is organized into 4 architecture layers: CLI Interface, Package Installers, Project Generation, Documentation Site. Data flows through 8 distinct pipeline stages. This layered structure keeps concerns separated and modules independent.
How does data flow through create-t3-app?
Data moves through 8 stages: Collect User Preferences → Parse Project Path → Build Installer Map → Create Project Directory → Execute Package Installers → .... The CLI collects user preferences through interactive prompts, builds a map of package installers based on selections, creates the target project directory, copies base template files, executes each selected installer to add package-specific files and dependencies, then optionally installs dependencies and initializes git. Each installer modifies the project by copying templates, updating package.json, and adding configuration files specific to its package. This pipeline design reflects a complex multi-stage processing system.
What technologies does create-t3-app use?
The core stack includes @clack/prompts (Provides interactive CLI prompts with modern styling for collecting user preferences during project generation), commander (Parses command-line arguments and flags passed to the create-t3-app CLI), fs-extra (Enhanced file system operations for copying template files and creating project directories), execa (Executes shell commands for package installation, git operations, and package manager detection), Astro (Static site generator that builds the documentation website from markdown files with internationalization support), Turbo (Monorepo build system that coordinates builds and caching between the CLI and documentation packages). A focused set of dependencies that keeps the build manageable.
What system dynamics does create-t3-app have?
create-t3-app exhibits 3 data pools (Template Files, Generated Project), 4 control points, 2 delays. These runtime behaviors shape how the system responds to load, failures, and configuration changes.
What design patterns does create-t3-app use?
3 design patterns detected: Installer Pattern, Template Composition, Package Manager Abstraction.
Analyzed on April 20, 2026 by CodeSea. Written by Karolina Sarna.