vite-ssr-components

0.5.2 verified Mon Apr 27 auth: no javascript

vite-ssr-components (v0.5.2) provides JSX components (Script, Link, ViteClient) and Vite plugins for SSR applications with Vite, particularly targeting Cloudflare deployments. It automates asset path resolution via manifest.json, client script injection, SSR hot reload, and build entry detection. Supports hono/jsx and React. Easy to set up with an SSR plugin that auto-scans Script/Link components for build input. Requires Node >=18.0.0.

Common errors

error Cannot find module 'vite-ssr-components/plugin' ↓

cause Incorrect import path or missing package.

fix

Ensure the package is installed: npm i -D vite-ssr-components, then use import ssrPlugin from 'vite-ssr-components/plugin'.

error Module not found: Error: Can't resolve 'vite-ssr-components/hono' ↓

cause Using wrong framework subpath or forgetting to add the subpath.

fix

Use import { Script } from 'vite-ssr-components/hono' for hono/jsx or 'vite-ssr-components/react' for React.

error Error: Vite manifest not found. Did you build the client? ↓

cause In production mode, the manifest.json file is not found; possibly the client build hasn't run or the path is incorrect.

fix

Run vite build for the client (e.g., vite build --outDir dist/client) before starting the SSR server.

error The plugin 'ssrPlugin' doesn't have a 'name' property. ↓

cause Using ssrPlugin without calling it as a function; the default export is a function that returns a plugin.

fix

Call ssrPlugin() in the plugins array: plugins: [ssrPlugin()].

Warnings

breaking In v0.2.0, option names were changed. Refer to the changelog for migration. ↓

fix Update your ssrPlugin() options to match the new names (see release notes).

breaking In v0.4.0, manifest file auto-detection was introduced; manual manifest options may no longer be required. ↓

fix Remove any custom manifest file configuration if using auto-detect; check that manifest.json exists in build output.

gotcha Custom components with the same names as default 'Link' and 'Script' components can cause unexpected behavior. ↓

fix Use different names for custom components or specify custom component names in the plugin's `components` option.

gotcha The plugin scans source files for Script/Link components at build time; if you import them dynamically, the plugin may not detect them. ↓

fix Ensure Script/Link components are statically importable in scanned files.

deprecated Using `require('vite-ssr-components')` is not supported; named imports from subpaths require ESM. ↓

fix Use ESM imports like `import { Script } from 'vite-ssr-components/hono'`.

Install

npm install vite-ssr-components

yarn add vite-ssr-components

pnpm add vite-ssr-components

Imports

ssrPlugin
wrong
```
import { ssrPlugin } from 'vite-ssr-components'
```
correct
```
import ssrPlugin from 'vite-ssr-components/plugin'
```
The plugin is a default export from 'vite-ssr-components/plugin', not a named export from the main package.
Script, Link, ViteClient
wrong
```
import { Script, Link, ViteClient } from 'vite-ssr-components'
```
correct
```
import { Script, Link, ViteClient } from 'vite-ssr-components/hono'
```
Components are exported from framework-specific subpaths: 'vite-ssr-components/hono' or 'vite-ssr-components/react'.

Script, Link, ViteClient

wrong

import { Script, Link, ViteClient } from 'vite-ssr-components/hono' // if using React

correct

import { Script, Link, ViteClient } from 'vite-ssr-components/react'

Choose the correct subpath based on your JSX framework: hono or react.

Quickstart

Shows how to add the SSR plugin to Vite config and use Script, Link, and ViteClient components in an SSR app.

// vite.config.ts
import { defineConfig } from 'vite'
import { cloudflare } from '@cloudflare/vite-plugin'
import ssrPlugin from 'vite-ssr-components/plugin'

export default defineConfig({
  plugins: [cloudflare(), ssrPlugin()],
})

// App.tsx
import { Script, Link, ViteClient } from 'vite-ssr-components/hono'
// import { Script, Link, ViteClient } from 'vite-ssr-components/react'

function App() {
  return (
    <html>
      <head>
        <ViteClient />
        <Script src='/src/client.tsx' />
        <Link href='/src/style.css' rel='stylesheet' />
      </head>
      <body>
        <div id='root' />
      </body>
    </html>
  )
}