Skip to content

Latest commit

 

History

History
404 lines (322 loc) · 10.9 KB

README.md

File metadata and controls

404 lines (322 loc) · 10.9 KB

create-tbk-app

CLI tool to scaffold TypeScript Backend Toolkit projects with customizable features.

Quick Start

# Guided prompts (recommended)
npx create-tbk-app my-backend-api

# Skip prompts and use defaults from flags
npx create-tbk-app my-api -y --preset=standard

# Provide defaults and confirm step-by-step
npx create-tbk-app my-api --auth=jwt --cache=redis --email=resend

Features

  • Interactive CLI - Guided setup with smart questions
  • Multiple Presets - Minimal, Standard, or Full-featured configurations
  • Customizable - Pick only the features you need
  • Type-safe - Full TypeScript support throughout
  • Production-ready - Best practices and security built-in

Available Presets

Minimal

Bare-bones API with core features only:

  • Express + TypeScript
  • MongoDB (Mongoose)
  • MagicRouter (auto-generated OpenAPI docs)
  • Basic logging

Use case: Simple APIs, microservices, learning projects

Standard

Production-ready REST API:

  • Everything in Minimal
  • JWT Authentication
  • Security hardening (Helmet, CORS, rate limiting)
  • Memory caching
  • Full observability (logging, metrics, health checks)

Use case: Most production APIs, SaaS backends

Full-Featured

Complete backend with all features:

  • Everything in Standard
  • JWT + Session management (Redis)
  • Redis caching
  • Background jobs (BullMQ)
  • File storage (S3/R2)
  • Email sending (Resend/Mailgun/SMTP)
  • Real-time (Socket.IO)
  • Admin panel
  • Queue dashboard

Use case: Complex applications, enterprise backends

CLI Options

create-tbk-app [project-name] [options]

Options:
  --preset <type>           Preset configuration (minimal, standard, full, custom)
  --auth <type>             Authentication (none, jwt, jwt-sessions)
  --session-driver <driver> Session storage driver (mongo, redis)
  --cache <provider>        Cache provider (none, memory, redis)
  --storage <provider>      Storage provider (none, local, s3, r2)
  --email <provider>        Email provider (none, resend, mailgun, smtp)
  --queues / --no-queues    Toggle background jobs
  --queue-dashboard         Include queue monitoring dashboard (with queues)
  --no-queue-dashboard      Disable queue monitoring dashboard
  --realtime / --no-realtime Toggle real-time features
  --admin / --no-admin      Toggle admin panel
  --google-oauth            Enable Google OAuth login (with auth)
  --observability <level>   Observability level (basic, full)
  --pm <manager>            Package manager (pnpm, npm, yarn)
  --skip-git                Skip git initialization
  --skip-install            Skip dependency installation
  -y, --yes                 Skip prompts and accept defaults
  --force                   Overwrite existing directory without prompting
  -h, --help                Display help
  -V, --version             Display version

Usage Examples

Interactive Mode (Recommended)

npx create-tbk-app

You'll be prompted for:

  1. Project name
  2. Preset selection
  3. Custom features (if preset is "custom")
  4. Package manager preference
  5. Git/install preferences
  6. Final summary confirmation

Non-Interactive Mode

Using presets:

# Minimal setup
npx create-tbk-app my-api --preset=minimal

# Standard with npm
npx create-tbk-app my-api --preset=standard --pm=npm --skip-install --skip-git

# Full-featured
npx create-tbk-app my-api --preset=full

Custom configuration:

# API with auth and caching
npx create-tbk-app my-api \
  --auth=jwt \
  --cache=redis \
  --pm=pnpm

# Full custom
npx create-tbk-app my-api \
  --auth=jwt-sessions \
  --cache=redis \
  --queues \
  --storage=s3 \
  --email=resend \
  --realtime \
  --admin \
  --pm=pnpm \
  --skip-install \
  --skip-git

Skip options:

# Don't install dependencies or init git
npx create-tbk-app my-api --preset=standard --skip-install --skip-git

# Force overwrite and skip prompts
npx create-tbk-app my-api -y --preset=standard --pm=pnpm --force

What Gets Generated

Core Files (Always)

my-api/
├── src/
│   ├── app/              # Application setup & plugin registration
│   ├── config/           # Environment configuration (Zod-validated)
│   ├── lib/              # Core libraries (database, etc.)
│   ├── middlewares/      # Express middlewares
│   ├── modules/          # Feature modules
│   ├── plugins/          # Plugin system
│   ├── routes/           # Route registration
│   ├── types/            # TypeScript types
│   ├── utils/            # Utility functions
│   └── main.ts           # Entry point
├── bin/                  # CLI tool (tbk)
├── public/               # Static assets
├── .env.example          # Environment variables template
├── .gitignore
├── package.json          # With selected dependencies
├── tsconfig.json
├── build.ts
└── README.md             # Custom README with setup instructions

Conditional Files

