@flightdev/cli

The command-line interface for Flight Framework. Create, develop, build, and deploy full-stack applications with a single tool.

Table of Contents

• Installation
• Creating a Project
• Development
• Building for Production
• Running in Production
• Generate Commands
• Configuration
• Environment Variables
• All Commands Reference
• Troubleshooting
• License

Installation

Global Installation (Recommended)

npm install -g @flightdev/cli

After installation, the flight command is available globally:

flight --version
flight --help

Using npx (No Installation)

Run commands without installing:

npx @flightdev/cli create my-app
npx @flightdev/cli dev

Using pnpm or yarn

pnpm add -g @flightdev/cli
# or
yarn global add @flightdev/cli

Creating a Project

Interactive Mode

Run create without arguments for the interactive wizard:

flight create

The wizard guides you through:

1. Project name
2. UI framework selection
3. TypeScript or JavaScript
4. Additional features (forms, auth, i18n, etc.)

Quick Start

Create a project with defaults (React + TypeScript):

flight create my-app
cd my-app
npm install
flight dev

With Options

Specify options to skip prompts:

# React with TypeScript (default)
flight create my-app

# Vue with TypeScript
flight create my-app --ui vue

# Svelte with JavaScript
flight create my-app --ui svelte --no-typescript

# Solid with all features
flight create my-app --ui solid --features forms,auth,i18n

Available UI Frameworks

| Framework | Option | Description | |-----------|--------|-------------| | React | --ui react | Default. Best ecosystem support | | Vue | --ui vue | Composition API with SFC support | | Svelte | --ui svelte | Compiler-based, minimal runtime | | Solid | --ui solid | Fine-grained reactivity | | Preact | --ui preact | Lightweight React alternative | | Qwik | --ui qwik | Resumability-first | | Lit | --ui lit | Web Components | | HTMX | --ui htmx | HTML-driven interactivity |

Create Options

| Option | Description | |--------|-------------| | --ui <framework> | UI framework to use | | --typescript | Use TypeScript (default) | | --no-typescript | Use JavaScript | | --features <list> | Comma-separated features: forms, auth, i18n, db | | --package-manager <pm> | npm, pnpm, yarn, or bun | | --git | Initialize git repository (default: true) | | --no-git | Skip git initialization | | --install | Install dependencies (default: true) | | --no-install | Skip dependency installation | | --raw | Create raw project (100% Web Standards, zero dependencies) | | --empty | Create empty project (just package.json) | | --minimal | Create minimal project (single server file) |

Toolbox Mode (Zero Lock-in)

Start with the minimum and add what you need:

# Raw project - 100% Web Standards, ZERO dependencies
# Works on Bun, Deno, Node 22+, Cloudflare Workers
flight create my-app --raw

# Empty project - just package.json
flight create my-app --empty

# Minimal project - single server file with Flight
flight create my-app --minimal

# Then add packages as needed
cd my-app
flight add http
flight add db
flight add cache

The --raw mode generates code with zero Flight dependencies. You can run it on any runtime and add Flight packages later if you want.

Adding Packages

Add Flight packages to an existing project:

flight add [package]

Available Packages

| Package | Description | |---------|-------------| | http | HTTP server with routing and middleware | | core | File-based routing and configuration | | db | Database abstraction layer | | cache | Caching with multiple adapters | | auth | Authentication adapters | | forms | Type-safe form handling | | i18n | Internationalization | | seo | SEO utilities | | image | Image optimization | | email | Email sending | | realtime | WebSocket and real-time features | | helpers | Optional helper utilities |

Examples

# Add HTTP server
flight add http

# Add database support
flight add db

# Add authentication
flight add auth

# See all packages
flight add

Development

Start the development server with hot module replacement:

flight dev

The dev server includes:

• Hot Module Replacement (HMR)
• Server-Side Rendering (if enabled)
• API routes with hot reload
• TypeScript type checking
• Error overlay with source maps

Dev Options

| Option | Default | Description | |--------|---------|-------------| | -p, --port <number> | 5173 | Port number | | -h, --host <host> | localhost | Host to bind | | --open | false | Open browser automatically | | --https | false | Enable HTTPS with self-signed cert | | --ssr | from config | Enable/disable SSR | | --no-ssr | - | Disable SSR for this session | | --force | false | Force re-optimization of dependencies |

Examples

# Start on port 3000
flight dev -p 3000

# Bind to all interfaces (for network access)
flight dev --host 0.0.0.0

# Open browser and enable HTTPS
flight dev --open --https

# Disable SSR temporarily
flight dev --no-ssr

Building for Production

Build optimized bundles for production:

flight build

The build process:

