@unieojs/unio-evjs-adapter

EVJS adapter for emitting Unio Build Output API (uboa) manifests.

Usage

Preferred integration is the EVJS plugin hook:

import { defineConfig } from "@evjs/ev";
import { unio } from "@unieojs/unio-evjs-adapter";

export default defineConfig({
  plugins: [unio()],
});

After a production ev build, the plugin writes .unio/output with unio.json, routes.json, middleware.json, artifacts.json, static assets, and an evjs serverFunction when the EVJS buildEnd server manifest has an entry.

build() and emitUboa() are lower-level APIs used by the plugin and expect manifest objects supplied by @evjs/ev build hooks. They do not invoke ev build, modify user config, or parse EVJS manifest files from dist.

Extension Hooks

The emitter stays platform-neutral. Deployment integrations that need platform-specific metadata or sidecar files can extend the generic uboa output through unio() or emitUboa() options instead of forking the EVJS adapter.

The available hooks are:

• extendServerFunctionDescriptor: called when a server function is emitted. It receives the generated serverFunction.json descriptor and must return an object. Use this to add generic deployment metadata, x-* extension records, environment variables, or runtime bindings.
• extendArtifacts: called after built-in artifacts are collected and before artifacts.json is written. It receives the current artifact list and must return the final artifact list. Use this to register sidecars such as apiSchema artifacts.
• afterEmit: called after the adapter writes the uboa manifests. Use this to write files referenced by extra artifacts or descriptor metadata.

Example:

import fs from "node:fs/promises";
import path from "node:path";
import { defineConfig } from "@evjs/ev";
import { unio } from "@unieojs/unio-evjs-adapter";

export default defineConfig({
  plugins: [
    unio({
      extendServerFunctionDescriptor({ descriptor, serverFunctionName }) {
        return {
          ...descriptor,
          deployment: { mode: "dedicated" },
          "x-example-platform": {
            resourceName: serverFunctionName,
            manifest: `api-schemas/${serverFunctionName}/metadata.json`,
          },
        };
      },
      extendArtifacts({ artifacts, serverFunctionName }) {
        return [
          ...artifacts,
          {
            id: `${serverFunctionName}-api-schema`,
            resourceKind: "apiSchema",
            schemaFormat: "oneapi",
            path: `api-schemas/${serverFunctionName}/metadata.json`,
            describes: {
              resourceKind: "serverFunction",
              id: serverFunctionName,
            },
          },
        ];
      },
      async afterEmit({ outputDir, serverFunctionName }) {
        await fs.mkdir(
          path.join(outputDir, "api-schemas", serverFunctionName),
          { recursive: true },
        );
        await fs.writeFile(
          path.join(outputDir, "api-schemas", serverFunctionName, "metadata.json"),
          `${JSON.stringify({ oneapi: "1.0.0" }, null, 2)}\n`,
          "utf8",
        );
      },
    }),
  ],
});

Hooks should keep platform-specific fields namespaced, for example under an x-* key, so the base adapter contract remains framework-neutral.

The generated output is:

.unio/output/
  unio.json
  routes.json
  middleware.json
  artifacts.json
  features.json
  observability.json
  static/
    index.html
    assets/
      app.js
      app.css
  server-functions/
    evjs/
      serverFunction.json
      main.js
      chunks/
        dep.js
  api-schemas/
    evjs/
      metadata.json

apiSchema entries in artifacts.json describe schema sidecars:

{
  "id": "evjs-api-schema",
  "resourceKind": "apiSchema",
  "schemaFormat": "oneapi",
  "path": "api-schemas/evjs/metadata.json",
  "describes": {
    "resourceKind": "serverFunction",
    "id": "evjs"
  }
}

describes is optional. When present, validation checks that the referenced artifact exists in the same artifacts.json.

P0 Behavior

• CSR-only EVJS builds emit static-only uboa output.
• Fullstack EVJS builds map the whole server bundle to one Fetch-style serverFunction named evjs.
• POST /api/fn is the default EVJS server function route.
• REST route handlers are bound through /api/:path* and marked degraded until EVJS exposes stable server route metadata.