vite-plugin-ssr

🔧 Control

Control how your pages are rendered and use any view framework (React, Vue, Svelte, ...) and any tool you want (Vuex/Redux/PullState, RPC or GraphQL, React/Vue Query, PWA, Service Workers, other Vite plugins, ...).

Integrating tools is simple and natural.

With vite-plugin-ssr you keep control over how your pages are rendered.

// /pages/about.page.js
// Environment: Node.js, Browser

export { Page }

// `Page` can be anything you want such as a React/Vue/Svelte/... component
function Page() {
  return <>
    <h1>About</h1>
    <p>This is our first vite-plugin-ssr app.</p>
  </>
}

// _default.page.server.js
// Environment: Node.js

import { escapeInject, dangerouslySkipEscape } from 'vite-plugin-ssr'

// This can be any view framework (React, Vue, Svelte, ...)
import { renderToHtml } from 'my-favorite-view-framework'

export async function render({ Page }) {
  // You control how you render `Page` to HTML
  const pageHtml = await renderToHtml(Page)
  const title = 'My first vite-plugin-ssr app'
  return escapeInject`<!DOCTYPE html>
    <html>
      <head>
        <title>{title}</title>
      </head>
      <body>
        <div id="page-root">${dangerouslySkipEscape(pageHtml)}</div>
      </body>
    </html>`
}

// _default.page.client.js
// Environment: Browser

import { getPage } from 'vite-plugin-ssr/client'
import { hydrateToDom } from 'my-favorite-view-framework'

// This file defines the *entire* browser-side code.
// If you leave this file empty then there is zero browser-side JavaScript.

hydrate()

async function hydrate() {
  const { Page } = await getPage() // In production, `await getPage()` is preloaded
  // You control how `Page` is hydrated
  await hydrateToDom(Page)
}

Not only can you use any tool you want, but integration is also simple: vite-plugin-ssr gets out of your way and you can simply follow the tool's official installation guide.

Full-fledged

Filesystem Routing, Data fetching, Pre-rendering (SSG), HMR, i18n, HTML Streaming.

Client Routing (faster page transitions) or Server Routing (simpler app architecture).

Pages can be rendered with SSR, as SPA, or to HTML-only.

Fast HMR

