docs: publish package usage examples for 0.2.24
This commit is contained in:
+71
-71
@@ -1,5 +1,5 @@
|
||||
{
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"status": "private-developer-preview",
|
||||
"generatedAt": "2026-07-13",
|
||||
"documents": [
|
||||
@@ -7,476 +7,476 @@
|
||||
"url": "/",
|
||||
"title": "WRNexusJS",
|
||||
"section": "portal",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/access",
|
||||
"title": "access",
|
||||
"section": "portal",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/getting-started",
|
||||
"title": "getting started",
|
||||
"section": "portal",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/tutorial",
|
||||
"title": "tutorial",
|
||||
"section": "portal",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/architecture",
|
||||
"title": "architecture",
|
||||
"section": "portal",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/language",
|
||||
"title": "language",
|
||||
"section": "portal",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/packages",
|
||||
"title": "packages",
|
||||
"section": "package",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/guides/project-structure",
|
||||
"title": "project structure",
|
||||
"section": "guide",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/guides/routing",
|
||||
"title": "routing",
|
||||
"section": "guide",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/guides/pages-and-components",
|
||||
"title": "pages and components",
|
||||
"section": "guide",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/guides/server-data",
|
||||
"title": "server data",
|
||||
"section": "guide",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/guides/api-routes",
|
||||
"title": "api routes",
|
||||
"section": "guide",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/guides/middleware",
|
||||
"title": "middleware",
|
||||
"section": "guide",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/guides/forms-and-validation",
|
||||
"title": "forms and validation",
|
||||
"section": "guide",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/guides/authentication",
|
||||
"title": "authentication",
|
||||
"section": "guide",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/guides/authorization",
|
||||
"title": "authorization",
|
||||
"section": "guide",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/guides/security",
|
||||
"title": "security",
|
||||
"section": "guide",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/guides/database",
|
||||
"title": "database",
|
||||
"section": "guide",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/guides/uploads",
|
||||
"title": "uploads",
|
||||
"section": "guide",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/guides/realtime",
|
||||
"title": "realtime",
|
||||
"section": "guide",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/guides/pubsub",
|
||||
"title": "pubsub",
|
||||
"section": "guide",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/guides/queues",
|
||||
"title": "queues",
|
||||
"section": "guide",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "experimental"
|
||||
},
|
||||
{
|
||||
"url": "/guides/testing",
|
||||
"title": "testing",
|
||||
"section": "guide",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/guides/workspaces-and-gateway",
|
||||
"title": "workspaces and gateway",
|
||||
"section": "guide",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/guides/deployment",
|
||||
"title": "deployment",
|
||||
"section": "guide",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/guides/configuration-and-profiles",
|
||||
"title": "configuration and profiles",
|
||||
"section": "guide",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/guides/i18n-and-themes",
|
||||
"title": "i18n and themes",
|
||||
"section": "guide",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/guides/mobile",
|
||||
"title": "mobile",
|
||||
"section": "guide",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "experimental"
|
||||
},
|
||||
{
|
||||
"url": "/guides/observability",
|
||||
"title": "observability",
|
||||
"section": "guide",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/guides/upgrading",
|
||||
"title": "upgrading",
|
||||
"section": "guide",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/guides/troubleshooting",
|
||||
"title": "troubleshooting",
|
||||
"section": "guide",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/examples",
|
||||
"title": "examples",
|
||||
"section": "portal",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/showcase",
|
||||
"title": "showcase",
|
||||
"section": "portal",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/benchmarks",
|
||||
"title": "benchmarks",
|
||||
"section": "portal",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/roadmap",
|
||||
"title": "roadmap",
|
||||
"section": "portal",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/changelog",
|
||||
"title": "changelog",
|
||||
"section": "portal",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/releases/0.2.23",
|
||||
"title": "0.2.23",
|
||||
"url": "/releases/0.2.24",
|
||||
"title": "0.2.24",
|
||||
"section": "portal",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/security",
|
||||
"title": "security",
|
||||
"section": "portal",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/support",
|
||||
"title": "support",
|
||||
"section": "portal",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/license",
|
||||
"title": "license",
|
||||
"section": "portal",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/search",
|
||||
"title": "search",
|
||||
"section": "portal",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/404",
|
||||
"title": "404",
|
||||
"section": "portal",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/packages/ai",
|
||||
"title": "ai",
|
||||
"section": "package",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/packages/authz",
|
||||
"title": "authz",
|
||||
"section": "package",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/packages/cli",
|
||||
"title": "cli",
|
||||
"section": "package",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/packages/compiler",
|
||||
"title": "compiler",
|
||||
"section": "package",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/packages/core",
|
||||
"title": "core",
|
||||
"section": "package",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/packages/csr",
|
||||
"title": "csr",
|
||||
"section": "package",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/packages/db",
|
||||
"title": "db",
|
||||
"section": "package",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/packages/dev-server",
|
||||
"title": "dev server",
|
||||
"section": "package",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/packages/encryption",
|
||||
"title": "encryption",
|
||||
"section": "package",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/packages/helpers",
|
||||
"title": "helpers",
|
||||
"section": "package",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/packages/i18n",
|
||||
"title": "i18n",
|
||||
"section": "package",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/packages/jwt",
|
||||
"title": "jwt",
|
||||
"section": "package",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/packages/mobile",
|
||||
"title": "mobile",
|
||||
"section": "package",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "experimental"
|
||||
},
|
||||
{
|
||||
"url": "/packages/native",
|
||||
"title": "native",
|
||||
"section": "package",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/packages/oauth",
|
||||
"title": "oauth",
|
||||
"section": "package",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/packages/pubsub",
|
||||
"title": "pubsub",
|
||||
"section": "package",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/packages/queue",
|
||||
"title": "queue",
|
||||
"section": "package",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/packages/reactive",
|
||||
"title": "reactive",
|
||||
"section": "package",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/packages/router",
|
||||
"title": "router",
|
||||
"section": "package",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/packages/ssr",
|
||||
"title": "ssr",
|
||||
"section": "package",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/packages/styles",
|
||||
"title": "styles",
|
||||
"section": "package",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/packages/test",
|
||||
"title": "test",
|
||||
"section": "package",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/packages/tracking",
|
||||
"title": "tracking",
|
||||
"section": "package",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/packages/ui",
|
||||
"title": "ui",
|
||||
"section": "package",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/packages/uploader",
|
||||
"title": "uploader",
|
||||
"section": "package",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
},
|
||||
{
|
||||
"url": "/packages/validation",
|
||||
"title": "validation",
|
||||
"section": "package",
|
||||
"version": "0.2.23",
|
||||
"version": "0.2.24",
|
||||
"stability": "preview"
|
||||
}
|
||||
]
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# WRNexusJS 0.2.23 comprehensive documentation index
|
||||
# WRNexusJS 0.2.24 comprehensive documentation index
|
||||
|
||||
Status: Private Developer Preview. Runtime: Bun. UI language: .wrn.
|
||||
This is the documentation application, not the framework monorepo.
|
||||
@@ -39,7 +39,7 @@ This is the documentation application, not the framework monorepo.
|
||||
- https://wrnexusjs.dev/benchmarks
|
||||
- https://wrnexusjs.dev/roadmap
|
||||
- https://wrnexusjs.dev/changelog
|
||||
- https://wrnexusjs.dev/releases/0.2.23
|
||||
- https://wrnexusjs.dev/releases/0.2.24
|
||||
- https://wrnexusjs.dev/security
|
||||
- https://wrnexusjs.dev/support
|
||||
- https://wrnexusjs.dev/license
|
||||
|
||||
+252
-28
@@ -1,4 +1,4 @@
|
||||
# WRNexusJS documentation 0.2.23
|
||||
# WRNexusJS documentation 0.2.24
|
||||
|
||||
Status: Private Developer Preview. This site documents 26 release-aligned packages.
|
||||
|
||||
@@ -281,7 +281,7 @@ wrnexus eject <component> # copy a Wire UI component's .wrn into app/compone
|
||||
|
||||
# Installed package documentation
|
||||
|
||||
The following README files and declarations come from the installed private 0.2.23 release.
|
||||
The following README files and declarations come from the installed private 0.2.24 release.
|
||||
|
||||
## @wrnexus/ai
|
||||
|
||||
@@ -411,6 +411,8 @@ try {
|
||||
|
||||
## Usage
|
||||
|
||||
### Return generated JSON from an API route
|
||||
|
||||
```ts
|
||||
// app/api/summarize.ts — summarize posted text
|
||||
import { createAI } from "@wrnexus/ai";
|
||||
@@ -426,6 +428,23 @@ export const POST = async (ctx) => {
|
||||
};
|
||||
```
|
||||
|
||||
### Stream a chat response to the browser
|
||||
|
||||
```ts
|
||||
// app/api/chat.ts
|
||||
import { createAI } from "@wrnexus/ai";
|
||||
|
||||
const ai = createAI({ model: "claude-sonnet-5" });
|
||||
|
||||
export const POST = async (ctx) => {
|
||||
const { messages } = await ctx.req.json();
|
||||
return ai.streamResponse(messages, {
|
||||
system: "Answer using concise Markdown.",
|
||||
maxTokens: 1_500,
|
||||
});
|
||||
};
|
||||
```
|
||||
|
||||
## Requirements / Notes
|
||||
|
||||
- **Bun-only.** Uses `fetch`, `ReadableStream`, `TextDecoder`/`TextEncoder`, and
|
||||
@@ -911,6 +930,47 @@ Runs the app's tests with `bun test`. Defaults to the `test` profile (config + `
|
||||
wrnexus test . --watch
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Create and run a single application
|
||||
|
||||
```bash
|
||||
bunx @wrnexus/cli create customer-portal
|
||||
cd customer-portal
|
||||
bun install
|
||||
bun run dev
|
||||
```
|
||||
|
||||
### Add routes and shared UI to an existing app
|
||||
|
||||
```bash
|
||||
wrnexus generate page reports/monthly
|
||||
wrnexus generate api reports/export
|
||||
wrnexus generate component report-filter
|
||||
wrnexus generate routes
|
||||
```
|
||||
|
||||
### Create a multi-app workspace and add another app
|
||||
|
||||
```bash
|
||||
wrnexus workspace company-suite
|
||||
cd company-suite
|
||||
wrnexus workspace add reports --domain=reports.localhost
|
||||
bun install
|
||||
wrnexus gateway --port=3000
|
||||
```
|
||||
|
||||
Open `http://reports.localhost:3000`; the gateway selects `apps/reports` from the
|
||||
request host.
|
||||
|
||||
### Upgrade with migrations and verification
|
||||
|
||||
```bash
|
||||
wrnexus update --latest --dry-run
|
||||
wrnexus update --latest
|
||||
wrnexus doctor
|
||||
```
|
||||
|
||||
## 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`.
|
||||
@@ -3991,7 +4051,9 @@ bun add @wrnexus/helpers
|
||||
The package is private, so the machine must be authenticated to the `wrnexus` npm
|
||||
organization.
|
||||
|
||||
## Forward-auth login redirects
|
||||
## Usage
|
||||
|
||||
### Redirect an unauthenticated forward-auth request
|
||||
|
||||
The gateway calls an SSO verifier on a different URL from the original application.
|
||||
These helpers reconstruct the original URL from the gateway headers and safely place it
|
||||
@@ -4020,15 +4082,29 @@ Location: http://sso.localhost:3000/login?returnTo=http%3A%2F%2Fadmin.localhost%
|
||||
|
||||
Always list the application hosts that are valid redirect destinations. Forwarded host
|
||||
headers are rejected when `allowedHosts` is absent or does not match, preventing an open
|
||||
redirect. A callback can support dynamic tenant domains:
|
||||
redirect.
|
||||
|
||||
The SSO hostname is the login destination, not an `allowedHosts` entry. For example,
|
||||
when protecting `admin.localhost:3000`, keep `admin.localhost:3000` in the allowlist even
|
||||
though the verifier runs at `sso.localhost:3000`. WRNexus preserves both hosts across a
|
||||
nested gateway request.
|
||||
|
||||
### Support dynamic tenant domains
|
||||
|
||||
```ts
|
||||
allowedHosts: (host) => host.endsWith(".example.test");
|
||||
import type { Context } from "@wrnexus/core";
|
||||
import { getOriginalRequestOrigin, redirectToLogin } from "@wrnexus/helpers";
|
||||
|
||||
export const GET = async (ctx: Context) => {
|
||||
const allowedHosts = (host: string) => host === "example.test" || host.endsWith(".example.test");
|
||||
|
||||
console.info("Authentication requested by", getOriginalRequestOrigin(ctx, { allowedHosts }));
|
||||
return redirectToLogin(ctx, "https://auth.example.test/login", {
|
||||
allowedHosts,
|
||||
returnToParam: "continue",
|
||||
status: 303,
|
||||
});
|
||||
};
|
||||
```
|
||||
|
||||
## API
|
||||
@@ -4541,28 +4617,87 @@ Documentation URL: https://wrnexusjs.dev/packages/mobile
|
||||
|
||||
# @wrnexus/mobile
|
||||
|
||||
SSR-safe access to Capacitor plugins from WrNexus browser code.
|
||||
> SSR-safe access to Capacitor plugins from WRNexusJS browser code.
|
||||
|
||||
## Overview
|
||||
|
||||
`@wrnexus/mobile` keeps optional native imports out of server rendering while giving
|
||||
browser-owned modules one consistent registry for Capacitor plugins. During SSR,
|
||||
`mobile.isNative()` is `false` and `mobile.platform()` is `"web"`.
|
||||
|
||||
## Installation
|
||||
|
||||
Install a plugin through the WRNexusJS CLI so the web and native projects stay aligned:
|
||||
|
||||
```bash
|
||||
wrnexus mobile add @capacitor/camera
|
||||
wrnexus mobile add @capacitor/camera @capacitor/haptics
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Register and invoke a Capacitor plugin
|
||||
|
||||
Import Capacitor packages only from browser-owned code, never from API routes or SSR
|
||||
helpers.
|
||||
|
||||
```ts
|
||||
import { Camera } from "@capacitor/camera";
|
||||
import { Camera, CameraResultType } from "@capacitor/camera";
|
||||
import { mobile } from "@wrnexus/mobile";
|
||||
|
||||
if (mobile.isNative()) {
|
||||
mobile.registerPlugin("Camera", Camera);
|
||||
const photo = await mobile.invoke("Camera", "getPhoto", { resultType: "uri" });
|
||||
mobile.registerPlugin("Camera", Camera);
|
||||
|
||||
export async function takePhoto() {
|
||||
if (!mobile.isNative()) return null;
|
||||
return mobile.invoke("Camera", "getPhoto", {
|
||||
quality: 85,
|
||||
resultType: CameraResultType.Uri,
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
`isNative()` is false and `platform()` is `web` during SSR. `plugin()` returns
|
||||
`undefined` when unavailable; `requirePlugin()` and `invoke()` throw an
|
||||
actionable `MobileUnavailableError`.
|
||||
### Provide a browser fallback
|
||||
|
||||
Import and register Capacitor packages only from browser-owned code. Do not
|
||||
import them in server routes, SSR helpers, or other Bun-only modules.
|
||||
`whenNative` runs the first callback only in a Capacitor WebView and can return a
|
||||
web/SSR-safe fallback everywhere else.
|
||||
|
||||
```ts
|
||||
import { Haptics, ImpactStyle } from "@capacitor/haptics";
|
||||
import { mobile } from "@wrnexus/mobile";
|
||||
|
||||
mobile.registerPlugin("Haptics", Haptics);
|
||||
|
||||
export const confirmAction = () =>
|
||||
mobile.whenNative(
|
||||
() => mobile.invoke("Haptics", "impact", { style: ImpactStyle.Medium }),
|
||||
() => navigator.vibrate?.(30),
|
||||
);
|
||||
```
|
||||
|
||||
### Read an optional plugin without throwing
|
||||
|
||||
```ts
|
||||
import type { NetworkPlugin } from "@capacitor/network";
|
||||
import { mobile } from "@wrnexus/mobile";
|
||||
|
||||
const network = mobile.plugin<NetworkPlugin>("Network");
|
||||
const status = network ? await network.getStatus() : { connected: true, connectionType: "unknown" };
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
- `registerPlugin(name, instance)` registers a browser-imported plugin.
|
||||
- `plugin(name)` returns a plugin or `undefined`; `requirePlugin(name)` throws when absent.
|
||||
- `invoke(plugin, method, options?)` calls a registered method and returns its result.
|
||||
- `whenNative(native, fallback?)` selects native behavior without breaking SSR.
|
||||
- `isNative()` and `platform()` report the current Capacitor environment.
|
||||
|
||||
Unavailable required plugins throw `MobileUnavailableError` with an actionable message.
|
||||
|
||||
## Requirements / Notes
|
||||
|
||||
- Capacitor plugin imports must remain in browser-owned modules.
|
||||
- `@wrnexus/mobile` re-exports `native` from `@wrnexus/native` for applications that
|
||||
prefer the higher-level cross-platform capability API.
|
||||
|
||||
### Exported TypeScript declarations
|
||||
|
||||
@@ -4615,21 +4750,89 @@ Documentation URL: https://wrnexusjs.dev/packages/native
|
||||
|
||||
# @wrnexus/native
|
||||
|
||||
Cross-platform capabilities for browsers, Capacitor WebViews, and compiled native apps.
|
||||
> Cross-platform capabilities for browsers, Capacitor WebViews, and compiled native apps.
|
||||
|
||||
## Overview
|
||||
|
||||
`@wrnexus/native` exposes capabilities by name so application code can ask what the
|
||||
current platform supports before presenting an action. Browser capabilities use Web
|
||||
APIs; mobile capabilities use installed Capacitor plugins. `platform()` returns
|
||||
`"server"` during SSR, `"browser"` on the web, and the Capacitor platform in a native
|
||||
WebView.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
bun add @wrnexus/native
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Share a page when the platform supports it
|
||||
|
||||
```ts
|
||||
import { native } from "@wrnexus/native";
|
||||
|
||||
if (native.supports("share")) await native.run("share", { title: "WrNexus", url: location.href });
|
||||
export async function shareCurrentPage() {
|
||||
if (!native.supports("share")) return false;
|
||||
await native.run("share", {
|
||||
title: document.title,
|
||||
url: location.href,
|
||||
});
|
||||
return true;
|
||||
}
|
||||
```
|
||||
|
||||
Built-ins include `camera`, `clipboard.write`, `share`, `geolocation`, `network`,
|
||||
`haptics`, storage, filesystem, notifications, and device information. Browser
|
||||
capabilities use Web APIs; mobile capabilities use installed Capacitor plugins.
|
||||
### Register an application-specific capability
|
||||
|
||||
`platform()` returns `server` during SSR, `browser` on the web, and the Capacitor
|
||||
platform in a native WebView. Unsupported operations reject with
|
||||
`NativeUnavailableError`; use `supports()` before presenting optional UI.
|
||||
`register` returns an unregister function, which is useful for tests and temporary
|
||||
feature modules.
|
||||
|
||||
```ts
|
||||
import { native } from "@wrnexus/native";
|
||||
|
||||
const unregister = native.register("orders.scan", {
|
||||
browser: {
|
||||
supported: () => typeof window !== "undefined",
|
||||
run: async ({ orderId }: { orderId: string }) => {
|
||||
const code = window.prompt(`Scan code for order ${orderId}`);
|
||||
return { code };
|
||||
},
|
||||
},
|
||||
});
|
||||
|
||||
const result = await native.run<{ code: string | null }>("orders.scan", { orderId: "ord_42" });
|
||||
unregister();
|
||||
```
|
||||
|
||||
### Target browser or mobile behavior explicitly
|
||||
|
||||
```ts
|
||||
import { native } from "@wrnexus/native";
|
||||
|
||||
const canUseMobileCamera = native.supports("camera", "mobile");
|
||||
const position = await native.run(
|
||||
"geolocation",
|
||||
{ enableHighAccuracy: true },
|
||||
{ target: "browser" },
|
||||
);
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
- `supports(name, target?)` checks availability without running the capability.
|
||||
- `run(name, options?, runOptions?)` executes it or rejects with `NativeUnavailableError`.
|
||||
- `register(name, capability)` adds or overrides a capability and returns cleanup.
|
||||
- `registered()` lists capability names; `clearRegistry()` resets the registry.
|
||||
- `isMobile()` and `platform()` report the current target safely during SSR.
|
||||
|
||||
Built-ins include `camera`, `clipboard.write`, `share`, `geolocation`, `network`,
|
||||
`haptics`, storage, filesystem, notifications, and device information.
|
||||
|
||||
## Requirements / Notes
|
||||
|
||||
Use `supports()` before showing optional controls. Mobile capabilities require their
|
||||
matching Capacitor plugins to be installed and registered by the application.
|
||||
|
||||
### Exported TypeScript declarations
|
||||
|
||||
@@ -5851,6 +6054,8 @@ type SeoConfig = {
|
||||
|
||||
## Usage
|
||||
|
||||
### Render an SEO-ready application page
|
||||
|
||||
```ts
|
||||
import { renderDocument } from "@wrnexus/ssr";
|
||||
|
||||
@@ -5878,6 +6083,23 @@ return new Response(html, {
|
||||
|
||||
The produced document has `<title>About Us — Acme</title>`, the SEO/Open Graph/Twitter tags derived from the merged metadata, a `modulepreload` link and module `<script>` for each entry in `scripts`, and the body wrapped in `<div id="app">`.
|
||||
|
||||
### Add trusted framework assets and boot data
|
||||
|
||||
Use `extraHead` and `extraBody` only for HTML generated by your application or the
|
||||
framework. User-provided values belong in `meta`, where they are escaped.
|
||||
|
||||
```ts
|
||||
const html = renderDocument({
|
||||
meta: { title: "Dashboard", robots: "noindex" },
|
||||
body: dashboardHtml,
|
||||
url: ctx.url,
|
||||
extraHead: '<link rel="stylesheet" href="/_wrnexus/admin.css">',
|
||||
extraBody: `<script type="application/json" id="boot">${JSON.stringify(bootData).replaceAll("<", "\\u003c")}</script>`,
|
||||
});
|
||||
|
||||
return new Response(html, { headers: { "content-type": "text/html; charset=utf-8" } });
|
||||
```
|
||||
|
||||
## Requirements / Notes
|
||||
|
||||
- **Server-only.** This module never imports or touches the DOM and is safe to keep out of client bundles.
|
||||
@@ -7130,7 +7352,9 @@ with one function call, drop a drag-and-drop widget on a page, and serve files b
|
||||
private. Zero external dependencies (S3 is signed with a built-in AWS SigV4 implementation, like the
|
||||
rest of the framework).
|
||||
|
||||
## Configure
|
||||
## Usage
|
||||
|
||||
### Configure local and S3 stores
|
||||
|
||||
```ts
|
||||
// wrnexus.config.ts
|
||||
@@ -7164,7 +7388,7 @@ const config: AppConfig = {
|
||||
export default config;
|
||||
```
|
||||
|
||||
## Upload (server)
|
||||
### Upload from an API route or server function
|
||||
|
||||
```ts
|
||||
// app/api/upload.ts — one-liner
|
||||
@@ -7184,7 +7408,7 @@ Uploads are validated (size + type), stored under a random, collision-proof, pat
|
||||
(the client filename is never used as a path), and — for public stores — returned with a servable
|
||||
`url`.
|
||||
|
||||
## Widget (client)
|
||||
### Add a client upload widget
|
||||
|
||||
Drop the element anywhere; the runtime (drag-and-drop, per-file progress, success/failed states) is
|
||||
auto-injected on pages that contain `data-uploader`:
|
||||
@@ -7216,7 +7440,7 @@ It dispatches bubbling events you can listen for:
|
||||
- `wrnexus:upload` — `detail: { file, result: { key, url, name, size, type } }`
|
||||
- `wrnexus:upload-error` — `detail: { file, error }`
|
||||
|
||||
## Serve files
|
||||
### Serve private files behind application authentication
|
||||
|
||||
- **Public + local** → served automatically at `/__wrnexus/uploads/<store>/<key>` (immutable cache).
|
||||
- **Public + S3** → `url` is the bucket/CDN URL directly.
|
||||
|
||||
+1
-1
@@ -1,2 +1,2 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"><url><loc>https://wrnexusjs.dev/</loc></url><url><loc>https://wrnexusjs.dev/access</loc></url><url><loc>https://wrnexusjs.dev/getting-started</loc></url><url><loc>https://wrnexusjs.dev/tutorial</loc></url><url><loc>https://wrnexusjs.dev/architecture</loc></url><url><loc>https://wrnexusjs.dev/language</loc></url><url><loc>https://wrnexusjs.dev/packages</loc></url><url><loc>https://wrnexusjs.dev/guides/project-structure</loc></url><url><loc>https://wrnexusjs.dev/guides/routing</loc></url><url><loc>https://wrnexusjs.dev/guides/pages-and-components</loc></url><url><loc>https://wrnexusjs.dev/guides/server-data</loc></url><url><loc>https://wrnexusjs.dev/guides/api-routes</loc></url><url><loc>https://wrnexusjs.dev/guides/middleware</loc></url><url><loc>https://wrnexusjs.dev/guides/forms-and-validation</loc></url><url><loc>https://wrnexusjs.dev/guides/authentication</loc></url><url><loc>https://wrnexusjs.dev/guides/authorization</loc></url><url><loc>https://wrnexusjs.dev/guides/security</loc></url><url><loc>https://wrnexusjs.dev/guides/database</loc></url><url><loc>https://wrnexusjs.dev/guides/uploads</loc></url><url><loc>https://wrnexusjs.dev/guides/realtime</loc></url><url><loc>https://wrnexusjs.dev/guides/pubsub</loc></url><url><loc>https://wrnexusjs.dev/guides/queues</loc></url><url><loc>https://wrnexusjs.dev/guides/testing</loc></url><url><loc>https://wrnexusjs.dev/guides/workspaces-and-gateway</loc></url><url><loc>https://wrnexusjs.dev/guides/deployment</loc></url><url><loc>https://wrnexusjs.dev/guides/configuration-and-profiles</loc></url><url><loc>https://wrnexusjs.dev/guides/i18n-and-themes</loc></url><url><loc>https://wrnexusjs.dev/guides/mobile</loc></url><url><loc>https://wrnexusjs.dev/guides/observability</loc></url><url><loc>https://wrnexusjs.dev/guides/upgrading</loc></url><url><loc>https://wrnexusjs.dev/guides/troubleshooting</loc></url><url><loc>https://wrnexusjs.dev/examples</loc></url><url><loc>https://wrnexusjs.dev/showcase</loc></url><url><loc>https://wrnexusjs.dev/benchmarks</loc></url><url><loc>https://wrnexusjs.dev/roadmap</loc></url><url><loc>https://wrnexusjs.dev/changelog</loc></url><url><loc>https://wrnexusjs.dev/releases/0.2.23</loc></url><url><loc>https://wrnexusjs.dev/security</loc></url><url><loc>https://wrnexusjs.dev/support</loc></url><url><loc>https://wrnexusjs.dev/license</loc></url><url><loc>https://wrnexusjs.dev/search</loc></url><url><loc>https://wrnexusjs.dev/404</loc></url><url><loc>https://wrnexusjs.dev/packages/ai</loc></url><url><loc>https://wrnexusjs.dev/packages/authz</loc></url><url><loc>https://wrnexusjs.dev/packages/cli</loc></url><url><loc>https://wrnexusjs.dev/packages/compiler</loc></url><url><loc>https://wrnexusjs.dev/packages/core</loc></url><url><loc>https://wrnexusjs.dev/packages/csr</loc></url><url><loc>https://wrnexusjs.dev/packages/db</loc></url><url><loc>https://wrnexusjs.dev/packages/dev-server</loc></url><url><loc>https://wrnexusjs.dev/packages/encryption</loc></url><url><loc>https://wrnexusjs.dev/packages/helpers</loc></url><url><loc>https://wrnexusjs.dev/packages/i18n</loc></url><url><loc>https://wrnexusjs.dev/packages/jwt</loc></url><url><loc>https://wrnexusjs.dev/packages/mobile</loc></url><url><loc>https://wrnexusjs.dev/packages/native</loc></url><url><loc>https://wrnexusjs.dev/packages/oauth</loc></url><url><loc>https://wrnexusjs.dev/packages/pubsub</loc></url><url><loc>https://wrnexusjs.dev/packages/queue</loc></url><url><loc>https://wrnexusjs.dev/packages/reactive</loc></url><url><loc>https://wrnexusjs.dev/packages/router</loc></url><url><loc>https://wrnexusjs.dev/packages/ssr</loc></url><url><loc>https://wrnexusjs.dev/packages/styles</loc></url><url><loc>https://wrnexusjs.dev/packages/test</loc></url><url><loc>https://wrnexusjs.dev/packages/tracking</loc></url><url><loc>https://wrnexusjs.dev/packages/ui</loc></url><url><loc>https://wrnexusjs.dev/packages/uploader</loc></url><url><loc>https://wrnexusjs.dev/packages/validation</loc></url></urlset>
|
||||
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"><url><loc>https://wrnexusjs.dev/</loc></url><url><loc>https://wrnexusjs.dev/access</loc></url><url><loc>https://wrnexusjs.dev/getting-started</loc></url><url><loc>https://wrnexusjs.dev/tutorial</loc></url><url><loc>https://wrnexusjs.dev/architecture</loc></url><url><loc>https://wrnexusjs.dev/language</loc></url><url><loc>https://wrnexusjs.dev/packages</loc></url><url><loc>https://wrnexusjs.dev/guides/project-structure</loc></url><url><loc>https://wrnexusjs.dev/guides/routing</loc></url><url><loc>https://wrnexusjs.dev/guides/pages-and-components</loc></url><url><loc>https://wrnexusjs.dev/guides/server-data</loc></url><url><loc>https://wrnexusjs.dev/guides/api-routes</loc></url><url><loc>https://wrnexusjs.dev/guides/middleware</loc></url><url><loc>https://wrnexusjs.dev/guides/forms-and-validation</loc></url><url><loc>https://wrnexusjs.dev/guides/authentication</loc></url><url><loc>https://wrnexusjs.dev/guides/authorization</loc></url><url><loc>https://wrnexusjs.dev/guides/security</loc></url><url><loc>https://wrnexusjs.dev/guides/database</loc></url><url><loc>https://wrnexusjs.dev/guides/uploads</loc></url><url><loc>https://wrnexusjs.dev/guides/realtime</loc></url><url><loc>https://wrnexusjs.dev/guides/pubsub</loc></url><url><loc>https://wrnexusjs.dev/guides/queues</loc></url><url><loc>https://wrnexusjs.dev/guides/testing</loc></url><url><loc>https://wrnexusjs.dev/guides/workspaces-and-gateway</loc></url><url><loc>https://wrnexusjs.dev/guides/deployment</loc></url><url><loc>https://wrnexusjs.dev/guides/configuration-and-profiles</loc></url><url><loc>https://wrnexusjs.dev/guides/i18n-and-themes</loc></url><url><loc>https://wrnexusjs.dev/guides/mobile</loc></url><url><loc>https://wrnexusjs.dev/guides/observability</loc></url><url><loc>https://wrnexusjs.dev/guides/upgrading</loc></url><url><loc>https://wrnexusjs.dev/guides/troubleshooting</loc></url><url><loc>https://wrnexusjs.dev/examples</loc></url><url><loc>https://wrnexusjs.dev/showcase</loc></url><url><loc>https://wrnexusjs.dev/benchmarks</loc></url><url><loc>https://wrnexusjs.dev/roadmap</loc></url><url><loc>https://wrnexusjs.dev/changelog</loc></url><url><loc>https://wrnexusjs.dev/releases/0.2.24</loc></url><url><loc>https://wrnexusjs.dev/security</loc></url><url><loc>https://wrnexusjs.dev/support</loc></url><url><loc>https://wrnexusjs.dev/license</loc></url><url><loc>https://wrnexusjs.dev/search</loc></url><url><loc>https://wrnexusjs.dev/404</loc></url><url><loc>https://wrnexusjs.dev/packages/ai</loc></url><url><loc>https://wrnexusjs.dev/packages/authz</loc></url><url><loc>https://wrnexusjs.dev/packages/cli</loc></url><url><loc>https://wrnexusjs.dev/packages/compiler</loc></url><url><loc>https://wrnexusjs.dev/packages/core</loc></url><url><loc>https://wrnexusjs.dev/packages/csr</loc></url><url><loc>https://wrnexusjs.dev/packages/db</loc></url><url><loc>https://wrnexusjs.dev/packages/dev-server</loc></url><url><loc>https://wrnexusjs.dev/packages/encryption</loc></url><url><loc>https://wrnexusjs.dev/packages/helpers</loc></url><url><loc>https://wrnexusjs.dev/packages/i18n</loc></url><url><loc>https://wrnexusjs.dev/packages/jwt</loc></url><url><loc>https://wrnexusjs.dev/packages/mobile</loc></url><url><loc>https://wrnexusjs.dev/packages/native</loc></url><url><loc>https://wrnexusjs.dev/packages/oauth</loc></url><url><loc>https://wrnexusjs.dev/packages/pubsub</loc></url><url><loc>https://wrnexusjs.dev/packages/queue</loc></url><url><loc>https://wrnexusjs.dev/packages/reactive</loc></url><url><loc>https://wrnexusjs.dev/packages/router</loc></url><url><loc>https://wrnexusjs.dev/packages/ssr</loc></url><url><loc>https://wrnexusjs.dev/packages/styles</loc></url><url><loc>https://wrnexusjs.dev/packages/test</loc></url><url><loc>https://wrnexusjs.dev/packages/tracking</loc></url><url><loc>https://wrnexusjs.dev/packages/ui</loc></url><url><loc>https://wrnexusjs.dev/packages/uploader</loc></url><url><loc>https://wrnexusjs.dev/packages/validation</loc></url></urlset>
|
||||
|
||||
Reference in New Issue
Block a user