From e526573cae8a2fb073bf9a38bef17aeb9adbebc3 Mon Sep 17 00:00:00 2001 From: Bjorn Lu Date: Thu, 11 Apr 2024 03:17:49 +0800 Subject: [PATCH] docs: add links to environment api (#16392) --- docs/guide/api-vite-runtime.md | 4 +++- docs/guide/ssr.md | 15 +++++---------- 2 files changed, 8 insertions(+), 11 deletions(-) diff --git a/docs/guide/api-vite-runtime.md b/docs/guide/api-vite-runtime.md index 5c4ee3f07c3ec5..9aa579d268ddcf 100644 --- a/docs/guide/api-vite-runtime.md +++ b/docs/guide/api-vite-runtime.md @@ -1,7 +1,9 @@ # Vite Runtime API :::warning Low-level API -This API was introduced in Vite 5.1 as an experimental feature. It was added to [gather feedback](https://github.com/vitejs/vite/discussions/15774). There will probably be breaking changes to it in Vite 5.2, so make sure to pin the Vite version to `~5.1.0` when using it. This is a low-level API meant for library and framework authors. If your goal is to create an application, make sure to check out the higher-level SSR plugins and tools at [Awesome Vite SSR section](https://github.com/vitejs/awesome-vite#ssr) first. +This API was introduced in Vite 5.1 as an experimental feature. It was added to [gather feedback](https://github.com/vitejs/vite/discussions/15774). There will likely be breaking changes, so make sure to pin the Vite version to `~5.1.0` when using it. This is a low-level API meant for library and framework authors. If your goal is to create an application, make sure to check out the higher-level SSR plugins and tools at [Awesome Vite SSR section](https://github.com/vitejs/awesome-vite#ssr) first. + +Currently, the API is being revised as the [Environment API](https://github.com/vitejs/vite/discussions/16358) which is released at `^6.0.0-alpha.0`. ::: The "Vite Runtime" is a tool that allows running any code by processing it with Vite plugins first. It is different from `server.ssrLoadModule` because the runtime implementation is decoupled from the server. This allows library and framework authors to implement their own layer of communication between the server and the runtime. diff --git a/docs/guide/ssr.md b/docs/guide/ssr.md index 60ed03b5ccc406..79c29518994a2b 100644 --- a/docs/guide/ssr.md +++ b/docs/guide/ssr.md @@ -8,6 +8,8 @@ The following guide also assumes prior experience working with SSR in your frame :::warning Low-level API This is a low-level API meant for library and framework authors. If your goal is to create an application, make sure to check out the higher-level SSR plugins and tools at [Awesome Vite SSR section](https://github.com/vitejs/awesome-vite#ssr) first. That said, many applications are successfully built directly on top of Vite's native low-level API. + +Currently, Vite is working on an improved SSR API with the [Environment API](https://github.com/vitejs/vite/discussions/16358). Check out the link for more details. ::: :::tip Help @@ -138,17 +140,10 @@ app.use('*', async (req, res, next) => { // preambles from @vitejs/plugin-react template = await vite.transformIndexHtml(url, template) - // 3a. Load the server entry. ssrLoadModule automatically transforms + // 3. Load the server entry. ssrLoadModule automatically transforms // ESM source code to be usable in Node.js! There is no bundling // required, and provides efficient invalidation similar to HMR. const { render } = await vite.ssrLoadModule('/src/entry-server.js') - // 3b. Since Vite 5.1, you can use the experimental createViteRuntime API - // instead. - // It fully supports HMR and works in a simillar way to ssrLoadModule - // More advanced use case would be creating a runtime in a separate - // thread or even a different machine using ViteRuntime class - const runtime = await vite.createViteRuntime(server) - const { render } = await runtime.executeEntrypoint('/src/entry-server.js') // 4. render the app HTML. This assumes entry-server.js's exported // `render` function calls appropriate framework SSR APIs, @@ -183,7 +178,7 @@ The `dev` script in `package.json` should also be changed to use the server scri To ship an SSR project for production, we need to: 1. Produce a client build as normal; -2. Produce an SSR build, which can be directly loaded via `import()` so that we don't have to go through Vite's `ssrLoadModule` or `runtime.executeEntrypoint`; +2. Produce an SSR build, which can be directly loaded via `import()` so that we don't have to go through Vite's `ssrLoadModule`; Our scripts in `package.json` will look like this: @@ -203,7 +198,7 @@ Then, in `server.js` we need to add some production specific logic by checking ` - Instead of reading the root `index.html`, use the `dist/client/index.html` as the template, since it contains the correct asset links to the client build. -- Instead of `await vite.ssrLoadModule('/src/entry-server.js')` or `await runtime.executeEntrypoint('/src/entry-server.js')`, use `import('./dist/server/entry-server.js')` (this file is the result of the SSR build). +- Instead of `await vite.ssrLoadModule('/src/entry-server.js')`, use `import('./dist/server/entry-server.js')` (this file is the result of the SSR build). - Move the creation and all usage of the `vite` dev server behind dev-only conditional branches, then add static file serving middlewares to serve files from `dist/client`.