CLI Reference

The davaux command is the single entry point for everything — scaffolding, development, building, and serving your application. Install it globally or run it via npx:

npx davaux <command> [options]

Or add it to your package.json scripts and use npm run <script>.

davaux create <name>

Scaffold a new Davaux project in a new directory.

davaux create my-app

Creates the following structure:

my-app/
├── davaux.config.ts
├── package.json
├── tsconfig.json
└── src/
    ├── islands/
    └── routes/
        ├── _layout.tsx
        └── index.page.tsx

After scaffolding, run npm install to install dependencies, then npm run dev to start.

davaux generate <type> [path]

Scaffold individual files inside an existing project. The type argument specifies what kind of file to create:

Examples:

davaux generate page src/routes/about
# → src/routes/about.page.tsx

davaux generate api src/routes/api/users
# → src/routes/api/users.get.ts

davaux generate layout src/routes/dashboard
# → src/routes/dashboard/_layout.tsx

davaux generate island src/islands/Dropdown
# → src/islands/Dropdown.tsx

davaux generate middleware src/routes/admin
# → src/routes/admin/_middleware.ts

davaux dev

Start the development server with live reload.

davaux dev
davaux dev --port 4000
davaux dev --hostname 0.0.0.0

Options:

The dev server watches src/ for changes. Route file changes restart the server and rebuild the router. TypeScript and CSS changes hot-reload without a full restart where possible.

.env file loading — davaux dev automatically loads .env and then .env.local from the project root before starting. Any key already present in the shell environment is left untouched — shell vars always win. This means DATABASE_URL, SESSION_SECRET, and other secrets can live in .env.local (add it to .gitignore) rather than needing to be exported manually before every npm run dev.

davaux build

Compile the application to dist/ for SSR deployment.

davaux build

Outputs:

dist/
├── _davaux/           # Client bundles (islands, CSS)
└── src/routes/        # Compiled route, layout, and middleware files

Run the compiled output with davaux start.

Custom server entry (server.ts)

If a server.ts exists at the project root with a default export, davaux build compiles it to dist/server.js alongside the routes. This lets you take full control of how the server starts — useful for HTTPS/TLS, HTTP/2, WebSocket co-hosting, or Node.js clustering.

The default export receives the compiled app and a static-file handler:

// server.ts
import { createServer } from 'node:https'
import { readFileSync } from 'node:fs'
import { dispatch } from 'davaux/handler'
import type { CompiledApp } from 'davaux/handler'
import type { IncomingMessage, ServerResponse } from 'node:http'

export default function start(
  app: CompiledApp,
  serveStatics: (req: IncomingMessage, res: ServerResponse) => Promise<boolean>,
) {
  return createServer(
    { key: readFileSync('key.pem'), cert: readFileSync('cert.pem') },
    async (req, res) => {
      if (await serveStatics(req, res)) return
      dispatch(req, res, app)
    },
  ).listen(443)
}

serveStatics automatically handles /_davaux/islands.js, /_davaux/styles.css, /_davaux/client.js, and any files in public/ — you only need to call dispatch for application routes.

Dev mode: davaux dev does not use server.ts. Use node --watch --import tsx/esm server.ts to develop with a custom server entry.

davaux start

Serve the compiled dist/ output. Use this in production after running davaux build.

davaux start
davaux start --port 8080

Options:

Like davaux dev, this also loads .env and .env.local from the project root before starting. For most hosting platforms (Railway, Fly, Render, etc.) you'll set secrets as platform environment variables instead, which take priority over .env files.

If dist/server.js exists with a default export, davaux start calls it with (app, serveStatics) instead of starting its own server. See the custom server entry section above.

Reverse proxy

For production deployments, running davaux start behind a reverse proxy is recommended. A proxy handles compression (gzip/brotli), long-lived caching, TLS termination, and static asset serving more efficiently than Node alone.

Caddy is the simplest option — it enables brotli and gzip automatically with zero configuration:

reverse_proxy localhost:3000

A minimal nginx config:

server {
    listen 80;
    gzip on;
    gzip_types text/html text/css application/javascript;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
    }
}

davaux static

Compile the application and pre-render all pages to static HTML files in out/.

davaux static
davaux static --out ./dist/static

Options:

Dynamic routes with [brackets] in their filename must export getStaticPaths to tell Davaux which params to render. Static routes are discovered and rendered automatically.

.env and .env.local are loaded before the build and static generation steps, so any environment variables your pages read at render time are available.

See the Static Generation page for full details.

davaux preview

Serve the SSG output directory locally so you can verify the build before deploying to a CDN.

davaux preview
davaux preview --port 8080
davaux preview --dir ./dist/static

Options:

davaux preview serves static files with correct MIME types, resolves directories to their index.html, and falls back to 404.html if one exists in the output directory. It exits with an error if the directory doesn't exist — run davaux static first.

This is a local verification tool, not a production server. For production, deploy the output directory to a CDN (Netlify, Cloudflare Pages, GitHub Pages) or a static host.

Environment variables

davaux dev always sets NODE_ENV=development. davaux build and davaux static set NODE_ENV=production.