@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
  ::
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nuxt/docs-nightly",
3
- "version": "5.0.0-29810231.9918cdce",
3
+ "version": "5.0.0-29810399.bd41d095",
4
4
  "repository": {
5
5
  "type": "git",
6
6
  "url": "git+https://github.com/nuxt/nuxt.git",