158 lines
22 KiB
Plaintext
158 lines
22 KiB
Plaintext
page wrnexuscli {
|
|
seo {
|
|
title = "@wrnexus/cli"
|
|
description = "Create, develop, build, generate, test, and maintain WRNexusJS apps."
|
|
}
|
|
|
|
view {
|
|
<div class="docs-shell">
|
|
<a class="skip-link" href="#main">Skip to content</a>
|
|
<header class="topbar">
|
|
<a class="brand" href="/"><span>W</span> WRNexusJS</a>
|
|
<nav aria-label="Primary"><a href="/getting-started">Get started</a><a href="/packages">Packages</a><a href="/language">Language</a><a href="/architecture">Architecture</a></nav>
|
|
<div class="topbar-actions"><a class="preview-pill" href="/access">Private preview · v0.2.40</a><button data-wire-theme-toggle class="theme-button" aria-label="Toggle color theme" title="Toggle color theme">◐</button></div>
|
|
</header>
|
|
<div class="mobile-doc-nav"><details><summary>Browse documentation</summary><nav><a href="/getting-started">Get started</a><a href="/packages">Packages</a><a href="/language">Language</a><a href="/architecture">Architecture</a><a href="/tutorial">Tutorial</a><a href="/guides/project-structure">Guides</a><a href="/examples">Examples</a><a href="/search">Search</a></nav></details></div>
|
|
<main class="page package-page">
|
|
<aside class="sidebar"><a href="/packages">← All packages</a><span class="category">Tooling</span><h2>@wrnexus/cli</h2><p>Create, develop, build, generate, test, and maintain WRNexusJS apps.</p><span class="status status-beta">Private preview · 0.2.40</span><nav><a href="#access">Access</a><a href="#guide">Guide</a><a href="#api">Complete API</a></nav></aside>
|
|
<article id="main" class="documentation"><section class="doc-intro"><span class="eyebrow">Tooling · Preview</span><h1>@wrnexus/cli</h1><p>Create, develop, build, generate, test, and maintain WRNexusJS apps.</p><section id="access" class="access-callout"><h2>Private registry access required</h2><p>This package is not available from the public npm registry. After WorkRoot approves access and supplies private registry instructions, install the release-aligned package:</p><pre><code>bun add @wrnexus/cli@0.2.40</code><button type="button" class="copy-button" aria-label="Copy installation command">Copy</button></pre><p><a href="/access">Request preview access</a>. Never put registry tokens in source control.</p></section></section><section id="guide" class="prose"><blockquote>The <code>wrnexus</code> command-line tool that scaffolds, runs, builds, tests, and manages WRNexusJS apps.</blockquote>
|
|
<p>Part of the <strong>WRNexusJS</strong> framework — an SSR-first, Bun-native full-stack web framework.</p>
|
|
<h3 id="overview">Overview</h3>
|
|
<p><code>@wrnexus/cli</code> provides the <code>wrnexus</code> 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.</p>
|
|
<pre data-language="bash"><code>bun add @wrnexus/cli</code></pre>
|
|
<blockquote>Private package — the machine must be authenticated to the <code>wrnexus</code> npm org</blockquote>
|
|
<blockquote>(a read token in <code>~/.npmrc</code>). Requires <strong>Bun</strong> (Node is not supported).</blockquote>
|
|
<p>Once installed, invoke it from an app directory:</p>
|
|
<pre data-language="bash"><code>bunx wrnexus dev
|
|
# or add scripts: "dev": "wrnexus dev .", "build": "wrnexus build ."</code></pre>
|
|
<h3 id="commands">Commands</h3>
|
|
<p>Every command accepts an optional <code>[app-dir]</code> (defaults to <code>.</code>). Commands that read config or <code>.env</code> also accept <code>--profile=<name></code> (see [Profiles](#profiles)).</p>
|
|
<div class="table-wrap"><table>
|
|
<thead><tr><th>Command</th><th>Purpose</th></tr></thead>
|
|
<tbody><tr><td><code>wrnexus dev [app-dir] [--port=3000]</code></td><td>Start the development server with live reload / HMR.</td></tr><tr><td><code>wrnexus build [app-dir]</code></td><td>Build a self-contained production server bundle + assets into <code>dist/</code>.</td></tr><tr><td><code>wrnexus create <app-name></code></td><td>Scaffold a new single app from an inline template.</td></tr><tr><td><code>wrnexus workspace <name></code></td><td>Scaffold a monorepo (<code>apps/*</code> + shared <code>packages/*</code>).</td></tr><tr><td><code>wrnexus workspace add <name></code></td><td>Add and register an app in the current workspace.</td></tr><tr><td><code>wrnexus gateway [--port=3000]</code></td><td>Serve every workspace app behind one port, routed by domain.</td></tr><tr><td><code>wrnexus generate <type> <name></code></td><td>Scaffold a <code>page</code> \</td><td><code>component</code> \</td><td><code>api</code> \</td><td><code>schema</code>.</td></tr><tr><td><code>wrnexus generate routes</code></td><td>Regenerate the typed routes file (<code>app/routes.gen.ts</code>).</td></tr><tr><td><code>wrnexus generate docker</code></td><td>Scaffold <code>Dockerfile</code>, <code>.dockerignore</code>, and <code>docker-compose.yml</code>.</td></tr><tr><td><code>wrnexus generate mobile</code></td><td>Scaffold a Capacitor shell for iOS and Android.</td></tr><tr><td><code>wrnexus mobile add <package...></code></td><td>Install Capacitor plugins and sync native projects.</td></tr><tr><td><code>wrnexus eject <name...></code></td><td>Copy Wire UI component <code>.wrn</code> sources into <code>app/components/</code>.</td></tr><tr><td><code>wrnexus db <cmd></code></td><td>Database migrations and tooling (see [db](#wrnexus-db)).</td></tr><tr><td><code>wrnexus test [app-dir] [--watch]</code></td><td>Run the app's tests via <code>bun test</code> (defaults to the <code>test</code> profile).</td></tr><tr><td><code>wrnexus profiles [app-dir]</code></td><td>List config profiles and their <code>.env</code> files, marking the active one.</td></tr><tr><td><code>wrnexus help</code></td><td>Print usage.</td></tr></tbody></table></div>
|
|
<p><code>wrnexus g</code> is an alias for <code>wrnexus generate</code>.</p>
|
|
<h4 id="wrnexus-dev"><code>wrnexus dev</code></h4>
|
|
<p>Supervises a child dev-server process (from <code>@wrnexus/dev-server</code>). 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 <code>--port=</code> to change the port (default <code>3000</code>).</p>
|
|
<pre data-language="bash"><code>wrnexus dev . --port=8080</code></pre>
|
|
<h4 id="wrnexus-build"><code>wrnexus build</code></h4>
|
|
<p>Emits into <code><app-dir>/dist/</code>:</p>
|
|
<ul>
|
|
<li><code>server.js</code> — a single, minified, self-contained Bun server with a <strong>static</strong> manifest of every page / api / realtime / middleware / component / layout module (no runtime filesystem scan or on-the-fly bundling).</li>
|
|
<li><code>reactive.js</code>, <code>theme.css</code>, <code>theme.js</code>, <code>ui.css</code>, and (if present) <code>styles.css</code> — hashed, minified browser assets.</li>
|
|
<li><code>public/</code> — copied verbatim.</li>
|
|
</ul>
|
|
<p>Before bundling, it regenerates typed queries for the default and every named database. Run the output with:</p>
|
|
<pre data-language="bash"><code>bun dist/server.js # PORT env var optional
|
|
# Generated apps also provide: npm start
|
|
# Build and start together: npm run production</code></pre>
|
|
<h4 id="wrnexus-create"><code>wrnexus create</code></h4>
|
|
<p>Scaffolds a new app from an inline (dependency-free) template — <code>package.json</code>, <code>.gitignore</code>, config, and starter <code>app/</code> files. Use <code>npm run dev</code> during development, <code>npm run build && npm start</code> for production, or <code>npm run production</code> to build and start in one command. The generated production server currently requires Bun even when npm is used to manage packages and scripts.</p>
|
|
<h4 id="wrnexus-update"><code>wrnexus update</code></h4>
|
|
<p><code>wrnexus update --latest</code> performs a complete project upgrade. It hands control to the exact target CLI, backs up important project files under <code>.wrnexus/update-backups/</code>, updates every <code>@wrnexus/*</code> 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 <code>check</code> and <code>build</code> scripts; the new version is recorded only after verification succeeds.</p>
|
|
<p>Use <code>--dry-run</code> to preview an upgrade or <code>--no-verify</code> 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.</p>
|
|
<pre data-language="bash"><code>wrnexus create my-app</code></pre>
|
|
<h4 id="wrnexus-generate"><code>wrnexus generate</code></h4>
|
|
<p>Scaffolds a single file from a template, refusing to overwrite an existing file. Types (with aliases): <code>page</code>/<code>p</code>, <code>component</code>/<code>c</code>, <code>api</code>/<code>a</code>, <code>schema</code>/<code>s</code>. Nested names create nested paths.</p>
|
|
<pre data-language="bash"><code>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</code></pre>
|
|
<p>The mobile generator creates a separate <code>mobile/</code> package and reads <code>config.mobile.mode</code>. <code>webview</code> creates a Capacitor shell that renders the hosted WRNexusJS application. <code>native</code> creates a WebView-free Expo/React Native app whose screens call the shared backend through <code>mobile/src/wrnexus.ts</code>. Native screens do not render <code>.wrn</code> HTML. In either mode, run <code>bun install</code> in <code>mobile/</code>; iOS device builds require macOS and Xcode.</p>
|
|
<p>Install official or community Capacitor plugins through the root CLI:</p>
|
|
<pre data-language="bash"><code>wrnexus mobile add @capacitor/camera @capacitor/haptics
|
|
wrnexus mobile sync
|
|
wrnexus mobile assets # generate native icons from config.mobile.icon</code></pre>
|
|
<p>In native mode, <code>mobile add</code> runs <code>expo install</code> and <code>mobile sync</code> runs Expo prebuild. In WebView mode they retain the Capacitor install/sync behavior. <code>wrnexus mobile compile</code> maps portable <code>app/pages/**/*.wrn</code> pages to Expo Router TSX routes. Native <code>bun run start</code> invokes this compilation automatically.</p>
|
|
<p>Browser code can access installed plugins through the SSR-safe <code>@wrnexus/mobile</code> bridge. The command adds each plugin to both the WRNexusJS app (JavaScript proxy) and <code>mobile/</code> (native synchronization).</p>
|
|
<p><code>wrnexus mobile sync</code> 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.</p>
|
|
<h4 id="wrnexus-eject"><code>wrnexus eject</code></h4>
|
|
<p>Copies a Wire UI component's <code>.wrn</code> source out of <code>@wrnexus/ui</code> into <code>app/components/</code>, 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.</p>
|
|
<pre data-language="bash"><code>wrnexus eject button card modal</code></pre>
|
|
<h4 id="wrnexus-db"><code>wrnexus db</code></h4>
|
|
<p>Database migrations and tooling. Without a flag, commands target the <strong>default</strong> database (<code>db</code> in <code>wrnexus.config.ts</code>, files under <code>app/db/</code>). Pass <code>--db=<name></code> to target a named database (<code>databases.<name></code>, files under <code>app/db/<name>/</code>).</p>
|
|
<div class="table-wrap"><table>
|
|
<thead><tr><th>Subcommand</th><th>Purpose</th></tr></thead>
|
|
<tbody><tr><td><code>db new <name> [--from-models]</code></td><td>Scaffold a migration; <code>--from-models</code> derives it from the TS models in <code>schema.ts</code>.</td></tr><tr><td><code>db migrate</code></td><td>Apply all pending migrations.</td></tr><tr><td><code>db rollback</code></td><td>Revert the last applied migration.</td></tr><tr><td><code>db status</code></td><td>List applied / pending migrations.</td></tr><tr><td><code>db generate</code></td><td>Regenerate typed queries (<code>queries/*.sql</code> → <code>queries.gen.ts</code>).</td></tr><tr><td><code>db seed</code></td><td>Run the database's <code>seed.ts</code> (default export / <code>seed</code> function).</td></tr><tr><td><code>db studio [table]</code></td><td>Inspect tables — list row counts, or dump the first 50 rows of one table.</td></tr></tbody></table></div>
|
|
<pre data-language="bash"><code>wrnexus db new create_users --from-models
|
|
wrnexus db migrate
|
|
wrnexus db studio users
|
|
wrnexus db status --db=analytics</code></pre>
|
|
<h4 id="wrnexus-workspace-and-wrnexus-gateway"><code>wrnexus workspace</code> and <code>wrnexus gateway</code></h4>
|
|
<p><code>workspace <name></code> scaffolds a monorepo: several WRNexusJS apps under <code>apps/*</code> and shared libraries under <code>packages/*</code>, plus a <code>wrnexus.workspace.ts</code> that maps each app to the domains it serves. <code>gateway</code> runs every app behind one port and routes by <code>Host</code> header, with optional per-app auth and gateway-wide security (trusted hosts, rate limit, security headers, access log).</p>
|
|
<pre data-language="bash"><code>wrnexus workspace acme
|
|
wrnexus gateway --port=3000</code></pre>
|
|
<p>From a workspace root, add and register another app in one command:</p>
|
|
<pre data-language="bash"><code>wrnexus workspace add reports --domain=reports.localhost
|
|
bun install</code></pre>
|
|
<p>Development gateways bind to <code>127.0.0.1</code> by default for reliable access on Windows, macOS, and Linux. Open the configured app domain on the gateway port (for example <code>http://localhost:3000</code> or <code>http://admin.localhost:3000</code>), not the internal child ports printed while apps start. Pass <code>--host=0.0.0.0</code> to accept connections from other devices.</p>
|
|
<h4 id="wrnexus-test"><code>wrnexus test</code></h4>
|
|
<p>Runs the app's tests with <code>bun test</code>. Defaults to the <code>test</code> profile (config + <code>.env.test</code>). Pass <code>--watch</code> to re-run on change; extra flags pass straight through to <code>bun test</code>.</p>
|
|
<pre data-language="bash"><code>wrnexus test . --watch</code></pre>
|
|
<h3 id="usage">Usage</h3>
|
|
<h4 id="create-and-run-a-single-application">Create and run a single application</h4>
|
|
<pre data-language="bash"><code>bunx @wrnexus/cli create customer-portal
|
|
cd customer-portal
|
|
bun install
|
|
bun run dev</code></pre>
|
|
<h4 id="add-routes-and-shared-ui-to-an-existing-app">Add routes and shared UI to an existing app</h4>
|
|
<pre data-language="bash"><code>wrnexus generate page reports/monthly
|
|
wrnexus generate api reports/export
|
|
wrnexus generate component report-filter
|
|
wrnexus generate routes</code></pre>
|
|
<h4 id="create-a-multi-app-workspace-and-add-another-app">Create a multi-app workspace and add another app</h4>
|
|
<pre data-language="bash"><code>wrnexus workspace company-suite
|
|
cd company-suite
|
|
wrnexus workspace add reports --domain=reports.localhost
|
|
bun install
|
|
wrnexus gateway --port=3000</code></pre>
|
|
<p>Open <code>http://reports.localhost:3000</code>; the gateway selects <code>apps/reports</code> from the request host.</p>
|
|
<h4 id="upgrade-with-migrations-and-verification">Upgrade with migrations and verification</h4>
|
|
<pre data-language="bash"><code>wrnexus update --latest --dry-run
|
|
wrnexus update --latest
|
|
wrnexus doctor</code></pre>
|
|
<h3 id="profiles">Profiles</h3>
|
|
<p>Pass <code>--profile=<name></code> to <code>dev</code>, <code>build</code>, <code>db</code> (or set <code>WRNEXUS_PROFILE</code>) to select a config profile. The CLI publishes <code>WRNEXUS_PROFILE</code> so config loaders and the dev child pick it up, and loads that profile's <code>.env</code> cascade (<code>.env</code>, <code>.env.local</code>, <code>.env.<profile></code>, <code>.env.<profile>.local</code>) into <code>process.env</code>.</p>
|
|
<pre data-language="bash"><code>wrnexus dev --profile=uat
|
|
wrnexus profiles # ● development (config, .env.development)
|
|
# ○ production
|
|
# ○ uat (config, .env.uat)</code></pre>
|
|
<h3 id="subpath-exports">Subpath exports</h3>
|
|
<p><code>@wrnexus/cli/workspace</code> exposes the workspace configuration types used by <code>wrnexus.workspace.ts</code>:</p>
|
|
<pre data-language="ts"><code>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;</code></pre>
|
|
<h3 id="requirements-notes">Requirements / Notes</h3>
|
|
<ul>
|
|
<li><strong>Bun-only.</strong> The CLI runs on Bun, spawns the Bun binary for the dev child and <code>bun test</code>, and the production build uses <code>Bun.build</code>. Node is not supported.</li>
|
|
<li>Orchestrates the rest of the framework: <code>@wrnexus/dev-server</code> (dev/prod server + gateway), <code>@wrnexus/router</code> (route + typed-routes codegen), <code>@wrnexus/compiler</code> (<code>.wrn</code> → <code>.ts</code>), <code>@wrnexus/db</code> (migrations, typed queries), <code>@wrnexus/styles</code> (config, profiles, <code>.env</code>, themes, styles), <code>@wrnexus/ui</code> (ejectable Wire UI components), <code>@wrnexus/validation</code>, <code>@wrnexus/csr</code>, and <code>@wrnexus/i18n</code>.</li>
|
|
<li>Reads <code>wrnexus.config.ts</code> for <code>db</code> / <code>databases</code>, <code>theme</code>, <code>styles</code>, <code>seo</code>, <code>security</code>, <code>i18n</code>, and <code>profiles</code>, and <code>wrnexus.workspace.ts</code> for the gateway.</li>
|
|
</ul></section><section id="api" class="prose api"><h2>Complete TypeScript API</h2><p>This declaration comes from the exact installed package and lists its exported functions, classes, interfaces, and types.</p><pre data-language="typescript"><code>#!/usr/bin/env bun
|
|
</code></pre></section><section id="examples" class="prose examples"><h2>Examples</h2><p>Examples are taken from this package's installed documentation and must be evaluated with its requirements and stability notes.</p><div class="example-grid"><article class="example-card"><h3>Create and run a single application</h3><pre data-language="bash"><code>bunx @wrnexus/cli create customer-portal
|
|
cd customer-portal
|
|
bun install
|
|
bun run dev</code></pre></article><article class="example-card"><h3>Add routes and shared UI to an existing app</h3><pre data-language="bash"><code>wrnexus generate page reports/monthly
|
|
wrnexus generate api reports/export
|
|
wrnexus generate component report-filter
|
|
wrnexus generate routes</code></pre></article><article class="example-card"><h3>Create a multi-app workspace and add another app</h3><pre data-language="bash"><code>wrnexus workspace company-suite
|
|
cd company-suite
|
|
wrnexus workspace add reports --domain=reports.localhost
|
|
bun install
|
|
wrnexus gateway --port=3000</code></pre></article><article class="example-card"><h3>Upgrade with migrations and verification</h3><pre data-language="bash"><code>wrnexus update --latest --dry-run
|
|
wrnexus update --latest
|
|
wrnexus doctor</code></pre></article></div></section></article>
|
|
<aside class="on-this-page"><h2>On this page</h2><nav><a class="toc-level-2" href="#guide">Guide</a><a class="toc-level-3" href="#overview">Overview</a><a class="toc-level-3" href="#commands">Commands</a><a class="toc-level-4" href="#wrnexus-dev">wrnexus dev</a><a class="toc-level-4" href="#wrnexus-build">wrnexus build</a><a class="toc-level-4" href="#wrnexus-create">wrnexus create</a><a class="toc-level-4" href="#wrnexus-update">wrnexus update</a><a class="toc-level-4" href="#wrnexus-generate">wrnexus generate</a><a class="toc-level-4" href="#wrnexus-eject">wrnexus eject</a><a class="toc-level-4" href="#wrnexus-db">wrnexus db</a><a class="toc-level-4" href="#wrnexus-workspace-and-wrnexus-gateway">wrnexus workspace and wrnexus gateway</a><a class="toc-level-4" href="#wrnexus-test">wrnexus test</a><a class="toc-level-3" href="#usage">Usage</a><a class="toc-level-4" href="#create-and-run-a-single-application">Create and run a single application</a><a class="toc-level-4" href="#add-routes-and-shared-ui-to-an-existing-app">Add routes and shared UI to an existing app</a><a class="toc-level-4" href="#create-a-multi-app-workspace-and-add-another-app">Create a multi-app workspace and add another app</a><a class="toc-level-4" href="#upgrade-with-migrations-and-verification">Upgrade with migrations and verification</a><a class="toc-level-3" href="#profiles">Profiles</a><a class="toc-level-3" href="#subpath-exports">Subpath exports</a><a class="toc-level-3" href="#requirements-notes">Requirements / Notes</a><a class="toc-level-2" href="#api">Complete API</a><a class="toc-level-2" href="#examples">Examples</a></nav></aside>
|
|
</main>
|
|
<footer>WRNexusJS 0.2.40 · Private Developer Preview · Bun-native · Documentation generated from installed package APIs.</footer>
|
|
</div>
|
|
}
|
|
}
|