import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs"; import { execFileSync } from "node:child_process"; import { join, resolve } from "node:path"; import { format } from "prettier"; const root = resolve(import.meta.dir, ".."); const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8")); const version = pkg.wrnexus.version as string; const pages = join(root, "app", "pages"); const docs = join(root, "docs"); const pub = join(root, "public"); mkdirSync(docs, { recursive: true }); const packageNames = [...Object.keys(pkg.dependencies), ...Object.keys(pkg.devDependencies)] .filter((name) => name.startsWith("@wrnexus/")) .map((name) => name.split("/")[1]!) .filter((name, index, all) => all.indexOf(name) === index) .sort(); const packageCount = packageNames.length; const cliEntry = join(root, "node_modules", "@wrnexus", "cli", "dist", "index.js"); const cliHelp = execFileSync(process.execPath, [cliEntry, "--help"], { cwd: root, encoding: "utf8", env: { ...process.env, WRNEXUS_DISABLE_UPDATE_CHECK: "1" }, }).trim(); const cliReference = `# Complete CLI command reference This section is generated from the installed \`@wrnexus/cli@${version}\` executable. It is the canonical command inventory for this release. \`\`\`text ${cliHelp} \`\`\` ## CLI workflows with expected output Commands below are copy-ready. Paths, ports, counts, and timings vary by project; the shown output identifies the success condition to check. ### Create, check, build, and preview an application \`\`\`bash bunx @wrnexus/cli@${version} create my-app cd my-app bun install bunx wrnexus typecheck . bunx wrnexus build . bunx wrnexus preview . --port=3000 \`\`\` Expected output: \`\`\`text ✓ Application types are valid ✓ Runtime: .../dist/reactive.js ✓ Styles: .../dist/styles.css ✓ Server: .../dist/server.js Run it: bun .../dist/server.js \`\`\` ### Generate framework files and committed application types \`\`\`bash bunx wrnexus generate page Dashboard bunx wrnexus generate component status-card bunx wrnexus generate api health bunx wrnexus generate schema account bunx wrnexus generate routes bunx wrnexus generate types . \`\`\` Expected output includes created source paths followed by: \`\`\`text ✓ Generated app/routes.gen.ts (... routes) ✓ Generated .../app/types/wrnexus.generated.d.ts (... routes, ... components) \`\`\` ### Run development and production-runtime modes \`\`\`bash bunx wrnexus dev . --port=3000 bunx wrnexus dev . --services --services-port=3099 bunx wrnexus dev . --production-runtime --port=3000 \`\`\` Expected output reports the active profile, discovered plugins/routes, generated cache path, and listening URL. Production-runtime mode rebuilds and reloads the exact production artifact. ### Database lifecycle \`\`\`bash bunx wrnexus db status bunx wrnexus db new create_accounts --from-models bunx wrnexus db migrate bunx wrnexus db generate bunx wrnexus db seed \`\`\` Expected output identifies the selected profile/dialect, migration state, applied migration names, and generated typed query files. Run \`db rollback\` only when intentionally reverting the latest migration. ### Diagnose, inspect, and enforce contracts \`\`\`bash bunx wrnexus doctor . bunx wrnexus typecheck . bunx wrnexus compatibility check . bunx wrnexus contracts check . bunx wrnexus security audit . bunx wrnexus inspect packages . bunx wrnexus inspect routes . bunx wrnexus inspect component Navbar . bunx wrnexus analyze . \`\`\` Successful checks exit with status 0. Inspect commands print the resolved package, route, component, asset, runtime, style, migration, or bundle contract without changing the application. ### Tests, API artifacts, SDKs, and deployment manifests \`\`\`bash bunx wrnexus test unit . bunx wrnexus test component . bunx wrnexus test api . bunx wrnexus test browser . bunx wrnexus api generate . bunx wrnexus api docs . bunx wrnexus sdk generate typescript . bunx wrnexus deploy docker . \`\`\` Test commands return the underlying suite summary and a nonzero status on failure. API/SDK/deploy commands report each generated artifact; review and commit generated files after validation. ### Workspaces and environments \`\`\`bash bunx wrnexus workspace company-platform cd company-platform bunx wrnexus workspace add reports --domain=reports.localhost bunx wrnexus gateway --port=3000 bunx wrnexus production . --prepare-only bunx wrnexus staging . \`\`\` Expected output lists created apps, domain mappings, selected environment/profile, build and migration decisions, and the gateway address. ### Internationalization, native targets, MCP, and support bundles \`\`\`bash bunx wrnexus i18n extract . bunx wrnexus i18n validate . bunx wrnexus generate mobile bunx wrnexus mobile compile bunx wrnexus native list bunx wrnexus mcp . bunx wrnexus report . --file=app/pages/index.wrn \`\`\` Expected output identifies extracted/validated translation keys, generated native routes, available capabilities, MCP stdio startup, or the sanitized reproduction archive. MCP uses stdio, so protocol messages—not a web URL—are its normal runtime output. ### Safe upgrades \`\`\`bash bunx wrnexus update . --latest --dry-run bunx wrnexus update . --latest \`\`\` The dry run previews dependency and migration changes. A real update prints the source and target versions, backup directory, each migration action, installation result, and verification result. Commit or back up the application before upgrading.`; const uiReferencePath = join(root, "node_modules", "@wrnexus", "ui", "component-reference.json"); const uiReference = existsSync(uiReferencePath) ? (JSON.parse(readFileSync(uiReferencePath, "utf8")) as { count: number; components: Array<{ name: string; mount: string; category: string; purpose: string; source: string; props: Array<{ name: string; type: string; required: boolean; default: string | null }>; slots: string[]; events: string[]; }>; }) : undefined; const uiReferenceText = uiReference ? uiReference.components .map( (component) => `### ${component.name}\nShowcase: https://component.wrnexusjs.dev/\nMount: <${component.mount} /> (legacy: data-component="${component.mount}")\nCategory: ${component.category}\nPurpose: ${component.purpose}\nProps: ${component.props.length ? component.props.map((prop) => `${prop.name}: ${prop.type}${prop.required ? " (required)" : ` = ${prop.default}`}`).join(", ") : "none"}\nSlots: ${component.slots.join(", ") || "none"}\nEvents: ${component.events.join(", ") || "none"}`, ) .join("\n\n") : "UI component reference unavailable; install the release-aligned @wrnexus/ui package."; async function writeFormatted(path: string, source: string) { writeFileSync(path, await format(source, { filepath: path })); } const esc = (s: string) => s.replaceAll("{", "{").replaceAll("}", "}"); const code = (s: string) => `
${esc(s).replaceAll("<", "<").replaceAll(">", ">")}
`; const navigation = [ ["/getting-started", "Get started"], ["/packages", "Packages"], ["https://component.wrnexusjs.dev/", "Components"], ["/language", "Language"], ["/architecture", "Architecture"], ] as const; const documentationNavigation = [ ...navigation, ["/tutorial", "Tutorial"], ["/guides/project-structure", "Guides"], ["/examples", "Examples"], ["/search", "Search"], ] as const; const packageNavigation = packageNames .map((name) => `@wrnexus/${name}`) .join(""); const sectionNavigation = ``; function documentationFrame(body: string): { body: string; toc: string } { const headings: Array<{ id: string; title: string; level: number }> = []; const used = new Set(); const framed = body.replace( /([\s\S]*?)<\/h\1>/g, (_match, levelText, idAttribute, existingId, rawTitle) => { const title = rawTitle .replace(/<[^>]+>/g, "") .replace(/&[^;]+;/g, " ") .trim(); let id = existingId || title .toLowerCase() .replace(/[^a-z0-9]+/g, "-") .replace(/^-|-$/g, "") || "section"; const base = id; let suffix = 2; while (used.has(id)) id = `${base}-${suffix++}`; used.add(id); headings.push({ id, title, level: Number(levelText) }); return `${rawTitle}`; }, ); const toc = headings .map(({ id, title, level }) => `${title}`) .join(""); return { body: framed, toc }; } function shell(title: string, description: string, body: string, section = "Documentation") { const nav = navigation.map(([href, label]) => `${label}`).join(""); const mobileNav = documentationNavigation .map(([href, label]) => `${label}`) .join(""); const breadcrumbs = title === "Home" ? "" : ``; const framed = documentationFrame(body); return `page ${title.replace(/[^A-Za-z0-9]/g, "") || "Guide"} { seo { title = "${title.replaceAll('"', "'")}" description = "${description.replaceAll('"', "'")}" canonical = "https://wrnexusjs.dev${routeFor(title)}" } view {
W WRNexusJS
Preview · v${version}
Browse documentation
${sectionNavigation}
${breadcrumbs}${framed.body}
} }`; } function marketingShell(description: string, body: string) { const codeCard = `
app/pages/dashboard.wrn
page Dashboard {
  ssr { api tasks GET /api/tasks { return tasks } }
  view {
    <main>
      <h1>Tasks</h1>
      {#each tasks as task}
        <article>{task.title}</article>
      {:empty}
        <p>Nothing waiting.</p>
      {/each}
    </main>
  }
}
`; const marketingBody = body .replace("hero portal-hero", "hero marketing-hero") .replace( "Packages require approved private-registry access. No public installation command is currently available.", "Private developer preview. Request access to the package registry.", ) .replace("", `${codeCard}`); return `page Home { seo { title = "WRNexusJS — Bun-native server-first framework" description = "${description.replaceAll('"', "'")}" canonical = "https://wrnexusjs.dev/" } view {
W WRNexusJS
Private preview · v${version}
Menu
${marketingBody}
} }`; } const slugs: Record = { Home: "", Packages: "/packages", "Getting started": "/getting-started", Tutorial: "/tutorial", Architecture: "/architecture", "The .wrn language": "/language", }; function routeFor(title: string) { return ( slugs[title] ?? `/${title .toLowerCase() .replace(/[^a-z0-9]+/g, "-") .replace(/^-|-$/g, "")}` ); } function page(route: string, title: string, description: string, body: string, section?: string) { const path = route === "/" ? join(pages, "index.wrn") : join(pages, `${route.slice(1)}.wrn`); mkdirSync(resolve(path, ".."), { recursive: true }); slugs[title] = route; writeFileSync(path, shell(title, description, body, section)); } const status = ``; writeFileSync( join(pages, "index.wrn"), marketingShell( "WRNexusJS is a Bun-native, SSR-first full-stack framework using the .wrn component language.", `
${status}

WRNexusJS v${version}

Build from the server.
Ship only what matters.

WRNexusJS is an SSR-first, Bun-native full-stack framework. Build typed pages, APIs, validated forms, realtime rooms, secure sessions, workspaces, and optional mobile experiences with the .wrn component language.

Request preview accessRead the preview docs

Packages require approved private-registry access. No public installation command is currently available.

Why WRNexusJS

Server-first rendering

Useful HTML is rendered first; reactive scopes hydrate only where declared.

.wrn components

Pages, layouts, props, state, events, server loops, and directives live in a focused language.

Bun-native runtime

The runtime is Bun. Node compatibility is not claimed.

Typed data and validation

Database queries and shared validation connect server routes to forms.

Integrated security

CSP, CSRF, sessions, authorization, encryption, and safe output are framework primitives.

Realtime and workspaces

Rooms, Redis pub/sub, and multi-app gateways support live and isolated applications.

A small full-stack flow

${code(`// app/schemas/contact.ts\nimport { v } from "@wrnexus/validation";\nexport default v.object({ email: v.string().email(), message: v.string().min(10) });\n\n// app/api/contacts.ts\nimport schema from "../schemas/contact";\nimport { parseBody } from "@wrnexus/validation";\nexport const POST = async (ctx) => {\n const result = await parseBody(schema, ctx.req);\n return result.ok ? Response.json({ ok: true }, { status: 201 }) : result.response;\n};`)}

Request lifecycle

  1. RequestSecurity headers and request limits
  2. MiddlewareAuthentication, policy, and context
  3. File routePage or API handler
  4. Compiler + SSRSafe HTML and scoped runtime
  5. ResponseHTML, JSON, stream, or realtime upgrade

Production proof

WorkRoot

Public creator/company site and approved WRNexusJS production showcase.

wrnexusjs.dev

This documentation application runs WRNexusJS ${version}.

View deployment notes and showcase status →

Capability status

CapabilityStatusDetails
SSR, routing, compiler, APIsPreviewInstalled in ${version}; public support policy pending.
Mobile/nativeExperimentalCapacitor compatibility and native generation have platform limitations.
Durable queuesExperimentalProduction durability requires an appropriate driver strategy.

Continue exploring

Explore ${packageCount} packagesRelease notesRoadmapSupport and access
`, ), ); page( "/access", "Access", "Request access to the WRNexusJS private developer preview.", `
${status}

Request preview access

WRNexusJS ${version} packages are not available from the public npm registry. Installation requires approval and private registry credentials supplied by WorkRoot. Never paste registry tokens into source control, issue reports, or support messages.

Request process

  1. Contact WorkRoot through the public contact path at workroot.in.
  2. Describe the application, team, expected deployment, and Bun environment.
  3. After approval, follow the registry instructions supplied privately.
  4. Use the canonical scaffold command below only after authentication.
${code(`bunx @wrnexus/cli@${version} create my-app`)}

Access approval, response time, licensing terms, and support level remain owner-controlled. This site does not collect access requests directly.

`, "Status", ); page( "/getting-started", "Getting started", "Build and run a first WRNexusJS application after receiving private preview access.", `
Preview guide · v${version}

Build a contact inbox

This path creates a server-rendered page, validated API route, middleware, and realtime next step. It requires approved registry access and Bun 1.3.x; this site was verified with Bun 1.3.14.

1. Create the project

${code(`bunx @wrnexus/cli@${version} create my-app\ncd my-app\nbun install\nbun run dev`)}

2. Know the structure

${code(`app/pages/ # file-based .wrn routes\napp/components/ # reusable .wrn components\napp/api/ # TypeScript request handlers\napp/middleware/ # ordered request middleware\napp/schemas/ # shared validation\napp/realtime/ # realtime rooms\nwrnexus.config.ts`)}

3. Add a page

${code(`page Contacts {\n view {\n

Contact inbox

\n
\n \n \n \n
\n
\n }\n}`)}

4. Validate an API route

${code(`import schema from "../schemas/contact";\nimport { parseBody } from "@wrnexus/validation";\nexport const POST = async (ctx) => {\n const result = await parseBody(schema, ctx.req);\n return result.ok ? Response.json({ ok: true }, { status: 201 }) : result.response;\n};`)}

5. Load server data

Use an ssr API binding and a server {#each} block. See Server data for the complete verified pattern.

6. Add middleware

${code(`export default async function logger(ctx, next) {\n console.log(ctx.req.method, ctx.url.pathname);\n return next();\n}`)}

7. Test and ship

${code(`bun run test\nbun run build\nbun dist/server.js`)}

Next: deployment, database, authentication, and workspaces.

`, ); page( "/tutorial", "Tutorial", "Build a secure task application with WRNexusJS preview APIs.", `
Preview · runnable-project extraction pending

Secure task board

This tutorial connects the installed ${version} APIs into one design. Snippets are limited to declarations and README patterns verified in the installed packages; a CI-compiled standalone fixture remains on the roadmap.

Application shape

A .wrn page renders tasks from an SSR API binding. A shared validation schema protects mutations. Session middleware identifies users, authorization policies gate updates, and a realtime room broadcasts changes.

Schema and create route

${code(`import { v, parseBody } from "@wrnexus/validation";\nconst task = v.object({ title: v.string().trim().min(3).max(120) });\nexport const POST = async (ctx) => {\n const parsed = await parseBody(task, ctx.req);\n if (!parsed.ok) return parsed.response;\n return Response.json({ ok: true, task: parsed.value }, { status: 201 });\n};`)}

Server-rendered list

${code(`page Tasks {\n ssr { api tasks GET /api/tasks { return tasks } }\n view {\n

Tasks

    \n {#each tasks as task}
  • {task.title}
    • {:empty}
  • No tasks yet.
    • {/each}\n
\n }\n}`)}

Production checklist

  • Choose SQLite for local development or configure the supported PostgreSQL driver.
  • Run migrations before accepting traffic.
  • Enable session authentication and enforce authorization on every mutation.
  • Validate upload types and sizes; keep private objects behind authenticated routes.
  • Use Redis pub/sub when realtime rooms span processes.
  • Treat the default queue as non-durable until a production driver is selected.

Follow the focused database, authentication, authorization, realtime, and upload guides.

`, ); page( "/architecture", "Architecture", "WRNexusJS request lifecycle, compiler, runtime, security, data, realtime, workspace, deployment, and mobile architecture.", `
Framework architecture · ${version}

Architecture

WRNexusJS is Bun-native and SSR-first. File discovery maps pages and API handlers; middleware enriches or short-circuits a request; the compiler turns .wrn declarations into server render functions and small feature runtimes.

Request and build lifecycle

  1. DiscoverPages, APIs, middleware, components, layouts, schemas, rooms
  2. CompileParse .wrn, validate grammar, generate server code
  3. RequestLimits, security, locale, session, middleware
  4. MatchStatic and dynamic file route
  5. RenderSSR data, escaped interpolation, components, metadata
  6. EnhanceOnly required reactive/directive runtimes

Package boundaries

core owns contexts, middleware, sessions and rooms; router discovers routes; compiler parses .wrn; ssr renders documents; csr supplies browser runtimes; dev-server and cli orchestrate development and builds.

Security and data flow

Validation happens at trust boundaries. Session authentication establishes identity; authorization makes resource decisions. CSP, Trusted Types, CSRF, upload checks, WebSocket origins, request limits, and output escaping are layered controls—not substitutes for application policy.

Realtime and scale

Rooms are process-local unless connected through pub/sub. Redis-backed pub/sub distributes events. Queue durability depends on the selected driver and must be evaluated explicitly.

Workspaces and gateways

The gateway can dispatch multiple applications while preserving route, component, asset, config, and session boundaries. Validate host routing and isolation before production.

Build and deployment

wrnexus build . produces dist/server.js and hashed/static assets. Run the server with Bun, apply migrations before traffic, terminate TLS at a trusted edge, and forward only expected proxy headers.

Mobile

Mobile compatibility bridges SSR-safe Capacitor capabilities; native route generation is experimental and is not general web portability. Test each target platform.

Generated files and limits

app/routes.gen.ts, .wrnexus/, and dist/ are generated. The runtime is Bun-only. Preview packages are private. Historical compatibility and long-term support policy are not yet published.

`, ); page( "/language", "The .wrn language", "Reference for WRNexusJS .wrn pages, components, layouts, props, state, directives, forms, security, and errors.", `
Language reference · ${version}

The .wrn language

File anatomy

${code(`page Account {\n layout = "public"\n seo { title = "Account" description = "Manage your account." }\n state count = 0\n view { }\n}`)}

Pages, components, layouts, props, and state

Pages are routes. Components declare default-valued props and may hold state. Layouts provide shared slots. Mount components with data-component; fill default or named slots with data-slot.

Interpolation, conditionals, and loops

Interpolation is HTML-escaped. Use server {#if} and {#each} for SSR data. Use data-show for reactive client visibility.

Events and directives

@click and other events execute in the reactive scope. Data attributes opt into forms, i18n, themes, realtime, uploader, browser, and mobile behavior. Consult the exact package page because availability varies.

Forms, i18n, themes, and realtime

form[data-schema] connects descriptors to client and server validation. Translation keys use {t:key}. Theme toggles use data-wire-theme-toggle. Realtime pages opt into a named room.

Escaping and security

Text interpolation is escaped by default. Do not construct trusted HTML from user input. Server-only refinements must be repeated at the authoritative mutation boundary.

Common compiler errors

  • Use balanced braces; a literal brace must be escaped.
  • Declare UI in view, not JSX or hooks.
  • Use a valid page, component, or layout declaration matching the file role.
  • Keep server loops tied to available SSR bindings.
  • Check troubleshooting and compiler API for this release.
`, ); const guides: Record = { "project-structure": [ "Project structure", "How source, public, generated, and build files are organized.", "Pages, components, layouts, APIs, middleware, schemas, database files, locales, realtime rooms, and styles live under app. Never edit app/routes.gen.ts, .wrnexus, or dist by hand.", ], routing: [ "Routing", "File-based page and API routing.", "A page filename defines its URL; index maps to the directory root and bracket segments are dynamic parameters. API files under app/api expose HTTP method functions and receive a Context.", ], "pages-and-components": [ "Pages and components", "Compose .wrn pages, layouts, props, state, and slots.", "Pages are routable, components are reusable, and layouts provide shared slots. Mount a component with data-component and keep browser state scoped and minimal.", ], "server-data": [ "Server data", "Render API-backed data with SSR bindings.", "Use an ssr API binding, return the desired response field, and render it with a server #each block. Values are escaped. Avoid fetching private data through a route that lacks authorization.", ], "api-routes": [ "API routes", "Build typed Bun-native HTTP handlers.", "Export GET, POST, PUT, PATCH, or DELETE from app/api files. Validate request bodies, enforce authentication and authorization, cap request sizes, and return Web Responses.", ], middleware: [ "Middleware", "Order and short-circuit request middleware.", "Middleware receives context and next. Return next() to continue or return a Response to stop. Put request limits and trust-boundary controls before business logic.", ], "forms-and-validation": [ "Forms and validation", "Share validation between forms and API routes.", "Define a v.object schema, use data-schema on the form, show field errors with data-error, and always call parseBody on the server. refine is server-only.", ], authentication: [ "Authentication", "Session and identity boundaries.", "Configure session authentication, log users in through supported auth helpers, and read identity from context. Cookie flags, rotation, expiry, and secret storage remain deployment responsibilities.", ], authorization: [ "Authorization", "Roles, permissions, policies, and resource checks.", "Authentication identifies; authorization decides. Enforce permissions in server routes and policies, including object ownership. UI hiding is never an authorization boundary.", ], security: [ "Application security", "Configure layered WRNexusJS security controls.", "Use CSP, CSRF, Trusted Types, session hardening, validation, origin checks, upload restrictions, encryption, request limits, and explicit CORS. See the security policy for reporting.", ], database: [ "Database", "Drivers, models, typed SQL, migrations, and deployment.", "Configure SQLite or the installed supported driver, keep queries in named SQL blocks, generate typed functions, and apply migrations before traffic. Back up data and test rollback independently.", ], uploads: [ "Uploads", "Validated local and S3-compatible file handling.", "Configure named stores, accepted MIME/extensions, and maxBytes. Random keys avoid path traversal. Private files require an authenticated serving route; v1 buffers each file in memory.", ], realtime: [ "Realtime", "Define rooms and secure WebSocket traffic.", "defineRoom handles connection and messages. Validate message shapes, authorize subscriptions, restrict origins, bound payloads, and use pub/sub to scale across processes.", ], pubsub: [ "Pub/sub", "Scale events with in-process or Redis-backed pub/sub.", "The in-process driver cannot cross processes. Use Redis where instances must share events, define channel ownership, and design for reconnects and duplicate delivery.", ], queues: [ "Queues", "Run delayed, retried, and repeated jobs.", "Queue behavior is preview-level. Treat in-process work as non-durable, make handlers idempotent, cap retries, record failures, and choose a production persistence strategy.", ], testing: [ "Testing", "Test compiled components, routes, and browser behavior.", "Use Bun tests and @wrnexus/test helpers. Cover server HTML, API status and validation, authorization failures, reactive behavior, and a production startup smoke test.", ], "workspaces-and-gateway": [ "Workspaces and gateway", "Add applications, route domains, and implement safe SSO forward authentication.", `

A workspace runs isolated applications behind one domain-routing gateway. Add an application from the workspace root; the CLI scaffolds apps/reports and registers it in wrnexus.workspace.ts:

${code(`wrnexus workspace add reports --domain=reports.localhost bun install bun run dev`)}

Forward authentication

Point protected applications at a dedicated verifier endpoint. The verifier must return 2xx for an authenticated session, 401/403 to deny access, or an HTTP redirect to begin browser login.

${code(`// wrnexus.workspace.ts { name: "admin", dir: "apps/admin", domains: ["admin.localhost"], auth: { forward: { url: "http://sso.localhost:3000/api/verify" } }, }`)}

The gateway forwards cookies, authorization, original host, protocol, method, path, and query. Inside the verifier, ctx.url identifies the SSO verifier request—not the original admin URL. Use @wrnexus/helpers to reconstruct and validate the original destination:

${code(`import type { Context } from "@wrnexus/core"; import { redirectToLogin } from "@wrnexus/helpers"; export const GET = async (ctx: Context) => { if (await hasValidSession(ctx)) { return new Response(null, { status: 204 }); } return redirectToLogin(ctx, "/login", { allowedHosts: ["admin.localhost:3000", "reports.localhost:3000"], }); };`)}

Always allowlist redirect hosts. After login, validate or sign the returnTo value before redirecting. Keep internal app ports private and open applications through the gateway port.

`, ], deployment: [ "Deployment", "Build and run WRNexusJS with Bun.", "Run bun run build, apply migrations, and start dist/server.js with Bun. Configure TLS, proxy trust, environment validation, health checks, graceful restarts, logs, backups, and restrictive security headers.", ], "configuration-and-profiles": [ "Configuration and profiles", "Use typed config and environment-specific profiles.", "wrnexus.config.ts owns styles, SEO, security, data, mobile, fonts, and profiles. Keep secrets in validated environment variables and review merged production configuration.", ], "i18n-and-themes": [ "Internationalization and themes", "Load translations and token-based themes.", "Store locale JSON under app/locales and use translation directives. Themes resolve CSS tokens; ensure contrast, system preference behavior, persistence, and non-color cues.", ], mobile: [ "Mobile", "Understand experimental webview and native modes.", "Mobile capabilities are experimental in this preview. Test Capacitor permissions and lifecycle on each platform; do not assume every .wrn or browser API converts to native.", ], observability: [ "Observability", "Capture errors and events without leaking private data.", "Use tracking middleware and sinks with redaction, sampling, stable request identifiers, alert ownership, and retention limits. Never capture registry tokens or session secrets.", ], upgrading: [ "Upgrading", "Upgrade aligned WRNexusJS packages safely.", `Back up and commit first, then use wrnexus update --latest as documented by the installed CLI. Review migrations and keep every @wrnexus package aligned. Current release: ${version}.`, ], troubleshooting: [ "Troubleshooting", "Diagnose compiler, routing, build, and runtime failures.", "Confirm Bun and package versions, regenerate docs/routes through supported commands, read the first compiler diagnostic, check file naming, validate config, and reproduce under a production build.", ], "full-stack-auth-demo": [ "Auth and permissions dashboard demo", "Create a complete demonstration site with public pages, authentication, configuration profiles, a protected dashboard, roles, permissions, database migrations, tests, and a production build.", `

This walkthrough builds a small team portal. Public visitors can read the home and pricing pages, users can sign in, and the dashboard separates ordinary members from administrators. Every authorization decision remains on the server.

1. Create the application

${code(`bunx @wrnexus/cli@${version} create team-portal cd team-portal bun install bun add @wrnexus/auth @wrnexus/authz @wrnexus/db @wrnexus/validation @wrnexus/ui bunx wrnexus generate page pricing bunx wrnexus generate page login bunx wrnexus generate page dashboard bunx wrnexus generate api session/login bunx wrnexus generate api session/logout bunx wrnexus generate schema login bunx wrnexus authz init --dialect=sqlite bunx wrnexus db new initial_auth --from-models bunx wrnexus db migrate bunx wrnexus generate types .`)}

Expected success output includes created file paths, an initialized authorization catalog, the applied migration name, and the generated application declaration path.

2. Configure profiles and security

${code(`// wrnexus.config.ts import type { AppConfig } from "@wrnexus/styles"; const config: AppConfig = { seo: { title: "Team Portal", titleTemplate: "%s | Team Portal" }, theme: { default: "system", palette: "violet" }, security: { contentSecurityPolicy: true, csrf: true, frameOptions: "deny", }, profiles: { development: { envFiles: [".env", ".env.development"] }, production: { envFiles: [".env", ".env.production"] }, }, }; export default config;`)}${code(`# .env.example — commit names, never real secrets DATABASE_URL=sqlite:./data/team-portal.db SESSION_SECRET=replace-with-at-least-32-random-bytes APP_ORIGIN=http://localhost:3000`)}

Run wrnexus config . --explain --profile=production before deployment and confirm no development fallback or secret value is printed.

3. Create public pages and layout

${code(`// app/layouts/public.wrn layout Public { view {