vite-plugin-zephyr 1.4.2 → 1.5.0

package/skills/zephyr-module-federation/references/remote-resolution.md

@@ -0,0 +1,98 @@
+# Remote Resolution
+
+Use this file when the user asks how Zephyr resolves remotes, how `workspace:*` works, or which selector format to use.
+
+## `zephyr:dependencies`
+
+Zephyr uses the `zephyr:dependencies` field in `package.json` to map local remote names to application identifiers and resolution selectors.
+
+Valid shapes:
+
+```json
+{
+  "zephyr:dependencies": {
+    "local-name": "workspace:*"
+  }
+}
+```
+
+```json
+{
+  "zephyr:dependencies": {
+    "local-name": "application-uid-or-name@selector"
+  }
+}
+```
+
+```json
+{
+  "zephyr:dependencies": {
+    "local-name": "zephyr:application-uid-or-name@selector"
+  }
+}
+```
+
+The `zephyr:` registry prefix is optional in current docs.
+
+## Selectors to explain
+
+- Label/tag/environment style: `@latest`, `@stable`, `@production`, `@staging`
+- Semver: `@^1.2.3`, `@~2.0.0`, `@1.5.0`
+- Wildcard latest: `*`
+- Workspace matching: `workspace:*`
+
+## `workspace:*`
+
+This is the most important Zephyr-specific selector for local dev and coordinated CI.
+
+It resolves the most recent version matching build context, including:
+
+- git branch
+- target platform
+- CI vs local
+- username / build identity
+
+Why it matters:
+
+- feature branches consume matching remotes automatically
+- local dev stays isolated from CI builds
+- teams do not need to hand-edit remote URLs for normal branch work
+
+Concrete example:
+
+- Host on branch `feature/cart`, user `alice`, local build, platform `web`
+- Remote selector is `workspace:*`
+- Zephyr prefers the most recent remote build that also matches `feature/cart`, `alice`, local context, and `web`
+- If none exists, the SDK retries the same remote with version `*` and uses the latest published version
+
+What to expect if no exact match exists:
+
+- The SDK resolves version `*` silently; with `DEBUG=zephyr:remotes` it logs `No workspace build found for <remote>@workspace:*; falling back to the latest published version`.
+- Some public docs describe this as a default-environment fallback; the current SDK uses the latest published version instead.
+- That means the remote needs at least one published build to resolve cleanly; an exact workspace match always wins when it exists.
+- If the user sees unresolved remotes, check whether the remote app has actually been built and exposed through an environment.
+
+## Selector guidance by scenario
+
+| Scenario                       | Good default                                              |
+| ------------------------------ | --------------------------------------------------------- |
+| Branch-based local dev         | `workspace:*`                                             |
+| Moving preview/staging channel | environment/tag-style selector like `@staging` or `@beta` |
+| Stable production pin          | exact version like `@1.2.3`                               |
+| Latest acceptable version      | `*` or an explicit moving selector, depending on policy   |
+
+## Resolution priority note
+
+For label-like selectors, the public docs say Zephyr resolves by looking for:
+
+1. environment name
+2. tag name
+3. version name
+
+If a user is confused by `production` or `staging`, explain that those names may resolve to an environment before they resolve to a tag.
+
+## Best docs to link
+
+- Remote dependencies: `https://docs.zephyr-cloud.io/features/remote-dependencies.md`
+- Environment overrides: `https://docs.zephyr-cloud.io/features/environment-overrides.md`
+- MF guide: `https://docs.zephyr-cloud.io/tutorials/mf-guide.md`

package/skills/zephyr-module-federation/references/setup-patterns.md

