Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/dvlkit/nuxe/llms.txt

Use this file to discover all available pages before exploring further.

Every route in a Nuxe application is server-side rendered out of the box. When a request arrives, the server runs your Vue component tree, streams the resulting HTML to the browser, and the Vue runtime then hydrates that HTML on the client to make it fully interactive. You do not need to configure anything to enable SSR — it is the default mode for every page.

​
How SSR works in Nuxe

Nuxe uses Nitro as its server engine. Incoming HTTP requests are handled by handler.ts, which orchestrates the following steps:
1

Request arrives at Nitro

Nitro receives the HTTP request and forwards it to the Nuxe handler as a Web-standard Request object.
2

Vue app is created

The handler loads the SSR entry (entry-server.ts) and creates a fresh Vue app instance for each request, providing the current URL and an SSR context object.
3

HTML is streamed

Nuxe calls renderToWebStream from vue/server-renderer to render the app tree into a ReadableStream. Chunks of HTML are emitted as Vue resolves async components and onServerPrefetch hooks. The <head> shell (populated by useHead) is emitted first, followed by the streamed component output.
4

Payload is serialised

After the component tree is fully rendered, Nuxe serialises the SSR payload — useAsyncData results, useState values, and public runtime config — into a window.__NUXE__ script tag appended to the HTML before the closing </body>.
5

Client hydrates

The browser receives the HTML, executes the client entry script (entry-client.ts), and Vue hydrates the existing DOM using the pre-fetched payload, skipping redundant network calls.

​
Dev vs production

Nuxe has two runtime modes with different serving strategies: 
# Starts the dev server with HMR and vite-node for on-demand SSR transforms
nuxe dev
In development, Nuxe starts a Vite dev server in middleware mode and uses vite-node to execute the server-side entry on every request. This means you get hot-module replacement without restarting the server — changes to pages, layouts, and composables are reflected immediately. In production, nuxe build runs two Vite builds (a client environment and an ssr environment) and outputs them to .output/. The client assets (JS, CSS) are written to .output/public/; the SSR bundle is at .output/server/ssr/index.js; and the Nitro server entry point is at .output/server/index.mjs. nuxe start then serves both using the same Nitro-backed handler with no Vite overhead.

​
Per-page SSR control with routeRules

You can opt individual pages out of SSR without affecting the rest of your app by setting routeRules.ssr = false inside definePage. The server still delivers a minimal HTML shell so the client JavaScript can boot, but no server-side Vue rendering is performed for that route.
app/pages/spa.vue
<script setup>
definePage({
  routeRules: { ssr: false },
})

useHead({ title: 'SPA Mode | my-app' })

const counter = ref(0)
</script>

<template>
  <div>
    <h1>SPA Mode</h1>
    <p>This page is rendered only on the client.</p>
    <p>Counter: {{ counter }}</p>
    <button type="button" @click="counter++">Increment</button>
  </div>
</template>
When the handler detects _spa: true on the SSR context (set by the route-rules middleware), it short-circuits the render and returns a bare HTML shell: 
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <!-- entry CSS links injected here in production -->
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="...entry-client..."></script>
  </body>
</html>
Pages with routeRules.ssr = false still receive this minimal HTML shell, so the client JavaScript boots and Vue mounts normally. The only difference from a full SSR page is that no server-rendered markup is inside <div id="app"> before hydration.

​
Streaming

Nuxe uses renderToWebStream from Vue’s server renderer to stream HTML as it becomes available. The response is sent with Transfer-Encoding: chunked, so the browser can start parsing and painting before the entire page is rendered on the server. Late-resolved <head> chunks (from async suspense boundaries) are injected inline as small <script> tags that are immediately removed after execution. 
// From packages/nuxe/lib/server/handler.ts — simplified
const vueStream = renderToWebStream(app, ssrContext)

return new Response(htmlStream, {
  status: 200,
  headers: {
    'Content-Type': 'text/html',
    'Transfer-Encoding': 'chunked',
  },
})

​
SSR-aware data fetching

useAsyncData and useFetch are fully SSR-aware. On the server they execute the fetch handler inside the request context and store the result in the SSR payload. On the client, hydration reads that payload instead of re-running the fetch — so your data is available immediately without an extra round-trip.
app/pages/fetch-demo.vue
<script setup lang="ts">
// Runs on the server during SSR; hydrates on the client automatically
const { data, pending, error } = await useAsyncData('user-list', () =>
  $fetch('/api/users')
)
</script>

<template>
  <div v-if="pending">Loading…</div>
  <div v-else-if="error">Error: {{ error.message }}</div>
  <ul v-else>
    <li v-for="user in data" :key="user.id">{{ user.name }}</li>
  </ul>
</template>
useFetch wraps useAsyncData and additionally serialises the HTTP status code into the payload so client-side hydration reflects the exact response the server received.

​
Environment variables

VariableDefaultSet byDescription
PORT3000YouPort the dev and production servers listen on
NODE_ENV'development'You / frameworkControls build-time and runtime optimisations
NUXE_BASE_URLhttp://localhost:<PORT>FrameworkFull base URL used for internal SSR fetch requests; set automatically by nuxe dev and nuxe start
NUXE_DEV'false'FrameworkSet to 'true' while nuxe dev is running; controls whether the handler uses vite-node or the pre-built SSR bundle
PORT and NODE_ENV can be set in your shell or a .env file before running any nuxe command. NUXE_BASE_URL and NUXE_DEV are managed by the framework and should not normally be set manually.
To pre-render a page as static HTML at build time instead of rendering it on every request, use prerender: true in routeRules. Nuxe will call the SSR handler during nuxe build, write the result to .output/public/, and Nitro will serve it as a static asset on subsequent requests — no server rendering needed at runtime.
app/pages/landing.vue
<script setup>
definePage({
  routeRules: { prerender: true },
})
</script>

Build docs developers (and LLMs) love

Get started for freeTalk to us