1. Type checks the project
2. Bundles client and server code
3. Optimizes assets (minification, tree-shaking)
4. Generates static pages (if configured)
5. Creates deployment artifacts

Build Options

| Option | Default | Description | |--------|---------|-------------| | --target <adapter> | from config | Deployment target | | --analyze | false | Generate bundle analysis | | --sourcemap | false | Include source maps | | --no-minify | - | Skip minification |

Deployment Targets

# Node.js server (default)
flight build --target node

# Cloudflare Workers
flight build --target cloudflare

# Vercel
flight build --target vercel

# Netlify
flight build --target netlify

# Static site
flight build --target static

# Docker
flight build --target docker

Build Output

dist/
  client/           # Browser bundles
    assets/
    index.html
  server/           # Server code
    index.js
  static/           # Pre-rendered pages

Running in Production

Start the production server:

flight start

This runs the optimized build with:

• Compression enabled
• Static asset caching
• Production error handling
• Health check endpoint at /_health

Start Options

| Option | Default | Description | |--------|---------|-------------| | -p, --port <number> | 3000 | Port number | | -h, --host <host> | 0.0.0.0 | Host to bind | | --cluster | false | Enable cluster mode | | --workers <number> | CPU cores | Number of workers |

Examples

# Start on port 8080
flight start -p 8080

# Enable cluster mode for multi-core
flight start --cluster --workers 4

Generate Commands

Scaffold new files with correct structure:

flight generate <type> <name>
# or shorthand
flight g <type> <name>

Available Generators

| Type | Alias | Description | |------|-------|-------------| | page | p | New page component | | api | a | API route handler | | component | c | UI component | | action | act | Server action | | middleware | mw | Middleware function | | layout | l | Layout component |

Examples

# Generate a page at /dashboard
flight g page dashboard

# Generate an API route at /api/users
flight g api users

# Generate a reusable component
flight g component Button

# Generate a server action
flight g action submitForm

# Generate middleware
flight g middleware auth

Generated Files

flight g page dashboard
# Creates: src/routes/dashboard.page.tsx

flight g api users
# Creates: src/routes/api/users.get.ts
#          src/routes/api/users.post.ts

flight g component Button
# Creates: src/components/Button.tsx
#          src/components/Button.css

Configuration

Flight uses flight.config.ts (or .js) in the project root:

// flight.config.ts
import { defineConfig } from '@flightdev/core';

export default defineConfig({
  // Server configuration
  server: {
    port: 3000,
    host: 'localhost',
  },

  // Rendering options
  render: {
    defaultMode: 'ssr',        // 'ssr' | 'ssg' | 'spa'
    streaming: true,
  },

  // Build options
  build: {
    outDir: 'dist',
    target: 'node',            // Deployment target
    minify: true,
    sourcemap: false,
  },

  // Routes configuration
  routes: {
    directory: 'src/routes',
  },
});

Environment Variables

Flight automatically loads environment variables:

| File | Environment | Priority | |------|-------------|---------| | .env | All | 1 (lowest) | | .env.local | All | 2 | | .env.development | Development | 3 | | .env.production | Production | 3 | | .env.development.local | Development | 4 (highest) | | .env.production.local | Production | 4 (highest) |

Accessing Variables

// Server-side (full access)
const apiKey = process.env.API_KEY;

// Client-side (only PUBLIC_ prefix)
const publicUrl = process.env.PUBLIC_API_URL;

Only variables prefixed with PUBLIC_ are exposed to the browser.

All Commands Reference

| Command | Description | |---------|-------------| | flight create [name] | Create new project | | flight dev | Start development server | | flight build | Build for production | | flight start | Start production server | | flight generate <type> <name> | Generate files | | flight typecheck | Run TypeScript type checking | | flight lint | Run ESLint | | flight test | Run tests | | flight preview | Preview production build locally | | flight upgrade | Upgrade Flight packages | | flight info | Display project information |

Global Options

Available on all commands:

| Option | Description | |--------|-------------| | --help | Show help | | --version | Show version | | --config <path> | Path to config file | | --cwd <path> | Working directory | | --verbose | Verbose output | | --quiet | Minimal output |

Troubleshooting

Port Already in Use

# Use a different port
flight dev -p 3001

# Or kill the process using the port
npx kill-port 5173

TypeScript Errors on Start

# Force rebuild of type cache
flight dev --force

Permission Denied (Global Install)

# Fix npm permissions
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH

# Or use npx instead
npx @flightdev/cli dev

Slow Dev Server

Check for large node_modules in the routes directory, or try:

# Clear Vite cache
rm -rf node_modules/.vite
flight dev

Build Fails with Memory Error

Increase Node.js memory limit:

NODE_OPTIONS="--max-old-space-size=8192" flight build

License

MIT