@@ -0,0 +1,128 @@
+# Setup Patterns
+
+Use this file when the user asks how to configure a host or remote with Zephyr and Module Federation.
+
+## Two layers to explain
+
+1. Bundler/module federation config
+2. `zephyr:dependencies` mapping in `package.json`
+
+Both are needed for a smooth Zephyr MF workflow.
+
+## Smallest end-to-end path
+
+1. Configure the remote with valid MF `name`, `filename`, and `exposes`.
+2. Configure the host with matching remote keys/names.
+3. Add `zephyr:dependencies` in the host `package.json`.
+4. Build the remote first so Zephyr can resolve it.
+5. Build the host and verify the host can load/import the remote.
+
+## Lifecycle map
+
+- Build time: bundler MF config is compiled and Zephyr captures dependency declarations.
+- Deploy time: Zephyr resolves remote selectors to concrete deploy targets.
+- Runtime: the host loads the resolved remote entry and executes the remote code.
+
+## Naming map
+
+Keep these aligned:
+
+- remote package `name`
+- remote MF config `name`
+- host remote key / import name
+- `zephyr:dependencies` local key
+- `zephyr:dependencies` target app identifier when not using `workspace:*`
+
+If names drift, users often get confusing resolution or runtime-load failures.
+
+## Vite host example
+
+File: `https://github.com/ZephyrCloudIO/zephyr-examples/blob/main/module-federation/react-vite-rspack-webpack/host/vite.config.ts`
+
+```ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { withZephyr, type ModuleFederationOptions } from 'vite-plugin-zephyr';
+
+const mfConfig: ModuleFederationOptions = {
+  name: 'vite-host',
+  filename: 'remoteEntry.js',
+  remotes: {
+    vite_remote: {
+      name: 'vite_remote',
+      entry: 'http://localhost:5174/remoteEntry.js',
+      type: 'module',
+    },
+    vite_webpack: {
+      name: 'vite_webpack',
+      entry: 'http://localhost:8080/remoteEntry.js',
+      type: 'var',
+    },
+    vite_rspack: {
+      name: 'vite_rspack',
+      entry: 'http://localhost:8081/remoteEntry.js',
+      type: 'var',
+    },
+  },
+  shared: {
+    react: { singleton: true },
+    'react-dom': { singleton: true },
+  },
+};
+
+export default defineConfig({
+  plugins: [react(), withZephyr({ mfConfig })],
+});
+```
+
+## Minimal remote example
+
+File: `https://docs.zephyr-cloud.io/bundlers/vite.md`
+
+```ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { withZephyr, type ModuleFederationOptions } from 'vite-plugin-zephyr';
+
+const mfConfig: ModuleFederationOptions = {
+  name: 'remote-app',
+  filename: 'remoteEntry.js',
+  exposes: {
+    './Button': './src/components/Button',
+  },
+  shared: {
+    react: { singleton: true },
+    'react-dom': { singleton: true },
+  },
+};
+
+export default defineConfig({
+  plugins: [react(), withZephyr({ mfConfig })],
+});
+```
+
+## Host dependency mapping
+
+File: `https://github.com/ZephyrCloudIO/zephyr-examples/blob/main/module-federation/react-vite-rspack-webpack/host/package.json`
+
+```json
+"zephyr:dependencies": {
+  "vite_remote": "workspace:*",
+  "vite_rspack": "workspace:*",
+  "vite_webpack": "workspace:*"
+}
+```
+
+## What to explain
+
+- Local import names must line up with the names the host uses.
+- `zephyr:dependencies` tells Zephyr how to resolve those remotes at build/runtime.
+- Shared React deps are usually singleton.
+- In mixed-bundler Vite hosts, remote `type` matters.
+- `type: 'module'` usually matches module-style Vite remotes; `type: 'var'` usually matches Webpack/Rspack-style remotes.
+- Host and remote still need valid MF config even when Zephyr handles deploy-time resolution.
+
+## Minimal code mental model
+
+- Host code imports/loads the remote by the host's configured remote key.
+- Zephyr helps resolve where that remote should come from in deployed environments.