Based on your selections:

  • Auth: src/modules/auth/, src/modules/user/, auth middleware
  • Cache: src/lib/cache.ts, cache plugin
  • Queues: src/lib/queue.ts, src/queues/
  • Storage: src/lib/storage.ts
  • Email: src/lib/email.ts, src/email/templates/
  • Realtime: src/plugins/realtime/
  • Admin: src/plugins/admin/

After Generation

1. Navigate to Project

cd my-api

2. Configure Environment

# Copy environment template
cp .env.example .env.development

# Edit with your configuration
# Update MongoDB URL, JWT secret, API keys, etc.

3. Start Development

pnpm dev

4. Access Services

Generated Project Commands

pnpm dev              # Start dev server with hot reload
pnpm build            # Build for production
pnpm start:prod       # Run production build
pnpm typecheck        # Type check without building
pnpm lint             # Run ESLint
pnpm tbk docs:openapi # Generate OpenAPI spec
pnpm tbk docs:sdk     # Generate TypeScript SDK

# CLI tool (module generation)
pnpm tbk generate:module <name>        # Generate CRUD module
pnpm tbk generate:plugin <name>        # Generate plugin
pnpm tbk generate:middleware <name>    # Generate middleware

Feature Details

Authentication

  • JWT: Stateless token-based authentication
  • JWT + Sessions: Token auth with server-side session management
  • Session drivers: MongoDB or Redis
  • Password hashing with Argon2
  • Passport.js integration

Caching

  • Memory: In-memory cache (development/testing)
  • Redis: Production-grade distributed cache
  • Tag-based invalidation
  • Middleware for route caching

Background Jobs

  • BullMQ queue system
  • Redis-backed job storage
  • Retry logic and error handling
  • Optional monitoring dashboard

File Storage

  • Local: Store files on disk
  • S3: Amazon S3 storage
  • R2: Cloudflare R2 (S3-compatible)
  • Formidable for file uploads

Email

  • Resend: Modern email API
  • Mailgun: Transactional email service
  • SMTP: Traditional SMTP server
  • React Email for templates

Real-time

  • Socket.IO server
  • Testing UI included
  • CORS configuration

Admin Panel

  • Django-style auto-generated UI
  • Model introspection
  • Full CRUD operations
  • Protected with authentication

Observability

  • Basic: Structured logging (Pino)
  • Full: Logging + Prometheus metrics + Health checks

Architecture

Plugin System

All features are implemented as plugins that can be enabled/disabled:

// src/app/app.ts
const plugins = [
  basicParserPlugin(),
  securityPlugin(),       // If enabled
  observabilityPlugin(),
  authPlugin(),           // If enabled
  realtimePlugin(),       // If enabled
  magicPlugin(),
  lifecyclePlugin(),
];

Module Structure

Each feature module follows a consistent 6-file pattern:

  • *.dto.ts - Zod schemas & types
  • *.model.ts - Mongoose model
  • *.schema.ts - Request/response validation
  • *.services.ts - Business logic
  • *.controller.ts - HTTP handlers
  • *.router.ts - MagicRouter setup

MagicRouter

Auto-generates OpenAPI documentation from Zod schemas:

router.post('/users', {
  requestType: { body: createUserSchema },
  responses: { 201: createUserResponseSchema },
}, canAccess(), handleCreate);

Requirements

  • Node.js: >= 18.0.0
  • MongoDB: Any version compatible with Mongoose 8.x
  • Redis: Required for queues or Redis cache/sessions

Development Status

Current Version: 0.1.0 (Alpha)

✅ Completed

  • CLI implementation with Commander
  • Interactive prompts with Inquirer
  • Preset configurations (minimal, standard, full)
  • Dependency resolver
  • Template engine with Handlebars
  • Configuration file generation (package.json, .env, README)
  • Package manager support (pnpm, npm, yarn)
  • Git initialization
  • Non-interactive mode with flags

🚧 In Progress

  • Template extraction from main toolkit
  • Complete file copying and rendering
  • Plugin-specific templates
  • Module templates

📋 Planned

  • Testing suite
  • Template validation
  • CI/CD examples
  • Docker support
  • Deployment guides

Template Extraction (Next Phase)

The next development phase involves extracting all files from the main toolkit into templates:

  1. Base templates (templates/base/)

    • Core application files
    • Build configuration
    • TypeScript config

  2. Plugin templates (templates/plugins/)

    • One directory per plugin
    • Handlebars variables for customization

  3. Module templates (templates/modules/)

    • Auth module
    • User module
    • Health check module

  4. Library templates (templates/lib/)

    • Cache, queue, storage, email services

Contributing

This is part of the TypeScript Backend Toolkit monorepo. See the main project for contribution guidelines.

Troubleshooting

"Invalid project name"

  • Use lowercase letters, numbers, hyphens, and underscores only
  • Must be a valid npm package name

"Directory already exists"

  • Choose a different project name
  • Or delete/rename the existing directory

Dependencies fail to install

  • Ensure you have Node.js >= 18.0.0
  • Try a different package manager with --pm flag
  • Check your network connection

Import errors after generation

  • Currently in development - template extraction pending
  • Follow the SETUP_NOTICE.md in generated project
  • Manually copy files from main toolkit

License

MIT

Links