Zephyr Rspress Plugin

Zephyr Cloud | Zephyr Docs | Rspress Docs | Discord | Twitter | LinkedIn

An Rspress plugin for deploying documentation and static apps with Zephyr Cloud. This plugin enables seamless integration with Rspress to optimize, build, and deploy your site globally with CDN-backed delivery and analytics.

Learn more in our documentation.

Get Started

You can quickly get started using the official Rspress template:

npx create-zephyr-apps@latest

Select the Rspress example when prompted.

For advanced usage and more recipes, visit our documentation.

Installation

# npm
npm install --save-dev zephyr-rspress-plugin

# yarn
yarn add --dev zephyr-rspress-plugin

# pnpm
pnpm add --dev zephyr-rspress-plugin

# bun
bun add --dev zephyr-rspress-plugin

AI Agent Skills (Optional)

This package ships the zephyr-rspress 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 zephyr-rspress-plugin 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 'zephyr-rspress-plugin#zephyr-rspress'

Usage

With Rspress

Add the plugin to your `rspress.config.ts` or `rspress.config.js` file:

// rspress.config.ts
import { defineConfig } from 'rspress/config';
import { withZephyr } from 'zephyr-rspress-plugin';

export default defineConfig({
  ssg: true,
  plugins: [withZephyr({ target: 'tap-app' })],
});

The optional target accepts web, ios, android, or tap-app. It is forwarded through both the normal Rsbuild and SSG publication paths.

Features

• 📘 Seamless Rspress integration
• 📦 Automatic static asset upload
• 🌍 Global CDN distribution
• 🔍 Optional search index support
• 🧠 Smart caching and invalidation
• 📊 Build analytics and logs via Zephyr Cloud
• 🛠️ Minimal config, works with `rspress build`

Build Scripts

Add these scripts to your `package.json`:

{
  "scripts": {
    "dev": "rspress dev",
    "build": "rspress build",
    "build:prod": "NODE_ENV=production rspress build"
  }
}

After running `build`, your site will automatically be uploaded to Zephyr Cloud if the plugin is enabled and configured.

SSG with Module Federation

No target-specific Zephyr configuration is required. Rspress builds browser and Node compilers during SSG; Zephyr publishes Module Federation metadata from the deployable browser compiler only, while uploading every emitted file from the shared output directory, including Node/SSG artifacts.

Generate files before SSG upload

Rspress runs plugins' afterBuild hooks in parallel. Putting Zephyr last in the plugin list does not guarantee that files generated by another hook are ready for upload.

For SSG builds, Zephyr observes the afterBuild hooks of plugins in the resolved config.plugins list and waits for their promises before collecting output files. Rspress still invokes each hook once and runs them in parallel. No dependency callback or plugin reordering is required:

import { defineConfig } from '@rspress/core';
import { pluginSitemap } from '@rspress/plugin-sitemap';
import { withZephyr } from 'zephyr-rspress-plugin';

export default defineConfig({
  ssg: true,
  plugins: [withZephyr(), pluginSitemap({ siteUrl: 'https://example.com' })],
});

If a configured hook fails, publication stops through the existing Zephyr error policy. Plugins registered only through Rspress's addPlugin utility are stored in a separate internal list and are not included in this coordination.

Requirements

• Rspress 0.7 or higher
• Node.js 18 or higher
• Zephyr Cloud account (sign up at zephyr-cloud.io)

Examples

Explore our examples directory to see the plugin in action:

• rspress-site – A simple Rspress documentation site deployed via Zephyr

Contributing

We welcome contributions! Please see our contributing guidelines before submitting pull requests.

License

Licensed under the Apache-2.0 License. See LICENSE for more information.