zephyr-rspress-plugin/README.md

Rspress plugin for Zephyr

# Zephyr Rspress Plugin

<div align="center">

[Zephyr Cloud](https://zephyr-cloud.io) | [Zephyr Docs](https://docs.zephyr-cloud.io/meta-frameworks/rspress) | [Rspress Docs](https://rspress.dev/) | [Discord](https://zephyr-cloud.io/discord) | [Twitter](https://x.com/ZephyrCloudIO) | [LinkedIn](https://www.linkedin.com/company/zephyr-cloud/)

<hr/>
<img src="https://cdn.prod.website-files.com/669061ee3adb95b628c3acda/66981c766e352fe1f57191e2_Opengraph-zephyr.png" alt="Zephyr Logo" />
</div>

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](https://docs.zephyr-cloud.io/meta-frameworks/rspress).

---

## Get Started

You can quickly get started using the official Rspress template:

```bash
npx create-zephyr-apps@latest
```

Select the Rspress example when prompted.

For advanced usage and more recipes, visit our [documentation](https://docs.zephyr-cloud.io/meta-frameworks/rspress).

---

## Installation

```bash
# 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
```

---

## Usage

### With Rspress

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

```ts
// 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\`:

```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:

```ts
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](https://zephyr-cloud.io))

---

## Examples

Explore our [examples directory](../../examples/) to see the plugin in action:

- [rspress-site](../../examples/rspress-site/) – A simple Rspress documentation site deployed via Zephyr

---

## Contributing

We welcome contributions! Please see our [contributing guidelines](../../CONTRIBUTING.md) before submitting pull requests.

---

## License

Licensed under the Apache-2.0 License. See [LICENSE](LICENSE) for more information.