docs: using plugins guide (#2743)

docs/.vitepress/config.js

@@ -81,6 +81,10 @@ module.exports = {
               text: 'Features',
               link: '/guide/features'
             },
+            {
+              text: 'Using Plugins',
+              link: '/guide/using-plugins'
+            },
             {
               text: 'Dependency Pre-Bundling',
               link: '/guide/dep-pre-bundling'

docs/config/index.md

@@ -115,7 +115,7 @@ export default ({ command, mode }) => {
 
 - **Type:** ` (Plugin | Plugin[])[]`
 
-  Array of plugins to use. See [Plugin API](/guide/api-plugin) for more details on Vite plugins.
+  Array of plugins to use. Falsy plugins are ignored and arrays of plugins are flattened. See [Plugin API](/guide/api-plugin) for more details on Vite plugins.
 
 ### publicDir
 

docs/guide/api-plugin.md

@@ -1,6 +1,6 @@
 # Plugin API
 
-Vite plugins extends Rollup's well-designed plugin interface with a few extra vite-specific options. As a result, you can write a Vite plugin once and have it work for both dev and build.
+Vite plugins extends Rollup's well-designed plugin interface with a few extra Vite-specific options. As a result, you can write a Vite plugin once and have it work for both dev and build.
 
 **It is recommended to go through [Rollup's plugin documentation](https://rollupjs.org/guide/en/#plugin-development) first before reading the sections below.**
 
@@ -25,6 +25,48 @@ If your plugin is only going to work for a particular framework, its name should
 - `vite-plugin-react-` prefix for React Plugins
 - `vite-plugin-svelte-` prefix for Svelte Plugins
 
+## Plugins config
+
+Users will add plugins to the project `devDependencies` and configure them using the `plugins` array option.
+
+```js
+// vite.config.js
+import vitePlugin from 'vite-plugin-feature'
+import rollupPlugin from 'rollup-plugin-feature'
+
+export default {
+  plugins: [ vitePlugin(), rollupPlugin() ]
+}
+```
+
+Falsy plugins will be ignored, which can be used to easily activate or deactivate plugins. 
+
+`plugins` also accept presets including several plugins as a single element. This is useful for complex features (like framework integration) that are implemented using several plugins. The array will be flattened internally.
+
+```js
+// framework-plugin
+import frameworkRefresh from 'vite-plugin-framework-refresh'
+import frameworkDevtools from 'vite-plugin-framework-devtools'
+
+export default function framework(config) {
+  return [
+    frameworkRefresh(config),
+    frameworkDevTools(config)
+  ]
+}
+```
+
+```js
+// vite.config.js
+import framework from 'vite-plugin-framework'
+
+export default {
+  plugins: [
+    framework()
+  ]
+}
+```
+
 ## Simple Examples
 
 :::tip
@@ -365,13 +407,13 @@ A Vite plugin can additionally specify an `enforce` property (similar to webpack
 
 ## Conditional Application
 
-By default plugins are invoked for both serve and build. In cases where a plugin needs to be conditionally applied only during serve or build, use the `apply` property:
+By default plugins are invoked for both serve and build. In cases where a plugin needs to be conditionally applied only during serve or build, use the `apply` property to only invoke them during `'build'` or `'serve'`:
 
 ```js
 function myPlugin() {
   return {
     name: 'build-only',
-    apply: 'build'
+    apply: 'build' // or 'serve'
   }
 }
 ```
@@ -380,7 +422,7 @@ function myPlugin() {
 
 A fair number of Rollup plugins will work directly as a Vite plugin (e.g. `@rollup/plugin-alias` or `@rollup/plugin-json`), but not all of them, since some plugin hooks do not make sense in an unbundled dev server context.
 
-In general, as long as a rollup plugin fits the following criterias then it should just work as a Vite plugin:
+In general, as long as a Rollup plugin fits the following criterias then it should just work as a Vite plugin:
 
 - It doesn't use the [`moduleParsed`](https://rollupjs.org/guide/en/#moduleparsed) hook.
 - It doesn't have strong coupling between bundle-phase hooks and output-phase hooks.
@@ -404,7 +446,7 @@ export default {
 }
 ```
 
-Check out [Vite Rollup Plugins](https://vite-rollup-plugins.patak.dev) for a list of compatible official rollup plugins with usage instructions.
+Check out [Vite Rollup Plugins](https://vite-rollup-plugins.patak.dev) for a list of compatible official Rollup plugins with usage instructions.
 
 ## Path normalization
 

docs/guide/using-plugins.md

@@ -0,0 +1,84 @@
+# Using Plugins
+
+Vite can be extended using plugins, which are based on Rollup's well-designed plugin interface with a few extra Vite-specific options. This means that Vite users can rely on the mature ecosystem of Rollup plugins, while also being able to extend the dev server and SSR functionality as needed.
+
+## Adding a Plugin
+
+To use a plugin, it needs to be added to the `devDependencies` of the project and included in the `plugins` array in the `vite.config.js` config file. For example, to provide support for legacy browsers, the official [@vitejs/plugin-legacy](https://github.com/vitejs/vite/tree/main/packages/plugin-legacy) can be used:
+
+```
+$ npm i -D @vitejs/plugin-legacy
+```
+
+```js
+// vite.config.js
+import legacy from '@vitejs/plugin-legacy'
+
+export default {
+  plugins: [
+    legacy({
+      targets: ['defaults', 'not IE 11']
+    })
+  ]
+}
+```
+
+`plugins` also accept presets including several plugins as a single element. This is useful for complex features (like framework integration) that are implemented using several plugins. The array will be flattened internally.
+
+Falsy plugins will be ignored, which can be used to easily activate or deactivate plugins.
+
+## Finding Plugins
+
+:::tip NOTE
+Vite aims to provide out-of-the-box support for common web development patterns. Before searching for a Vite or compatible Rollup plugin, check out the [Features Guide](../guide/features.md). A lot of the cases where a plugin would be needed in a Rollup project are already covered in Vite.
+:::
+
+Check out the [Plugins section](../plugins) for information about official plugins. Community plugins are listed in [awesome-vite](https://github.com/vitejs/awesome-vite#plugins). For compatible Rollup plugins, check out [Vite Rollup Plugins](https://vite-rollup-plugins.patak.dev) for a list of compatible official Rollup plugins with usage instructions or the [Rollup Plugin Compatibility section](../guide/api-plugin#rollup-plugin-compatibility) in case it is not listed there.
+
+You can also find plugins that follow the [recommended conventions](./api-plugin.md#conventions) using a [npm search for vite-plugin](https://www.npmjs.com/search?q=vite-plugin&ranking=popularity) for Vite plugins or a [npm search for rollup-plugin](https://www.npmjs.com/search?q=rollup-plugin&ranking=popularity) or a [npm search for vite-plugin](https://www.npmjs.com/search?q=vite-plugin&ranking=popularity) for Rollup plugins.
+
+## Enforcing Plugin Ordering
+
+For compatibility with some Rollup plugins, it may be needed to enforce the order of the plugin or only apply at build time. This should be an implementation detail for Vite plugins. You can enforce the position of a plugin with the `enforce` modifier:
+
+- `pre`: invoke plugin before Vite core plugins
+- default: invoke plugin after Vite core plugins
+- `post`: invoke plugin after Vite build plugins
+
+```js
+// vite.config.js
+import image from '@rollup/plugin-image'
+
+export default {
+  plugins: [
+    {
+      ...image(),
+      enforce: 'pre',
+    },
+  ]
+}
+```
+
+Check out [Plugins API Guide](./api-plugin.md#plugin-ordering) for detailed information, and look out for the `enforce` label and usage instructions for popular plugins in the [Vite Rollup Plugins](https://vite-rollup-plugins.patak.dev) compatibility listing.
+
+## Conditional Application
+
+By default, plugins are invoked for both serve and build. In cases where a plugin needs to be conditionally applied only during serve or build, use the `apply` property to only invoke them during `'build'` or `'serve'`:
+
+```js
+// vite.config.js
+import typescript2 from 'rollup-plugin-typescript2'
+
+export default {
+  plugins: [
+    {
+      ...typescript2(),
+      apply: 'build',
+    },
+  ]
+}
+```
+
+## Building Plugins
+
+Check out the [Plugins API Guide](./api-plugin.md) for documentation about creating plugins.

docs/plugins/index.md

@@ -24,7 +24,7 @@ Vite aims to provide out-of-the-box support for common web development patterns.
 
 ## Community Plugins
 
-Check out [awesome-vite](https://github.com/vitejs/awesome-vite) - you can also submit a PR to list your plugins there.
+Check out [awesome-vite](https://github.com/vitejs/awesome-vite#plugins) - you can also submit a PR to list your plugins there.
 
 ## Rollup Plugins