vite-plugin-vinext-zephyr

Zephyr Cloud | Zephyr Docs | Discord | Twitter | LinkedIn

A Vite plugin for deploying Vinext applications with Zephyr Cloud.

Installation

pnpm add --save-dev vite-plugin-vinext-zephyr

AI Agent Skills (Optional)

This package ships the zephyr-vinext Agent Skill for AI coding agents, together with the shared zephyr-core and zephyr-module-federation guides. The skills are versioned with the package, so your agent reads guidance that matches the release you installed.

Zephyr does not need Intent at runtime. Coding agents only find these skills after you opt in with TanStack Intent:

pnpm add -D @tanstack/intent
pnpm dlx @tanstack/intent@latest install

Allow vite-plugin-vinext-zephyr when install asks. Intent saves that choice in the intent.skills allowlist in your package.json. To check or load the skill yourself:

pnpm exec intent list
pnpm exec intent load 'vite-plugin-vinext-zephyr#zephyr-vinext'

Usage

Add the plugin after vinext() in your vite.config.ts:

import { defineConfig } from 'vite';
import vinext from 'vinext';
import { cloudflare } from '@cloudflare/vite-plugin';
import { withZephyr } from 'vite-plugin-vinext-zephyr';

export default defineConfig({
  plugins: [
    vinext(),
    cloudflare({
      viteEnvironment: {
        name: 'rsc',
        childEnvironments: ['ssr'],
      },
    }),
    withZephyr(),
  ],
});

Options

const tapFederationMetadata = {
  mfConfigs: [
    { name: 'desktop', filename: 'targets/desktop/remoteEntry.mjs', library: { type: 'module' } },
    { name: 'mobile', filename: 'targets/mobile/remoteEntry.mjs', library: { type: 'module' } },
    { name: 'quickjs', filename: 'targets/quickjs/remoteEntry.mjs', library: { type: 'module' } },
  ],
  federation: [
    { name: 'desktop', remote: 'targets/desktop/remoteEntry.mjs', library_type: 'module' },
    { name: 'mobile', remote: 'targets/mobile/remoteEntry.mjs', library_type: 'module' },
    { name: 'quickjs', remote: 'targets/quickjs/remoteEntry.mjs', library_type: 'module' },
  ],
};

withZephyr({
  target: 'tap-app',
  outputDir: 'dist',
  ...tapFederationMetadata,
  hooks: {},
});

• outputDir - Build output directory. Defaults to dist.
• target - Zephyr artifact family. Use tap-app for TAP packages.
• mfConfigs - Every Module Federation container included in the snapshot.
• federation - Matching build-stat metadata for each mfConfigs entry.
• snapshotType - 'csr' or 'ssr'. TAP packages default to CSR; ordinary Vinext deployments default to SSR.
• entrypoint - Optional server entrypoint relative to output directory for an SSR snapshot. Auto-detected when SSR is selected.
• hooks - Optional Zephyr deployment lifecycle hooks.

target: 'tap-app' publishes a desktop/mobile/QuickJS ESM package as CSR by default, without requiring a server entrypoint. To publish a TAP SSR package instead, opt in explicitly:

withZephyr({
  target: 'tap-app',
  snapshotType: 'ssr',
  entrypoint: 'server/index.js',
  ...tapFederationMetadata,
});

TAP publication requires both non-empty metadata arrays. Every mfConfigs item must have exactly one federation item with the same name and with filename === remote; mismatched metadata fails before the build starts. Vinext does not infer this information from framework plugins. A valid singleton is also exposed through the legacy mfConfig field for older consumers; multi-container packages use only the complete mfConfigs array.

Entrypoint Auto-Detection

The plugin waits for Vinext's post-ordered buildApp phase, verifies every Vite child environment completed, then scans the finalized output tree. Ordinary Vinext deployments include the generated RSC manifest and Worker-compatible import cleanup. With target: 'tap-app', the finalized tree is transported verbatim instead: no Node-import rewriting and no synthesized RSC manifest. CSR transport does not inspect a server entry. When snapshotType: 'ssr' is selected and entrypoint is not provided, it resolves JavaScript, ESM, and CommonJS entries from:

1. dist/server/index.js for App Router builds.
2. dist/<worker-dir>/index.* when <worker-dir> contains wrangler.json or wrangler.jsonc (Pages Router builds).

License

Apache-2.0