package/skills/zephyr-vite/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: zephyr-vite
+description: Configure and deploy Vite applications with vite-plugin-zephyr; use
+  when adding withZephyr, configuring its Module Federation integration, or
+  diagnosing Vite build publication and plugin ordering. Use the dedicated
+  integrations for TanStack Start and Vinext.
+metadata:
+  library: vite-plugin-zephyr
+  library_version: '1.5.0' # x-release-please-version
+  purpose: Configure an existing Vite application for Zephyr publication while preserving its framework plugins and selecting the correct build lifecycle.
+  domain: vite
+  type: core
+sources:
+  - ZephyrCloudIO/zephyr-packages:**/libs/vite-plugin-zephyr/src/index.ts
+  - ZephyrCloudIO/zephyr-packages:**/libs/vite-plugin-zephyr/src/lib/vite-plugin-zephyr.ts
+  - ZephyrCloudIO/zephyr-packages:**/libs/vite-plugin-zephyr/src/lib/vite-api.integration.spec.ts
+  - ZephyrCloudIO/zephyr-packages:**/libs/vite-plugin-zephyr/src/package-output.spec.ts
+  - ZephyrCloudIO/zephyr-packages:**/libs/vite-plugin-zephyr/src/lib/__fixtures__/vite-api/skill-task.md
+  - ZephyrCloudIO/zephyr-packages:**/libs/vite-plugin-zephyr/README.md
+---
+
+# Configure Vite for Zephyr
+
+## Setup
+
+Read the application's existing Vite config and installed package versions before editing.
+Keep its framework plugins and build options. If `vite-plugin-zephyr` is missing,
+install it as a development dependency only when dependency changes are authorized.
+
+Add `withZephyr()` to the existing plugin list. It returns a plugin array, so both
+spreading it and nesting it in Vite's plugin list work:
+
+```typescript
+import { defineConfig } from 'vite';
+import { withZephyr } from 'vite-plugin-zephyr';
+
+export default defineConfig({
+  plugins: [...withZephyr()],
+});
+```
+
+The installed package supports Vite 5 through 8. Multi-environment application
+publication requires Vite 7 or newer. Use `vite-plugin-tanstack-start-zephyr` or
+`vite-plugin-vinext-zephyr` for those frameworks rather than replacing their
+specialized integration with this generic plugin.
+
+## Configure Module Federation
+
+For a new federation setup, install a compatible `@module-federation/vite` peer
+when authorized and pass the container config through `mfConfig`:
+
+```typescript
+import { defineConfig } from 'vite';
+import { withZephyr } from 'vite-plugin-zephyr';
+
+export default defineConfig({
+  plugins: [
+    ...withZephyr({
+      mfConfig: {
+        name: 'catalog',
+        exposes: { './Product': './src/Product.tsx' },
+      },
+    }),
+  ],
+});
+```
+
+`withZephyr({ mfConfig })` installs the federation plugins itself. Do not also
+add `federation(mfConfig)` for the same container. Existing configs that already
+install `federation(...)` can keep that plugin and add plain `withZephyr()`;
+Zephyr detects the existing federation config. The optional peer is unnecessary
+for an ordinary Vite app and is required when `mfConfig` is supplied.
+
+For hosts, keep normal federation wiring and Zephyr's `zephyr:dependencies`
+mapping distinct. The `zephyr-module-federation` skill shipped in this package
+covers `zephyr:dependencies`, remote resolution, and build order.
+
+## Choose the publication lifecycle
+
+Use the application's existing Vite build command for an ordinary client app.
+When an application uses `createBuilder()` with multiple environments, publish
+through `builder.buildApp()` rather than building each environment separately.
+
+When working on SSR, multi-environment builds, explicit plugin ordering, or
+separate producer builds, read [build lifecycle](references/build-lifecycle.md)
+before choosing options or changing hooks.
+
+## Avoid misleading fixes
+
+- Do not move Zephyr universally to the end of the plugin list. It must precede
+  another `enforce: 'pre'` plugin with a pre-ordered `buildApp` hook. Read the
+  [build lifecycle](references/build-lifecycle.md) when resolving ordering conflicts.
+- Do not use an arbitrary source filename as an SSR `entrypoint`. It must name
+  an emitted server chunk relative to the snapshot root. Read the SSR entrypoint
+  rules in [build lifecycle](references/build-lifecycle.md) when choosing that path.
+- Do not treat a successful local asset build as proof of deployment. Check
+  Zephyr publication separately, especially when errors are configured to log
+  rather than fail the build.
+- Do not put credentials in `ZE_PUBLIC_*`; those values are client-visible.
+
+## Verify completion
+
+Run the authorized build with the application's existing package runner.
+Confirm its expected assets are emitted and Zephyr reports a successful
+publication with a version URL. A build without credentials can establish local
+asset correctness, but not live deployment success. Report that distinction.
+
+On failure, retain the actionable error and fix the matching configuration or
+publication issue. Do not silently change the framework integration, suppress
+errors, or claim that a partial build was deployed.

