@nuxt/docs-nightly 5.0.0-29810231.9918cdce → 5.0.0-29810399.bd41d095
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -241,6 +241,113 @@ Every path is a function, because a builder may only resolve it while initialisi
|
|
|
241
241
|
`nuxt.serverBuild` and the `setServerBuild()` / `useServerBuild()` helpers are experimental and exported from `@nuxt/kit/internal`. The shape will change without a major release while a second server builder is being built out.
|
|
242
242
|
::
|
|
243
243
|
|
|
244
|
+
## Standing Up the SSR Renderer
|
|
245
|
+
|
|
246
|
+
Nuxt's SSR renderer is not part of `@nuxt/nitro-server`: it ships in the `nuxt` package and is
|
|
247
|
+
imported through builder-agnostic specifiers, so a server builder that is not backed by Nitro can
|
|
248
|
+
render with it. `@nuxt/nitro-server` is one consumer of it, and its own handler is a thin adapter.
|
|
249
|
+
|
|
250
|
+
The renderer is created with `createNuxtRenderer()`, which returns a web-standard handler:
|
|
251
|
+
|
|
252
|
+
```ts
|
|
253
|
+
import { createNuxtRenderer } from 'nuxt/renderer'
|
|
254
|
+
|
|
255
|
+
const renderer = createNuxtRenderer({
|
|
256
|
+
runtimeConfig: () => useRuntimeConfig(),
|
|
257
|
+
buildAssetsURL: (...path) => joinURL(baseURL, buildAssetsDir, ...path),
|
|
258
|
+
publicAssetsURL: (...path) => joinURL(baseURL, ...path),
|
|
259
|
+
getRouteRules: event => rulesFor(event.url.pathname),
|
|
260
|
+
hooks: () => hooks,
|
|
261
|
+
createResponse: (body, init) => new Response(body, init),
|
|
262
|
+
createError: init => new HTTPError(init),
|
|
263
|
+
})
|
|
264
|
+
|
|
265
|
+
const response = await renderer.fetch(event)
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
The event it takes is described in web standards only (a `Request`, a `URL`, a response to influence,
|
|
269
|
+
and a context), matching the `RequestEvent` a server builder contributes
|
|
270
|
+
through the `ServerTypes` registry in `@nuxt/schema`. Everything the renderer cannot
|
|
271
|
+
learn from the platform (route rules, hooks, response and error construction, early hints, island
|
|
272
|
+
rendering, and the prerender caches) is passed in, so the renderer itself imports no server runtime.
|
|
273
|
+
|
|
274
|
+
The renderer needs three things from the build.
|
|
275
|
+
|
|
276
|
+
### The Artifacts to Render With
|
|
277
|
+
|
|
278
|
+
The renderer imports the build outputs above (`nuxt/entry`, `nuxt/manifest`, and the rest), so a
|
|
279
|
+
builder that already fulfils the [build output contract](#the-build-output-contract) has them.
|
|
280
|
+
|
|
281
|
+
A server builder that bundles the app build's output, rather than inlining those module bodies, also
|
|
282
|
+
needs to know where the app build wrote it. Those paths are on the build description, in the same
|
|
283
|
+
register as the output paths:
|
|
284
|
+
|
|
285
|
+
```ts
|
|
286
|
+
import { useServerBuild } from '@nuxt/kit/internal'
|
|
287
|
+
|
|
288
|
+
const build = useServerBuild()
|
|
289
|
+
|
|
290
|
+
build.input.serverEntry() // the SSR entry the app build emitted: the input of a server bundle
|
|
291
|
+
build.input.serverDir() // the directory its chunks landed in
|
|
292
|
+
build.input.clientDir() // the client build's assets
|
|
293
|
+
build.input.clientManifest() // the manifest the renderer renders against
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
### Its Build-Time Configuration
|
|
297
|
+
|
|
298
|
+
The renderer reads the flags it was built with from `nuxt/renderer-config`, a module the server
|
|
299
|
+
builder provides. Everything in it is an inlined constant, so a build folds away the branches it
|
|
300
|
+
does not use. `addRendererConfig()` generates it from `nuxt.options` and points the specifier at it:
|
|
301
|
+
|
|
302
|
+
```ts
|
|
303
|
+
import { addRendererConfig } from '@nuxt/kit/internal'
|
|
304
|
+
|
|
305
|
+
addRendererConfig()
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
Constants a builder resolves for itself (anything derived from route rules, from a page matcher, or
|
|
309
|
+
from an asset it emits) default to the value of a build without the feature, and are replaced with
|
|
310
|
+
`overrides`, whose values are JS expressions:
|
|
311
|
+
|
|
312
|
+
```ts
|
|
313
|
+
addRendererConfig({
|
|
314
|
+
overrides: {
|
|
315
|
+
NUXT_RUNTIME_PAYLOAD_EXTRACTION: String(hasCachedRoutes),
|
|
316
|
+
spaTemplate: JSON.stringify(await spaLoadingTemplate(nuxt)),
|
|
317
|
+
},
|
|
318
|
+
})
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
`getRendererConfig()` returns the same module body without registering anything, for a builder that
|
|
322
|
+
serves its own virtual modules (as `@nuxt/nitro-server` does).
|
|
323
|
+
|
|
324
|
+
### The Defines It Is Compiled With
|
|
325
|
+
|
|
326
|
+
The renderer and the app runtime branch on `import.meta.*` flags, which a builder must replace at
|
|
327
|
+
build time. `getRendererDefines()` returns the set for a phase, so a builder does not re-derive it:
|
|
328
|
+
|
|
329
|
+
```ts
|
|
330
|
+
import { getRendererDefines } from '@nuxt/kit/internal'
|
|
331
|
+
|
|
332
|
+
const define = getRendererDefines('server') // or 'prerender'
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
Leaving them in place is not merely a size cost: `import.meta.prerender` reaching the runtime as
|
|
336
|
+
`undefined` silently disables payload extraction and the prerender caches.
|
|
337
|
+
|
|
338
|
+
::note
|
|
339
|
+
Import `createNuxtRenderer` from `nuxt/renderer` only in the module that is your server entry.
|
|
340
|
+
Anything the entry can also reach (an island handler, a route-rule helper) should import the pieces
|
|
341
|
+
it needs from the granular `nuxt/renderer/*` subpaths instead: pulling the barrel into a module the
|
|
342
|
+
entry shares produces a chunk cycle, which some bundlers resolve into a broken entry namespace.
|
|
343
|
+
::
|
|
344
|
+
|
|
345
|
+
::warning
|
|
346
|
+
`nuxt/renderer`, `nuxt/renderer-config`, `serverBuild.input`, and the renderer helpers in
|
|
347
|
+
`@nuxt/kit/internal` are experimental, and will change without a major release while a second server
|
|
348
|
+
builder is being built out.
|
|
349
|
+
::
|
|
350
|
+
|
|
244
351
|
::read-more{to="/docs/4.x/guide/going-further/internals"}
|
|
245
352
|
Learn more about the Nuxt interface and the build vs. runtime split.
|
|
246
353
|
::
|