Skip to content

docs: fix some mistakes in Environment API guides #20000

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
May 30, 2025
12 changes: 7 additions & 5 deletions docs/guide/api-environment-frameworks.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ Note that although the `FetchableDevEnvironment` is implemented as a class, it i

## Default `RunnableDevEnvironment`

Given a Vite server configured in middleware mode as described by the [SSR setup guide](/guide/ssr#setting-up-the-dev-server), let's implement the SSR middleware using the environment API. Error handling is omitted.
Given a Vite server configured in middleware mode as described by the [SSR setup guide](/guide/ssr#setting-up-the-dev-server), let's implement the SSR middleware using the environment API. Remember that it doesn't have to be called `ssr`, so we'll name it `server` in this example. Error handling is omitted.

```js
import fs from 'node:fs'
Expand All @@ -94,7 +94,7 @@ import { createServer } from 'vite'

const __dirname = path.dirname(fileURLToPath(import.meta.url))

const server = await createServer({
const viteServer = await createServer({
server: { middlewareMode: true },
appType: 'custom',
environments: {
Expand All @@ -106,7 +106,7 @@ const server = await createServer({

// You might need to cast this to RunnableDevEnvironment in TypeScript or
// use isRunnableDevEnvironment to guard the access to the runner
const environment = server.environments.node
const serverEnvironment = viteServer.environments.server

app.use('*', async (req, res, next) => {
const url = req.originalUrl
Expand All @@ -118,12 +118,14 @@ app.use('*', async (req, res, next) => {
// 2. Apply Vite HTML transforms. This injects the Vite HMR client,
// and also applies HTML transforms from Vite plugins, e.g. global
// preambles from @vitejs/plugin-react
template = await server.transformIndexHtml(url, template)
template = await viteServer.transformIndexHtml(url, template)

// 3. Load the server entry. import(url) automatically transforms
// ESM source code to be usable in Node.js! There is no bundling
// required, and provides full HMR support.
const { render } = await environment.runner.import('/src/entry-server.js')
const { render } = await serverEnvironment.runner.import(
'/src/entry-server.js',
)

// 4. render the app HTML. This assumes entry-server.js's exported
// `render` function calls appropriate framework SSR APIs,
Expand Down
4 changes: 2 additions & 2 deletions docs/guide/api-environment-instances.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,8 @@ During dev, the available environments in a dev server can be accessed using `se
// create the server, or get it from the configureServer hook
const server = await createServer(/* options */)

const environment = server.environments.client
environment.transformRequest(url)
const clientEnvironment = server.environments.client
clientEnvironment.transformRequest(url)
console.log(server.environments.ssr.moduleGraph)
```

Expand Down
2 changes: 1 addition & 1 deletion docs/guide/api-environment.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ For a simple SPA/MPA, no new APIs around environments are exposed to the config.
When we move to a typical server-side rendered (SSR) app, we'll have two environments:

- `client`: runs the app in the browser.
- `server`: runs the app in node (or other server runtimes) which renders pages before sending them to the browser.
- `ssr`: runs the app in node (or other server runtimes) which renders pages before sending them to the browser.

In dev, Vite executes the server code in the same Node process as the Vite dev server, giving a close approximation to the production environment. However, it is also possible for servers to run in other JS runtimes, like [Cloudflare's workerd](https://github.com/cloudflare/workerd) which have different constraints. Modern apps may also run in more than two environments, e.g. a browser, a node server, and an edge server. Vite 5 didn't allow to properly represent these environments.

Expand Down