Better-T-Stack

bts.jsonc is a JSONC (JSON with comments) configuration file located at your project root (./bts.jsonc). It captures the specific stack choices made during project creation, such as frontend, backend, API, DB/ORM, auth, and addons.

Crucial Note: While the generated code in apps/* and packages/* is the source of truth for your application, you must keep bts.jsonc if you intend to use the add command. If this file is missing, the add command will fail because it cannot detect your current stack to validate compatibility or pre-fill defaults.

The website is built with Next.js and Fumadocs. The directory structure is as follows:

• /src/app: Contains the Next.js application routes.
• /content/docs: Contains the documentation content in MDX format.
• /public: Contains static assets.

The CLI generates a monorepo structure as follows:

my-better-t-app/
├── apps/
│   ├── web/          # Frontend application
│   ├── server/       # Backend API
│   ├── native/       # (optional) Mobile application
│   └── docs/         # (optional) Documentation site
├── packages/         # Shared packages
└── README.md         # Auto-generated project documentation

Better T Stack is a project scaffolding CLI designed to transform a specific stack selection into a reproducible TypeScript starter project. It provides two primary workflows:

1. Create Path: The CLI workflow used to turn a project configuration into a brand-new scaffolded project.
2. Add Path: The CLI workflow used to add new capabilities (Addons) to an existing Better T Stack project.

Additionally, the project exposes an MCP Surface (Model Context Protocol server) that allows AI agents to access planning, creation, addon, guidance, and schema operations.

To develop the documentation site (apps/web), you must first set up the backend.

1. From the repo root, run bun install.
2. Navigate to packages/backend and run bun dev:setup (follow the prompts to choose local development).
3. Copy the CONVEX_URL from packages/backend/.env.local to apps/web/.env using the key NEXT_PUBLIC_CONVEX_URL.
4. Set the required Convex environment variables in packages/backend using the Convex CLI:
   • GITHUB_ACCESS_TOKEN
   • GITHUB_WEBHOOK_SECRET
5. Run bun dev from the repo root.

When the Web and Server components are deployed as separate Cloudflare Workers, they reside on different subdomains. To allow authentication to work across these subdomains, you must enable crossSubDomainCookies in your betterAuth configuration. Replace the placeholder domain with your actual workers subdomain (e.g., .your-subdomain.workers.dev).

// packages/auth/src/auth.ts
export const auth = betterAuth({
  // ... other config
  session: {
    cookieCache: {
      enabled: true,
      maxAge: 5 * 60, // 5 minutes
    },
  },
  advanced: {
    crossSubDomainCookies: {
      enabled: true,
      domain: ".workers.dev", // Shared domain for cookies
    },
  },
});

The scaffolding process is split into two distinct phases to prevent accidental file generation and ensure user confirmation.

1. Plan Phase: Call bts_plan_project with your full configuration. This is a dry run that performs no file writes. Review the output to ensure it matches your intended stack.
2. Create Phase: Once the plan is confirmed, call bts_create_project.

Important: When calling bts_create_project, set install: false. This prevents MCP request timeouts. You should run the installation command (e.g., bun install or npm install) manually in the project directory after the creation is complete.

When using the create-better-t-stack CLI, you must select compatible Database and ORM pairs.

Supported Combinations:

• sqlite: Use with drizzle or prisma.
• postgres: Use with drizzle or prisma.
• mysql: Use with drizzle or prisma.
• mongodb: Use with mongoose or prisma.
• none: No database or ORM required.

Restrictions:

• mongodb is not compatible with drizzle.
• You cannot select a database without an ORM, or an ORM without a database.

# ❌ Invalid - MongoDB with Drizzle
create-better-t-stack --database mongodb --orm drizzle

# ✅ Valid - MongoDB with Mongoose
create-better-t-stack --database mongodb --orm mongoose

You can use Better-T-Stack in Codex either via the plugin or by wiring the MCP server directly.

Option 1: Plugin Add the marketplace from the Codex plugins screen and install Better-T-Stack.

Option 2: MCP (via add-mcp)

npx -y add-mcp@latest "npx -y create-better-t-stack@latest mcp"   # choose "codex"

Option 3: Direct Config (~/.codex/config.toml)

[mcp_servers.better-t-stack]
command = "npx"
args = ["-y", "create-better-t-stack@latest", "mcp"]

Use the --dry-run flag to validate your inputs and target directories without actually writing any files. This is useful for planning, CI validation, or agent reasoning loops.

CLI usage:

create-better-t-stack --yes --dry-run

JSON usage: Include "dryRun": true in your input payload for create-json or add-json commands.

create-better-t-stack --yes --dry-run
create-better-t-stack create-json --input '{"projectName":"my-app","yes":true,"dryRun":true}'
create-better-t-stack add-json --input '{"projectDir":"./my-app","addons":["mcp"],"dryRun":true}'