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.

​
Installation issues

Problem: Running npm create better-t-stack results in command not foundSolutions:
  1. Use the full npx command: 
    npx create-better-t-stack@latest
  2. Check npm is installed: 
    npm --version
    If not installed, get it from nodejs.org
  3. Clear npm cache: 
    npm cache clean --force
Problem: Error: “Node.js v20 or higher is required”Solution:
  1. Check your Node.js version: 
    node --version
  2. Upgrade Node.js:
    • Download from nodejs.org (LTS version recommended)
    • Or use a version manager: 
      # nvm
nvm install 20
nvm use 20

# fnm
fnm install 20
fnm use 20
Problem: EACCES or permission denied when running npm commandsSolutions:
  1. Don’t use sudo (can cause issues)
  2. Fix npm permissions: 
    mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
  3. Use a version manager:
    • nvm, fnm, or asdf handle permissions automatically

​
Project creation issues

Problem: Error: “Directory ‘my-app’ already exists”Solutions:
  1. Use a different project name: 
    npm create better-t-stack@latest my-app-2
  2. Use directory conflict strategy: 
    # Merge with existing
npm create better-t-stack@latest my-app --directory-conflict merge

# Overwrite existing
npm create better-t-stack@latest my-app --directory-conflict overwrite

# Auto-increment name
npm create better-t-stack@latest my-app --directory-conflict increment
  3. Remove existing directory: 
    rm -rf my-app
npm create better-t-stack@latest my-app
Problem: Error: “Invalid combination: X is not compatible with Y”Solutions:
  1. Check the compatibility matrix: See CLI Compatibility for valid combinations
  2. Use the Stack Builder: Visit better-t-stack.dev/new to see compatible options
  3. Common incompatibilities:
    • Cloudflare Workers requires Hono, Express, Fastify, or Elysia backend
    • Convex backend doesn’t need a runtime selection
    • MongoDB requires Mongoose ORM
    • Some addons require specific frontends (e.g., PWA needs a web framework)
Problem: npm install or bun install fails during project creationSolutions:
  1. Skip auto-install and install manually: 
    npm create better-t-stack@latest my-app --no-install
cd my-app
npm install
  2. Clear package manager cache: 
    # npm
npm cache clean --force

# pnpm
pnpm store prune

# bun
rm -rf ~/.bun/install/cache
  3. Check network connection:
    • Try a different network
    • Check if npm registry is accessible: 
      npm ping
  4. Use a different package manager: 
    npm create better-t-stack@latest my-app --package-manager pnpm

​
Development issues

Problem: TypeScript errors in newly created projectSolutions:
  1. Install dependencies: 
    bun install  # or npm install
  2. Restart TypeScript server: In VS Code: Cmd/Ctrl + Shift + P → “TypeScript: Restart TS Server”
  3. Clear TypeScript cache: 
    rm -rf node_modules/.cache
  4. Regenerate types: 
    # For Convex projects
bun run dev:convex

# For tRPC projects
bun run dev
Problem: Error: “Port 3000 is already in use”Solutions:
  1. Find and kill process using port: 
    # macOS/Linux
lsof -ti:3000 | xargs kill -9

# Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F
  2. Use a different port: 
    PORT=3001 bun run dev
  3. Stop other development servers: Check if you have other dev servers running
Problem: Changes don’t reflect without manual refreshSolutions:
  1. Check file is saved: Ensure auto-save is enabled in your editor
  2. Restart dev server: 
    # Stop with Ctrl+C, then restart
bun run dev
  3. Check file is in watch directories: Some files may be ignored by watch config
  4. Disable any file watchers limit (Linux): 
    echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

​
Database issues

Problem: Error connecting to databaseSolutions:
  1. Check DATABASE_URL: 
    echo $DATABASE_URL
    Verify format matches your database type
  2. For Docker databases, ensure containers are running: 
    docker compose up -d
docker ps
  3. For cloud databases, check:
    • Credentials are correct
    • IP is whitelisted
    • Database exists
    • SSL settings match requirements
  4. Test connection directly: 
    # PostgreSQL
psql $DATABASE_URL

# MySQL
mysql -u user -p -h host database

# MongoDB
mongosh $DATABASE_URL
Problem: Database migrations don’t applySolutions:
  1. Check database connection first: Ensure you can connect to the database
  2. For Drizzle: 
    # Generate migrations
bun run db:generate

# Apply migrations
bun run db:migrate

# Or push schema directly (dev)
bun run db:push
  3. For Prisma: 
    cd packages/db

# Generate Prisma Client
npx prisma generate

# Apply migrations
npx prisma migrate dev
  4. Check migration files: Ensure SQL syntax is valid for your database type
  5. Reset database (dev only): 
    # Drizzle
