Nuxt 4.5+ Native Wire

More

@kelphect/nuxt-lockwell is the server-only Nuxt adapter for the shared @kelphect/sdk-native LNW/1 client. It owns Nuxt configuration, Nitro lifecycle, request cancellation, HTTP streaming helpers, health diagnostics, and optional OpenTelemetry bridging. It does not copy the wire codec and never falls back to JSON, XML, or S3.

Release boundary

LNW/1 remains opt-in. Use the source-shipped package only with the matching Lockwell server revision until the release gate and package-publication policy explicitly approve a public version.

Install

npm install @kelphect/nuxt-lockwell @kelphect/sdk-native

Use Nuxt 4.5 or newer with Node 22+ or Bun 1.4+. Configure public connection settings in nuxt.config.ts, but keep credentials and TLS private keys in server runtime configuration:

export default defineNuxtConfig({
  modules: ["@kelphect/nuxt-lockwell"],
  lockwellNative: {
    host: "lockwell.internal",
    port: 9444,
    requestTimeoutMs: 30_000,
    tls: {
      serverName: "lockwell.internal",
      caFile: "/run/secrets/lockwell-ca.pem",
    },
    pool: {
      maxConnections: 8,
      idleTimeoutMs: 30_000,
      acquireTimeoutMs: 10_000,
    },
  },
})

Supply credentials only through private runtime environment variables:

NUXT_LOCKWELL_NATIVE_ACCESS_KEY_ID=...
NUXT_LOCKWELL_NATIVE_SECRET_ACCESS_KEY=...

Putting lockwellNative under runtimeConfig.public fails the build. TLS certificate verification remains enabled, and file-backed CA, client-certificate, and private-key material is loaded only by the server process.

Supported Nitro presets

Preset	Runtime	Status
nitro-dev	Node	Supported for development; HMR retires the old pool
node-server	Node 22+	Supported
node-cluster	Node 22+	Supported; one bounded pool per worker
bun	Bun 1.4+	Supported
aws-lambda, netlify, vercel	Serverless	Rejected until raw-TLS lifecycle is qualified
Cloudflare, edge, Deno, service worker	Edge	Rejected; no raw socket transport
static, github-pages, unknown	No supported server	Rejected

Unsupported presets fail during nitro:config. There is no hidden JSON or S3 fallback. Selective prerendering inside a supported server build is an application decision; static-only generation is not supported.

Server helpers

Nitro auto-imports server-only helpers:

• useLockwellNative() returns the shared typed client.
• useLockwellStorage(event) adds request cancellation, deadlines, and valid inbound trace context.
• defineLockwellEventHandler(handler) supplies the event-scoped client, service, and cancellation signal.
• uploadLockwellObjectFromEvent streams a known-length body.
• uploadLockwellMultipartFromEvent handles bounded unknown-length or resumable uploads with abort cleanup.
• downloadLockwellObjectToEvent streams full, closed, open, and suffix ranges.

export default defineLockwellEventHandler(async ({ event }) => {
  return uploadLockwellObjectFromEvent(event, {
    bucket: "documents",
    key: getRouterParam(event, "key")!,
    checksum: {
      algorithm: "SHA256",
      value: getHeader(event, "x-lockwell-checksum-sha256")!,
    },
    request: { idempotencyKey: getHeader(event, "idempotency-key") },
  })
})

Known-length uploads stream directly. Unknown-length requests must use the multipart helper, which processes sequential 5–512 MiB parts, retains at most one part plus an inbound chunk, and performs best-effort abort cleanup. Direct idempotent streams require a caller-supplied checksum; the adapter never buffers a stream merely to manufacture one.

The service exposes the shared core's bucket, object, pagination, multipart, batch-delete, copy, version, tag, retention, legal-hold, CORS, notification, readiness, and signed-capability operations. SSE-C and Admin operations are not LNW/1 data-plane capabilities.

Lifecycle and diagnostics

The native client is lazy and shared per Nitro application. Nitro's close hook drains it, and development HMR retires the previous instance before replacement. H3 request cancellation propagates to LNW/1 CANCEL; operation deadlines use the smaller caller or configured bound.

GET /api/_lockwell/health performs native readiness and returns 503 when unavailable. Its fixed response contains only aggregate state, bounded connection counts, negotiated capabilities, and metrics—never credentials, TLS material, peer certificates, object keys, tenant IDs, or payloads. When @opentelemetry/api is installed and telemetry is enabled, the adapter uses the application's providers and installs no exporter.

Migration and rollback

Keep S3 and LNW/1 clients explicit while migrating. Compare reads and metadata first, then move idempotent writes, multipart recovery, versions, Object Lock denials, cancellation, and bounded-concurrency workloads. Rollback drains the native pool and routes the application back to its separately configured S3 client; object bytes and metadata require no migration because both transports use the same server-side storage authority.

See the Native Wire guide, capability index, and the source contract.