@wrnexus/cli

The wrnexus command-line tool that scaffolds, runs, builds, tests, and manages WRNexusJS apps.

Part of the WRNexusJS framework — an SSR-first, Bun-native full-stack web framework.

Overview

@wrnexus/cli provides the wrnexus executable — the single entry point for developing a WRNexusJS app. It runs the HMR dev server, produces a self-contained production build, scaffolds apps/pages/components, drives database migrations, regenerates typed routes and queries, runs tests, and manages configuration profiles. It also scaffolds multi-app monorepos and serves them behind a domain-routing gateway. This is a CLI/build-time package (it shells out to the Bun binary for the dev child and tests) and it also exports the workspace config types via a subpath.

Installation

bun add @wrnexus/cli

Private package — the machine must be authenticated to the wrnexus npm org

(a read token in ~/.npmrc). Requires Bun (Node is not supported).

Once installed, invoke it from an app directory:

bunx wrnexus dev
# or add scripts: "dev": "wrnexus dev .", "build": "wrnexus build ."

Commands

Every command accepts an optional [app-dir] (defaults to .). Commands that read config or .env also accept --profile=<name> (see [Profiles](#profiles)).

wrnexus g is an alias for wrnexus generate.

wrnexus dev

Supervises a child dev-server process (from @wrnexus/dev-server). The child owns file watching and HMR: CSS and client-island edits update the live page over a WebSocket with no restart; when a server module changes, the child exits with a restart code and the supervisor respawns it (the browser reconnects and morphs in the new HTML). On startup it regenerates typed DB queries and typed routes (best effort). Use --port= to change the port (default 3000).

wrnexus dev . --port=8080

wrnexus build

Emits into <app-dir>/dist/:

• server.js — a single, minified, self-contained Bun server with a static manifest of every page / api / realtime / middleware / component / layout module (no runtime filesystem scan or on-the-fly bundling).
• reactive.js, theme.css, theme.js, ui.css, and (if present) styles.css — hashed, minified browser assets.
• public/ — copied verbatim.

Before bundling, it regenerates typed queries for the default and every named database. Run the output with:

bun dist/server.js   # PORT env var optional
# Generated apps also provide: npm start
# Build and start together: npm run production

wrnexus create

Scaffolds a new app from an inline (dependency-free) template — package.json, .gitignore, config, and starter app/ files. Use npm run dev during development, npm run build && npm start for production, or npm run production to build and start in one command. The generated production server currently requires Bun even when npm is used to manage packages and scripts.

wrnexus update

wrnexus update --latest performs a complete project upgrade. It hands control to the exact target CLI, backs up important project files under .wrnexus/update-backups/, updates every @wrnexus/* dependency, refreshes framework-owned references, and applies every versioned syntax/config/file migration between the project version and target version. After installation it runs the project's check and build scripts; the new version is recorded only after verification succeeds.

Use --dry-run to preview an upgrade or --no-verify when verification is intentionally handled elsewhere. Migrations never overwrite user-owned configuration wholesale: each release must provide a focused, idempotent transformation for any changed syntax or config contract.

wrnexus create my-app

wrnexus generate

Scaffolds a single file from a template, refusing to overwrite an existing file. Types (with aliases): page/p, component/c, api/a, schema/s. Nested names create nested paths.

wrnexus generate page about          # app/pages/about.wrn
wrnexus generate component user-card # app/components/user-card.wrn
wrnexus generate api users/list      # app/api/users/list.ts
wrnexus generate schema signup       # app/schemas/signup.ts
wrnexus generate routes              # regenerate app/routes.gen.ts
wrnexus generate docker              # Dockerfile + compose + .dockerignore
wrnexus generate mobile --mode=webview --app-id=com.example.app --app-name="Example" --url=https://app.example.com
wrnexus generate mobile --mode=native

The mobile generator creates a separate mobile/ package and reads config.mobile.mode. webview creates a Capacitor shell that renders the hosted WRNexusJS application. native creates a WebView-free Expo/React Native app whose screens call the shared backend through mobile/src/wrnexus.ts. Native screens do not render .wrn HTML. In either mode, run bun install in mobile/; iOS device builds require macOS and Xcode.

Install official or community Capacitor plugins through the root CLI:

wrnexus mobile add @capacitor/camera @capacitor/haptics
wrnexus mobile sync
wrnexus mobile assets # generate native icons from config.mobile.icon

In native mode, mobile add runs expo install and mobile sync runs Expo prebuild. In WebView mode they retain the Capacitor install/sync behavior. wrnexus mobile compile maps portable app/pages/**/*.wrn pages to Expo Router TSX routes. Native bun run start invokes this compilation automatically.

Browser code can access installed plugins through the SSR-safe @wrnexus/mobile bridge. The command adds each plugin to both the WRNexusJS app (JavaScript proxy) and mobile/ (native synchronization).

wrnexus mobile sync also configures Android so only true network failures use the local connection-error screen. HTTP errors such as 404 and 500 keep their WRNexusJS response pages.

wrnexus eject

Copies a Wire UI component's .wrn source out of @wrnexus/ui into app/components/, so the app owns and can edit it (the app copy shadows the library one by name). Run with no names to list available components. It skips components that already exist in the app.

wrnexus eject button card modal

wrnexus db

Database migrations and tooling. Without a flag, commands target the default database (db in wrnexus.config.ts, files under app/db/). Pass --db=<name> to target a named database (databases.<name>, files under app/db/<name>/).

wrnexus db new create_users --from-models
wrnexus db migrate
wrnexus db studio users
wrnexus db status --db=analytics

wrnexus workspace and wrnexus gateway

workspace <name> scaffolds a monorepo: several WRNexusJS apps under apps/* and shared libraries under packages/*, plus a wrnexus.workspace.ts that maps each app to the domains it serves. gateway runs every app behind one port and routes by Host header, with optional per-app auth and gateway-wide security (trusted hosts, rate limit, security headers, access log).

wrnexus workspace acme
wrnexus gateway --port=3000

wrnexus test

Runs the app's tests with bun test. Defaults to the test profile (config + .env.test). Pass --watch to re-run on change; extra flags pass straight through to bun test.

wrnexus test . --watch

Profiles

Pass --profile=<name> to dev, build, db (or set WRNEXUS_PROFILE) to select a config profile. The CLI publishes WRNEXUS_PROFILE so config loaders and the dev child pick it up, and loads that profile's .env cascade (.env, .env.local, .env.<profile>, .env.<profile>.local) into process.env.

wrnexus dev --profile=uat
wrnexus profiles          # ● development  (config, .env.development)
                          # ○ production
                          # ○ uat          (config, .env.uat)

Subpath exports

@wrnexus/cli/workspace exposes the workspace configuration types used by wrnexus.workspace.ts:

import type { WorkspaceConfig, WorkspaceApp } from "@wrnexus/cli/workspace";

const config: WorkspaceConfig = {
  security: { trustedHostsOnly: true, headers: true, accessLog: true },
  apps: [{ name: "web", dir: "apps/web", domains: ["localhost", "web.localhost"] }],
};

export default config;

Requirements / Notes

• Bun-only. The CLI runs on Bun, spawns the Bun binary for the dev child and bun test, and the production build uses Bun.build. Node is not supported.
• Orchestrates the rest of the framework: @wrnexus/dev-server (dev/prod server + gateway), @wrnexus/router (route + typed-routes codegen), @wrnexus/compiler (.wrn → .ts), @wrnexus/db (migrations, typed queries), @wrnexus/styles (config, profiles, .env, themes, styles), @wrnexus/ui (ejectable Wire UI components), @wrnexus/validation, @wrnexus/csr, and @wrnexus/i18n.
• Reads wrnexus.config.ts for db / databases, theme, styles, seo, security, i18n, and profiles, and wrnexus.workspace.ts for the gateway.