package/skills/zephyr-vite/references/build-lifecycle.md

@@ -0,0 +1,70 @@
+# Build lifecycle
+
+Use this reference for SSR, multiple Vite environments, ordering conflicts, or
+intentionally separate producer builds. This reference describes publication
+behavior of the installed `vite-plugin-zephyr` release.
+
+## Direct builds and coordinated application builds
+
+Ordinary `vite.build()` calls publish the direct build's output. For a
+multi-environment Vite 7 or 8 builder, use `builder.buildApp()` so all current
+environments contribute to one snapshot. Building the environments separately
+is rejected instead of publishing incomplete snapshots.
+
+Vite 6 does not dispatch plugin `buildApp` hooks. Its non-watch publication
+supports one environment without an explicit builder configuration. Upgrade
+Vite only when authorized; do not work around this limitation by silently
+publishing only the client environment.
+
+Put `withZephyr()` before plugins that combine `enforce: 'pre'` with a
+pre-ordered `buildApp` hook. Direct non-watch builds also require Zephyr to observe
+the final `outputOptions`, `writeBundle`, and `closeBundle` hooks. A later
+post-ordered hook or unresolved asynchronous output plugin is rejected because
+it could change output or fail after publication.
+
+## SSR entrypoints
+
+Direct SSR builds infer their emitted server entry. Set `snapshotType: 'ssr'`
+and `entrypoint` only when the default inference does not express the intended
+snapshot. The entrypoint is an emitted path inside the snapshot, not a source
+path or an absolute filesystem path. Multiple emitted server entries require
+an explicit choice.
+
+With an emitted `server/index.mjs`, the relevant options are:
+
+```typescript
+import { withZephyr } from 'vite-plugin-zephyr';
+
+withZephyr({
+  snapshotType: 'ssr',
+  entrypoint: 'server/index.mjs',
+});
+```
+
+Explicit options take precedence over inference. Framework files created after
+Vite returns are outside this upload lifecycle. If those files must be deployed,
+the framework needs a supported post-build publication step.
+
+## Separate producer builds
+
+Use `withZephyrPartial()` only for intentionally separate producer invocations.
+Give every producer and the finalizer the same nonempty `invocationId`, or use
+the documented `ZE_BUILD_INVOCATION_ID` contract. The finalizer passes that
+identity through `withZephyr({ partialBuild: { invocationId } })`.
+
+Ambient CI metadata alone does not opt an ordinary build into partial output.
+Do not invent a shared identity or reuse one across unrelated builds. A missing
+identity or unavailable producer output is a failure to investigate, not a
+reason to publish a reduced snapshot.
+
+## Base paths and public configuration
+
+Without an explicit base, the plugin defaults build assets to `./`. Existing
+bases are preserved. An origin-absolute base such as `/docs/` cannot be relocated
+under another deployment prefix and can produce a warning for path addressing.
+
+This default does not make SSR HTML generation prefix-aware. Keep the dedicated
+TanStack Start and Vinext integrations for their runtime HTML behavior.
+
+`ZE_PUBLIC_*` rewrites support public runtime configuration. Never use this
+mechanism to carry authentication tokens or other secrets.