bun run db:drop && bun run db:push

# Prisma
cd packages/db && npx prisma migrate reset
Problem: Cannot import ‘@prisma/client’Solution:
cd packages/db
npx prisma generate
Or add to postinstall script to auto-generate:
// packages/db/package.json
{
  "scripts": {
    "postinstall": "prisma generate"
  }
}

​
API and networking issues

Problem: CORS policy blocks requestsSolutions:
  1. Check CORS_ORIGIN matches frontend URL: 
    # apps/server/.env
CORS_ORIGIN=http://localhost:3000
  2. For development, allow localhost: 
    // apps/server/src/index.ts
import { cors } from "hono/cors";

app.use(cors({
  origin: process.env.CORS_ORIGIN || "http://localhost:3000",
  credentials: true,
}));
  3. For production, use exact domain: 
    CORS_ORIGIN=https://myapp.com
    Don’t use wildcards (*) in production
Problem: Cannot connect to APISolutions:
  1. Check server URL: 
    # apps/web/.env
VITE_SERVER_URL=http://localhost:3000
  2. Verify server is running: 
    curl http://localhost:3000/trpc/healthcheck
  3. Check network tab in browser: Look for failed requests and error messages
  4. For mobile development, use IP address: 
    # Don't use localhost from mobile device
VITE_SERVER_URL=http://192.168.1.100:3000
Problem: Network requests failSolutions:
  1. Check backend is running: Visit http://localhost:3000 in browser
  2. Verify URLs have http:// or https://: 
    # Wrong
VITE_SERVER_URL=localhost:3000

# Correct
VITE_SERVER_URL=http://localhost:3000
  3. Check firewall: Ensure development server port isn’t blocked
  4. For React Native:
    • Use computer’s IP, not localhost
    • Enable network permissions in app config
    • Check Expo Go or simulator can reach server

​
Build and deployment issues

Problem: Production build fails with TypeScript errorsSolutions:
  1. Run type check locally: 
    bun run check-types
  2. Fix type errors: Check the error messages and fix issues
  3. Ensure all dependencies are installed: 
    bun install --frozen-lockfile
  4. Check generated types are up to date: 
    # For tRPC
bun run dev  # generates types

# For Prisma
cd packages/db && npx prisma generate
Problem: Alchemy deployment failsSolutions:
  1. Check ALCHEMY_PASSWORD is set: 
    echo $ALCHEMY_PASSWORD
  2. Verify Cloudflare credentials: Ensure API token has correct permissions
  3. Check environment variables: All required vars must be in .env files
  4. View deployment logs: 
    bun run deploy --verbose
  5. Test locally first: 
    bun run dev
Problem: Env vars work locally but not in productionSolutions:
  1. Check platform-specific env var setup:
    • Vercel: Dashboard > Project > Settings > Environment Variables
    • Netlify: Site settings > Build & deploy > Environment
    • Cloudflare: Set via Alchemy bindings in alchemy.run.ts
  2. Verify variable names match exactly: Variable names are case-sensitive
  3. For Vite (client-side), use VITE_ prefix: 
    # Works in browser
VITE_API_URL=https://api.example.com

# Server-side only
DATABASE_URL=postgresql://...
  4. Redeploy after adding env vars: Changes to env vars usually require redeployment

​
Runtime issues

Problem: Cannot find module ‘X’Solutions:
  1. Install the package: 
    bun add <package-name>
  2. Check workspace dependencies: 
    bun install
  3. Verify imports are correct: 
    // Wrong
import { foo } from "@my-app/does-not-exist";

// Correct
import { foo } from "@my-app/db";
  4. For workspace packages, rebuild: 
    bun run build
Problem: Application is slowSolutions:
  1. Check database queries: Add indexes, optimize queries, use database query analyzer
  2. Enable production mode: 
    NODE_ENV=production bun run start
  3. Use build tools: Development mode is slower - test performance with production build
  4. Profile the application:
    • Browser DevTools Performance tab
    • Backend: Add timing logs
    • Database: Enable query logging
  5. For Cloudflare Workers:
    • Reduce bundle size
    • Use edge caching
    • Optimize database queries

​
Getting help

If you’re still stuck:

GitHub Discussions

Ask questions and get help from the community

GitHub Issues

Report bugs or request features

FAQ

Check frequently asked questions

Compatibility

Verify your stack combination is valid

​
When reporting issues

Include:
  1. Command you ran: 
    npm create better-t-stack@latest my-app --frontend next --backend hono
  2. Error message: Copy the full error output
  3. Environment: 
    node --version
npm --version
# or bun --version
  4. Operating system: macOS, Linux (which distro), Windows
  5. Steps to reproduce: What you did before the error occurred

Build docs developers (and LLMs) love

Get started for freeTalk to us