Blazing fast Hot Module Replacement powered by Vite ⚡. It stays fast as you scale (thanks to Vite's novel lazy-transpiling approach).

Routing

Pages are automatically routed:

FILESYSTEM                  URL
pages/index.page.js         /
pages/about.page.js         /about
pages/faq/index.page.js     /faq

You can also use so-called Route Strings and Route Functions.

// Route String - for parameterized routes
export default '/movie/:movieId'

// Route Function - for full flexibility
export default ({ url, ...pageContext }) => url==='/admin' && pageContext.isAdmin

You can choose between:

Client Routing for faster page transitions. (DOM mutation upon page navigation.)
Server Routing for a simpler app architecture. (Full HTML reload upon page navigation.)

SSR, SPA & HTML-first

You can create:

SSR pages.
SPA pages (aka MPA).
HTML-first pages (zero/minimal browser-side JavaScript).

For example, you can render an admin panel as SPA while rendering marketing pages to HTML-first.

HTML Streaming

HTML Streaming is the future. It enables, for example, drastic improvements in mobile performance (progressive loading of HTML content).

vite-plugin-ssr is the first SSR tool with support for HTML Streaming.

💫 Simple

With vite-plugin-ssr you integrate tools manually instead of using a plugin system.

While it means more work, it gives you a simple & sturdy foundation to build upon.

Less easy, but simpler

With vite-plugin-ssr you integrate tools yourself. This usually means more work and it's less easy than just adding a Next.js/Nuxt plugin; getting started is often slower.

But plugin systems are complex, limiting, and quickly become counterproductive. You end up fighting the plugin system and needing brittle workarounds to circumvent Next.js/Nuxt's black-box limiting nature. The net result is a substantial loss in dev time and frustration.

In contrast, vite-plugin-ssr gets out of your way and integrating a tool is simply a matter of following the tool's official installation guide.

In a nutshell: vite-plugin-ssr is less easy but simpler.

Stable foundation

Plugin systems / frameworks need to constantly keep up with the ecosystem, whereas do-one-thing-do-it-well tools tend to quickly stabilize. Actually, vite-plugin-ssr is already stable: the v1 release will most likley have no breaking changes with the current version, and the goal will be to stay on v1 for the foreseeable future.

More fun

Last but not least, manual integration is more fun (and more insightful) than fighting some arbitrary and idiosyncratic framework.

💎 Rock-solid

The source code of vite-plugin-ssr has no known bug, every release is assailed against a heavy suite of automated tests, and it's used in production by many companies.

Stable: the v1 release will most likely have no breaking changes with the current v0.3.x.

🌍 Deploy anywhere

Works with any server environement (Vercel, EC2 instance, AWS lambda, Firebase, Cloudflare Workers, Express.js, Fastify, Hapi, ...).

Pre-render your app and deploy it to any static host (Netlify, GitHub Pages, Cloudflare Pages, ...).

Fits very well Cloudflare Workers's compute model.

It's just a middleware

From an architectural point of view, vite-plugin-ssr is just a server middleware.

const { createPageRenderer } = require('vite-plugin-ssr')
const renderPage = createPageRenderer(/* ... */)

// `app` can be any server framework such as Express.js/Fastify/Koa/Hapi/...
app.get('*', async (req, res) => {
  // `renderPage()` can also be used in serverless environments such as
  // Cloudflare Workers and Vercel
  const pageContext = await renderPage({ url: req.url })
  res.send(pageContext.httpResponse.body)
})

Pre-rendering (aka SSG)

You can also pre-render your app to remove the need for a production Node.js server and deploy to any static host (Cloudflare Pages, GitHub Pages, Netlify, ...).

$ npx vite-plugin-ssr prerender
vite-plugin-ssr 0.1.2 pre-rendering HTML...
✓ 3 HTML documents pre-rendered.
dist/client/index.html
dist/client/about/index.html
dist/client/404.html

Cloudflare Workers + `vite-plugin-ssr` = ❤

Thanks to vite-plugin-ssr's lean architecture, your app is much less limited by Cloudflare Workers's 1MB bundle size limit.

In general, vite-plugin-ssr has been designed with Cloudflare Workers in mind, for example:

You can dev with Vite + Express.js for lightning fast HMR & dev start, while bundling your worker code for production with Cloudflare Workers's webpack bundler.
vite-plugin-ssr supports Cloudflare Workers's HTML Streaming.

⚡ High-performance

Browser-side code splitting: each page loads only the code it needs. Lighthouse score of 100%.

Fast Node.js cold start: pages are lazy-loaded so that adding pages doesn't increase the cold start of your serverless functions.

🚀 Scalable

DX that scales to hundreds of kLOCs — HMR & dev start stays fast.

Architectural flexibility that scales from small hobby projects to large-scale enterprise projects.

Lazy-transpiling

One of Vite's foundational novelty is lazy-transpiling: only executed code is transpiled. If you define ten pages but load only one page in the browser, then only the code for that page is transpiled.

Thanks to lazy-transpiling, you can scale to (very) large source code while keeping fast HMR & dev start.

No black box, no plugin system

At scale, Next.js/Nuxt's black-box nature and its plugin system become painfully limiting.

In contrast, vite-plugin-ssr is transparent: you keep control over both the server- and browser-side.

As you scale, you usually need increasingly custom SSR integrations; vite-plugin-ssr's flexibility accommodates such needs.

Vite + SSR + Scale = ❤

At (very) large scale, you can progressively replace vite-plugin-ssr with Vite's native SSR API which is low-level and highly flexible. If you're Netflix and perfecting UX leads to a substantial revenue increase, then vite-plugin-ssr and Vite's native SSR API are what you are looking for.

Large production apps are using Vite for its speed.

Tweet 1398240747661533184

Tweet 1392901819135795202

Tweet 1409983946201370626

Tweet 1423324336845426691

❤ Craftmanship

Crafted with attention to details and care for simplicity.

Upsteam contributions to Vite and others.

GitHub and Discord conversations are welcome.

Have a question? Want a feature? A tool integration is not working?Join our Discord or open a GitHub ticket.

Explore how it's like to use vite-plugin-ssr