Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
docs: cleanup changes (#8989)
  • Loading branch information
bluwy committed Jul 8, 2022
1 parent 33d6177 commit 07aef1b
Show file tree
Hide file tree
Showing 13 changed files with 97 additions and 121 deletions.
4 changes: 2 additions & 2 deletions docs/config/server-options.md
Expand Up @@ -198,8 +198,8 @@ Create Vite server in middleware mode.
- **Example:**

```js
const express = require('express')
const { createServer: createViteServer } = require('vite')
import express from 'express'
import { createServer as createViteServer } from 'vite'

async function createServer() {
const app = express()
Expand Down
15 changes: 10 additions & 5 deletions docs/guide/api-javascript.md
Expand Up @@ -13,7 +13,10 @@ async function createServer(inlineConfig?: InlineConfig): Promise<ViteDevServer>
**Example Usage:**

```js
const { createServer } = require('vite')
import { fileURLToPath } from 'url'
import { createServer } from 'vite'
const __dirname = fileURLToPath(new URL('.', import.meta.url))
;(async () => {
const server = await createServer({
Expand Down Expand Up @@ -134,8 +137,11 @@ async function build(
**Example Usage:**

```js
const path = require('path')
const { build } = require('vite')
import path from 'path'
import { fileURLToPath } from 'url'
import { build } from 'vite'
const __dirname = fileURLToPath(new URL('.', import.meta.url))
;(async () => {
await build({
Expand All @@ -161,8 +167,7 @@ async function preview(inlineConfig?: InlineConfig): Promise<PreviewServer>
**Example Usage:**

```js
const { preview } = require('vite')
import { preview } from 'vite'
;(async () => {
const previewServer = await preview({
// any valid user config options, plus `mode` and `configFile`
Expand Down
4 changes: 2 additions & 2 deletions docs/guide/api-plugin.md
Expand Up @@ -11,7 +11,7 @@ Vite strives to offer established patterns out of the box, so before creating a
When creating a plugin, you can inline it in your `vite.config.js`. There is no need to create a new package for it. Once you see that a plugin was useful in your projects, consider sharing it to help others [in the ecosystem](https://chat.vitejs.dev).

::: tip
When learning, debugging, or authoring plugins we suggest including [vite-plugin-inspect](https://github.com/antfu/vite-plugin-inspect) in your project. It allows you to inspect the intermediate state of Vite plugins. After installing, you can visit `localhost:5173/__inspect/` to inspect the modules and transformation stack of your project. Check out install instructions in the [vite-plugin-inspect docs](https://github.com/antfu/vite-plugin-inspect).
When learning, debugging, or authoring plugins, we suggest including [vite-plugin-inspect](https://github.com/antfu/vite-plugin-inspect) in your project. It allows you to inspect the intermediate state of Vite plugins. After installing, you can visit `localhost:5173/__inspect/` to inspect the modules and transformation stack of your project. Check out install instructions in the [vite-plugin-inspect docs](https://github.com/antfu/vite-plugin-inspect).
![vite-plugin-inspect](/images/vite-plugin-inspect.png)
:::

Expand Down Expand Up @@ -199,7 +199,7 @@ Vite plugins can also provide hooks that serve Vite-specific purposes. These hoo
name: 'mutate-config',
config(config, { command }) {
if (command === 'build') {
config.root = __dirname
config.root = 'foo'
}
}
})
Expand Down
4 changes: 0 additions & 4 deletions docs/guide/assets.md
Expand Up @@ -113,7 +113,3 @@ const imgUrl = new URL(imagePath, import.meta.url).href
::: warning Does not work with SSR
This pattern does not work if you are using Vite for Server-Side Rendering, because `import.meta.url` have different semantics in browsers vs. Node.js. The server bundle also cannot determine the client host URL ahead of time.
:::
::: warning `target` needs to be `es2020` or higher
This pattern will not work if [build-target](/config/build-options.md#build-target) or [optimizedeps.esbuildoptions.target](/config/dep-optimization-options.md#optimizedeps-esbuildoptions) is set to a value lower than `es2020`.
:::
40 changes: 20 additions & 20 deletions docs/guide/build.md
Expand Up @@ -35,7 +35,7 @@ The build can be customized via various [build config options](/config/build-opt

```js
// vite.config.js
module.exports = defineConfig({
export default defineConfig({
build: {
rollupOptions: {
// https://rollupjs.org/guide/en/#big-list-of-options
Expand All @@ -53,7 +53,7 @@ You can configure how chunks are split using `build.rollupOptions.output.manualC
```js
// vite.config.js
import { splitVendorChunkPlugin } from 'vite'
module.exports = defineConfig({
export default defineConfig({
plugins: [splitVendorChunkPlugin()]
})
```
Expand All @@ -66,7 +66,7 @@ You can enable rollup watcher with `vite build --watch`. Or, you can directly ad

```js
// vite.config.js
module.exports = defineConfig({
export default defineConfig({
build: {
watch: {
// https://rollupjs.org/guide/en/#watch-options
Expand Down Expand Up @@ -97,10 +97,10 @@ During build, all you need to do is to specify multiple `.html` files as entry p

```js
// vite.config.js
const { resolve } = require('path')
const { defineConfig } = require('vite')
import { resolve } from 'path'
import { defineConfig } from 'vite'

module.exports = defineConfig({
export default defineConfig({
build: {
rollupOptions: {
input: {
Expand All @@ -122,10 +122,10 @@ When it is time to bundle your library for distribution, use the [`build.lib` co

```js
// vite.config.js
const path = require('path')
const { defineConfig } = require('vite')
import { resolve } from 'path'
import { defineConfig } from 'vite'

module.exports = defineConfig({
export default defineConfig({
build: {
lib: {
entry: path.resolve(__dirname, 'lib/main.js'),
Expand Down Expand Up @@ -214,17 +214,17 @@ experimental: {
If the hashed assets and public files aren't deployed together, options for each group can be defined independently using asset `type` included in the third `context` param given to the function.

```js
experimental: {
renderBuiltUrl(filename: string, { hostType: 'js' | 'css' | 'html', type: 'public' | 'asset' }) {
if (type === 'public') {
return 'https://www.domain.com/' + filename
}
else if (path.extname(importer) === '.js') {
return { runtime: `window.__assetsPath(${JSON.stringify(filename)})` }
}
else {
return 'https://cdn.domain.com/assets/' + filename
}
experimental: {
renderBuiltUrl(filename: string, { hostType: 'js' | 'css' | 'html', type: 'public' | 'asset' }) {
if (type === 'public') {
return 'https://www.domain.com/' + filename
}
else if (path.extname(importer) === '.js') {
return { runtime: `window.__assetsPath(${JSON.stringify(filename)})` }
}
else {
return 'https://cdn.domain.com/assets/' + filename
}
}
}
```
9 changes: 8 additions & 1 deletion docs/guide/env-and-mode.md
Expand Up @@ -12,6 +12,8 @@ Vite exposes env variables on the special **`import.meta.env`** object. Some bui

- **`import.meta.env.DEV`**: {boolean} whether the app is running in development (always the opposite of `import.meta.env.PROD`)

- **`import.meta.env.SSR`**: {boolean} whether the app is running in the [server](./ssr.md#conditional-logic).

### Production Replacement

During production, these env variables are **statically replaced**. It is therefore necessary to always reference them using the full static string. For example, dynamic key access like `import.meta.env[key]` will not work.
Expand Down Expand Up @@ -47,12 +49,17 @@ Loaded env variables are also exposed to your client source code via `import.met
To prevent accidentally leaking env variables to the client, only variables prefixed with `VITE_` are exposed to your Vite-processed code. e.g. the following file:

```
DB_PASSWORD=foobar
VITE_SOME_KEY=123
DB_PASSWORD=foobar
```

Only `VITE_SOME_KEY` will be exposed as `import.meta.env.VITE_SOME_KEY` to your client source code, but `DB_PASSWORD` will not.

```js
console.log(import.meta.env.VITE_SOME_KEY) // 123
console.log(import.meta.env.DB_PASSWORD) // undefined
```
If you want to customize env variables prefix, see [envPrefix](/config/index#envprefix) option.
:::warning SECURITY NOTES
Expand Down
5 changes: 3 additions & 2 deletions docs/guide/features.md
Expand Up @@ -108,11 +108,12 @@ Vite provides first-class Vue support:

- Vue 3 SFC support via [@vitejs/plugin-vue](https://github.com/vitejs/vite/tree/main/packages/plugin-vue)
- Vue 3 JSX support via [@vitejs/plugin-vue-jsx](https://github.com/vitejs/vite/tree/main/packages/plugin-vue-jsx)
- Vue 2 support via [underfin/vite-plugin-vue2](https://github.com/underfin/vite-plugin-vue2)
- Vue 2.7 support via [vitejs/vite-plugin-vue2](https://github.com/vitejs/vite-plugin-vue2)
- Vue <2.7 support via [underfin/vite-plugin-vue2](https://github.com/underfin/vite-plugin-vue2)

## JSX

`.jsx` and `.tsx` files are also supported out of the box. JSX transpilation is also handled via [esbuild](https://esbuild.github.io), and defaults to the React 16 flavor. React 17 style JSX support in esbuild is tracked [here](https://github.com/evanw/esbuild/issues/334).
`.jsx` and `.tsx` files are also supported out of the box. JSX transpilation is also handled via [esbuild](https://esbuild.github.io).

Vue users should use the official [@vitejs/plugin-vue-jsx](https://github.com/vitejs/vite/tree/main/packages/plugin-vue-jsx) plugin, which provides Vue 3 specific features including HMR, global component resolving, directives and slots.

Expand Down
2 changes: 1 addition & 1 deletion docs/guide/index.md
Expand Up @@ -18,7 +18,7 @@ You can learn more about the rationale behind the project in the [Why Vite](./wh

## Browser Support

- The default build targets browsers that support both [native ES Modules](https://caniuse.com/es6-module) and [native ESM dynamic import](https://caniuse.com/es6-module-dynamic-import). Legacy browsers can be supported via the official [@vitejs/plugin-legacy](https://github.com/vitejs/vite/tree/main/packages/plugin-legacy) - see the [Building for Production](./build) section for more details.
The default build targets browsers that support both [native ES Modules](https://caniuse.com/es6-module) and [native ESM dynamic import](https://caniuse.com/es6-module-dynamic-import). Legacy browsers can be supported via the official [@vitejs/plugin-legacy](https://github.com/vitejs/vite/tree/main/packages/plugin-legacy) - see the [Building for Production](./build) section for more details.

## Trying Vite Online

Expand Down
22 changes: 11 additions & 11 deletions docs/guide/migration.md
Expand Up @@ -17,17 +17,17 @@ A small fraction of users will now require using [@vitejs/plugin-legacy](https:/

## Config Options Changes

- The following options that were already deprecated in v2 have been removed:
The following options that were already deprecated in v2 have been removed:

- `alias` (switch to [`resolve.alias`](../config/shared-options.md#resolve-alias))
- `dedupe` (switch to [`resolve.dedupe`](../config/shared-options.md#resolve-dedupe))
- `build.base` (switch to [`base`](../config/shared-options.md#base))
- `build.brotliSize` (switch to [`build.reportCompressedSize`](../config/build-options.md#build-reportcompressedsize))
- `build.cleanCssOptions` (Vite now uses esbuild for CSS minification)
- `build.polyfillDynamicImport` (use [`@vitejs/plugin-legacy`](https://github.com/vitejs/vite/tree/main/packages/plugin-legacy) for browsers without dynamic import support)
- `optimizeDeps.keepNames` (switch to [`optimizeDeps.esbuildOptions.keepNames`](../config/dep-optimization-options.md#optimizedeps-esbuildoptions))
- `alias` (switch to [`resolve.alias`](../config/shared-options.md#resolve-alias))
- `dedupe` (switch to [`resolve.dedupe`](../config/shared-options.md#resolve-dedupe))
- `build.base` (switch to [`base`](../config/shared-options.md#base))
- `build.brotliSize` (switch to [`build.reportCompressedSize`](../config/build-options.md#build-reportcompressedsize))
- `build.cleanCssOptions` (Vite now uses esbuild for CSS minification)
- `build.polyfillDynamicImport` (use [`@vitejs/plugin-legacy`](https://github.com/vitejs/vite/tree/main/packages/plugin-legacy) for browsers without dynamic import support)
- `optimizeDeps.keepNames` (switch to [`optimizeDeps.esbuildOptions.keepNames`](../config/dep-optimization-options.md#optimizedeps-esbuildoptions))

## Architecture changes and legacy Options
## Architecture Changes and Legacy Options

This section describes the biggest architecture changes in Vite v3. To allow projects to migrate from v2 in case of a compat issue, legacy options have been added to revert to the Vite v2 strategies.

Expand Down Expand Up @@ -72,7 +72,7 @@ Also [`build.rollupOptions.output.inlineDynamicImports`](https://rollupjs.org/gu
- When using an alias with `import.meta.glob`, the keys are always absolute.
- `import.meta.globEager` is now deprecated. Use `import.meta.glob('*', { eager: true })` instead.

### WebAssembly support
### WebAssembly Support

`import init from 'example.wasm'` syntax is dropped to prevent future collision with ["ESM integration for Wasm"](https://github.com/WebAssembly/esm-integration).
You can use `?init` which is similar to the previous behavior.
Expand All @@ -87,7 +87,7 @@ You can use `?init` which is similar to the previous behavior.
})
```

### Automatic https certificate generation
### Automatic https Certificate Generation

A valid certificate is needed when using `https`. In Vite v2, if no certificate was configured, a self-signed certificate was automatically created and cached.
Since Vite v3, we recommend manually creating your certificates. If you still want to use the automatic generation from v2, this feature can be enabled back by adding [@vitejs/plugin-basic-ssl](https://github.com/vitejs/vite-plugin-basic-ssl) to the project plugins.
Expand Down
12 changes: 6 additions & 6 deletions docs/guide/ssr.md
Expand Up @@ -66,10 +66,10 @@ When building an SSR app, you likely want to have full control over your main se
**server.js**
```js{17-19}
const fs = require('fs')
const path = require('path')
const express = require('express')
const { createServer: createViteServer } = require('vite')
import fs from 'fs'
import path from 'path'
import express from 'express'
import {createServer as createViteServer} from 'vite'

async function createServer() {
const app = express()
Expand Down Expand Up @@ -154,7 +154,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 `require()` so that we don't have to go through Vite's `ssrLoadModule`;
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:
Expand All @@ -174,7 +174,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 instead, since it contains the correct asset links to the client build.
- Instead of `await vite.ssrLoadModule('/src/entry-server.js')`, use `require('./dist/server/entry-server.js')` instead (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')` instead (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`.
Expand Down

0 comments on commit 07aef1b

Please sign in to comment.