Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/amanvarshney01/create-better-t-stack/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

bts.jsonc is a configuration file automatically created in your project root when you scaffold a new Better-T-Stack project. It captures all your stack choices and enables the CLI to understand your project structure for future operations.
The add command requires bts.jsonc to detect your existing stack configuration. Without this file, the CLI cannot determine compatibility or apply the correct templates.

​
Location

my-project/
├── bts.jsonc          ← Configuration file
├── apps/
├── packages/
└── ...

​
File Format

The file uses JSONC (JSON with Comments) format and includes a $schema reference for editor autocomplete and validation: 
// Better-T-Stack configuration file
// safe to delete
{
  "$schema": "https://r2.better-t-stack.dev/schema.json",
  "version": "1.0.0",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "reproducibleCommand": "bun create better-t-stack my-app --frontend tanstack-router --backend hono --database postgres --orm drizzle --api trpc --auth better-auth",
  "frontend": ["tanstack-router"],
  "backend": "hono",
  "runtime": "bun",
  "database": "postgres",
  "orm": "drizzle",
  "api": "trpc",
  "auth": "better-auth",
  "addons": ["turborepo"],
  "examples": [],
  "dbSetup": "neon",
  "webDeploy": "none",
  "serverDeploy": "none",
  "packageManager": "bun"
}

​
Schema Reference

The configuration follows the BetterTStackConfigFileSchema defined in packages/types/src/schemas.ts:194-203.

​
Core Fields

​
version
string
required
CLI version used to create the project (e.g., "1.0.0")
​
createdAt
string
required
ISO 8601 timestamp when the project was created
​
reproducibleCommand
string
The exact command used to create this project, useful for recreating the same configuration

​
Stack Configuration

​
frontend
array
required
Frontend framework(s) selected. Possible values:
  • tanstack-router
  • react-router
  • tanstack-start
  • next
  • nuxt
  • svelte
  • solid
  • astro
  • native-bare, native-uniwind, native-unistyles (React Native)
  • none
​
backend
string
required
Backend framework. Options: hono, express, fastify, elysia, convex, self, none
​
runtime
string
required
Runtime environment: bun, node, workers, none
​
database
string
required
Database type: sqlite, postgres, mysql, mongodb, none
​
orm
string
required
ORM/database client: drizzle, prisma, mongoose, none
​
api
string
required
API layer: trpc, orpc, none
​
auth
string
required
Authentication provider: better-auth, clerk, none
​
payments
string
required
Payment integration: polar, none

​
Additional Options

​
addons
array
required
Additional tools and features:
  • turborepo - Monorepo build system
  • pwa - Progressive Web App support
  • tauri - Desktop app wrapper
  • biome, oxlint - Linting tools
  • lefthook, husky - Git hooks
  • starlight, fumadocs - Documentation
  • ruler - Project rules
  • mcp, skills, ultracite, opentui, wxt - Advanced features
  • none
​
examples
array
required
Example templates: todo, ai, or empty array
​
dbSetup
string
required
Database hosting setup:
  • turso - Turso (SQLite)
  • neon - Neon (Postgres)
  • supabase - Supabase (Postgres)
  • prisma-postgres - Prisma Postgres
  • planetscale - PlanetScale (MySQL)
  • mongodb-atlas - MongoDB Atlas
  • d1 - Cloudflare D1
  • docker - Local Docker
  • none
​
webDeploy
string
required
Web deployment target: cloudflare, none
​
serverDeploy
string
required
Server deployment target: cloudflare, none
​
packageManager
string
required
Package manager: npm, pnpm, bun

​
Usage by CLI

​
Project Detection

The CLI reads bts.jsonc to detect existing projects: 
// apps/cli/src/utils/bts-config.ts:12-26
export async function readBtsConfig(projectDir: string): Promise<BetterTStackConfig | null> {
  try {
    const configPath = path.join(projectDir, "bts.jsonc");
    
    if (!(await fs.pathExists(configPath))) {
      return null;
    }
    
    const configContent = await fs.readFile(configPath, "utf-8");
    const config = parse(configContent) as BetterTStackConfig;
    return config;
  } catch {
    return null;
  }
}

​
Configuration Updates

The add command can update specific fields while preserving comments: 
// apps/cli/src/utils/bts-config.ts:31-54
export async function updateBtsConfig(
  projectDir: string,
  updates: Partial<Pick<BetterTStackConfig, "addons" | "webDeploy" | "serverDeploy">>,
): Promise<void> {
  try {
    const configPath = path.join(projectDir, "bts.jsonc");
    
    if (!(await fs.pathExists(configPath))) {
      return;
    }
    
    let content = await fs.readFile(configPath, "utf-8");
    
    // Apply each update using jsonc-parser's modify (preserves comments)
    for (const [key, value] of Object.entries(updates)) {
      const edits = modify(content, [key], value, { formattingOptions: { tabSize: 2 } });
      content = applyEdits(content, edits);
    }
    
    await fs.writeFile(configPath, content, "utf-8");
  } catch {
    // Silent failure
  }
}

​
Editor Support

The $schema field enables IDE features:
1

Autocomplete

Get field suggestions as you type in VS Code, Cursor, or other editors that support JSON Schema
2

Validation

See inline errors for invalid values or missing required fields
3

Hover Documentation

View field descriptions by hovering over property names

​
Can You Delete It?

Yes, bts.jsonc can be safely deleted for normal development. Your generated code in apps/* and packages/* remains the source of truth.
If you delete bts.jsonc, the add command will not work because it cannot detect your project configuration. You would need to recreate the file manually or re-run project creation.

​
Example Configurations

​
Full-Stack T3-style App

{
  "$schema": "https://r2.better-t-stack.dev/schema.json",
  "version": "1.0.0",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "frontend": ["next"],
  "backend": "self",
  "runtime": "node",
  "database": "postgres",
  "orm": "drizzle",
  "api": "trpc",
  "auth": "better-auth",
  "addons": ["turborepo"],
  "examples": ["todo"],
  "dbSetup": "neon",
  "webDeploy": "none",
  "serverDeploy": "none",
  "packageManager": "bun"
}

​
API-Only Backend

{
  "$schema": "https://r2.better-t-stack.dev/schema.json",
  "version": "1.0.0",
  "createdAt": "2025-01-15T11:00:00.000Z",
  "frontend": ["none"],
  "backend": "hono",
  "runtime": "bun",
  "database": "postgres",
  "orm": "drizzle",
  "api": "trpc",
  "auth": "better-auth",
  "addons": ["turborepo"],
  "examples": [],
  "dbSetup": "docker",
  "webDeploy": "none",
  "serverDeploy": "cloudflare",
  "packageManager": "bun"
}

​
Serverless with Convex

{
  "$schema": "https://r2.better-t-stack.dev/schema.json",
  "version": "1.0.0",
  "createdAt": "2025-01-15T12:00:00.000Z",
  "frontend": ["tanstack-router"],
  "backend": "convex",
  "runtime": "none",
  "database": "none",
  "orm": "none",
  "api": "none",
  "auth": "better-auth",
  "addons": ["turborepo"],
  "examples": ["todo"],
  "dbSetup": "none",
  "webDeploy": "cloudflare",
  "serverDeploy": "none",
  "packageManager": "bun"
}

add Command

Use bts.jsonc to add features to existing projects

Project Structure

See how configuration affects generated layouts

Build docs developers (and LLMs) love

Get started for freeTalk to us