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.

The create() function generates a new Better-T-Stack project on disk. It runs in silent mode with no interactive prompts and returns a typed Result.

​
Signature

function create(
  projectName?: string,
  options?: Partial<CreateInput>
): Promise<Result<InitResult, CreateError>>
Source: ~/workspace/source/apps/cli/src/index.ts:191

​
Parameters

​
projectName
string
The name of the project. If not provided, defaults to the current directory name or prompts in CLI mode.Example: "my-app"
​
options
Partial<CreateInput>
Configuration options for the project. All fields are optional.

​
Return Type

Promise<Result<InitResult, CreateError>>

​
Success (Result.ok)

Returns InitResult:
​
success
boolean
required
Always true on success
​
projectDirectory
string
required
Absolute path to the created projectExample: "/Users/name/my-app"
​
relativePath
string
required
Relative path to the projectExample: "./my-app"
​
projectConfig
ProjectConfig
required
The complete project configuration used
​
reproducibleCommand
string
required
CLI command to reproduce this exact configurationExample: "create-better-t-stack my-app --frontend tanstack-router --backend hono"
​
timeScaffolded
string
required
ISO timestamp when the project was createdExample: "2026-03-03T10:30:00.000Z"
​
elapsedTimeMs
number
required
Time taken to scaffold the project in millisecondsExample: 1234

​
Error (Result.err)

Returns CreateError which is a union of:
  • UserCancelledError - Operation was cancelled
  • CLIError - General CLI error
  • ProjectCreationError - Error during project creation
See Error Handling for details.

​
Examples

​
Basic Usage

import { create } from "create-better-t-stack";

const result = await create("my-app", {
  frontend: ["tanstack-router"],
  backend: "hono",
  database: "sqlite",
  orm: "drizzle",
});

result.match({
  ok: (data) => {
    console.log(`Project created at: ${data.projectDirectory}`);
    console.log(`Time taken: ${data.elapsedTimeMs}ms`);
  },
  err: (error) => {
    console.error(`Failed: ${error.message}`);
  },
});

​
Full Stack Application

import { create } from "create-better-t-stack";

const result = await create("my-app", {
  frontend: ["next"],
  backend: "hono",
  runtime: "bun",
  database: "postgres",
  orm: "drizzle",
  auth: "better-auth",
  payments: "stripe",
  addons: ["biome", "playwright"],
  packageManager: "bun",
  install: true,
  git: true,
});

if (result.isOk()) {
  console.log(result.value.reproducibleCommand);
}

​
Error Handling

import { create } from "create-better-t-stack";

const result = await create("existing-dir", {
  frontend: ["tanstack-router"],
  directoryConflict: "error",
});

if (result.isErr()) {
  const error = result.error;
  
  if (error.tag === "DirectoryConflictError") {
    console.error(`Directory already exists: ${error.directory}`);
  } else if (error.tag === "UserCancelledError") {
    console.log("Operation cancelled by user");
  } else {
    console.error(`Error: ${error.message}`);
  }
  
  process.exit(1);
}

console.log(`Created: ${result.value.projectDirectory}`);

​
Using unwrap Methods

import { create } from "create-better-t-stack";

const result = await create("my-app", {
  frontend: ["tanstack-router"],
  backend: "hono",
});

// Get value or null
const data = result.unwrapOr(null);
if (data) {
  console.log(data.projectDirectory);
}

// Or throw on error
try {
  const data = result.unwrap();
  console.log(data.projectDirectory);
} catch (error) {
  console.error("Failed to create project");
}

​
With Template

import { create } from "create-better-t-stack";

const result = await create("my-app", {
  template: "tanstack",
  // Template pre-configures frontend/backend/database
  // You can still override specific options:
  database: "postgres",
  auth: "better-auth",
});

​
Directory Conflict Handling

import { create } from "create-better-t-stack";

// Overwrite existing directory
const result1 = await create("my-app", {
  frontend: ["tanstack-router"],
  directoryConflict: "overwrite",
});

// Merge with existing directory
const result2 = await create("my-app", {
  frontend: ["tanstack-router"],
  directoryConflict: "merge",
});

// Auto-increment name (my-app-1, my-app-2, etc.)
const result3 = await create("my-app", {
  frontend: ["tanstack-router"],
  directoryConflict: "increment",
});

​
Notes

The create() function runs in silent mode:
  • No interactive prompts
  • No CLI UI output (spinners, colors, etc.)
  • No process exits
  • Analytics disabled by default (disableAnalytics: true)
Avoid using yolo: true in production. It bypasses compatibility checks and validation, which can lead to invalid configurations.

Build docs developers (and LLMs) love

Get started for freeTalk to us