From 981e1f5ca214ace0044350d566ecd267269a4e9b Mon Sep 17 00:00:00 2001 From: patak Date: Tue, 2 Nov 2021 01:48:49 +0100 Subject: [PATCH] docs: virtual modules ID naming convention (#5505) --- docs/guide/api-plugin.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/guide/api-plugin.md b/docs/guide/api-plugin.md index 5a76575d8fe914..58afcfea832dfe 100644 --- a/docs/guide/api-plugin.md +++ b/docs/guide/api-plugin.md @@ -17,7 +17,7 @@ When learning, debugging, or authoring plugins we suggest including [vite-plugin ## Conventions -If the plugin doesn't use Vite specific hooks and can be implemented as a [Compatible Rollup Plugin](#rollup-plugin-compatibility), then it is recommended to use the [Rollup Plugin naming conventions](https://rollupjs.org/guide/en/#conventions) +If the plugin doesn't use Vite specific hooks and can be implemented as a [Compatible Rollup Plugin](#rollup-plugin-compatibility), then it is recommended to use the [Rollup Plugin naming conventions](https://rollupjs.org/guide/en/#conventions) (except for virtual modules naming, see note below). - Rollup Plugins should have a clear name with `rollup-plugin-` prefix. - Include `rollup-plugin` and `vite-plugin` keywords in package.json. @@ -36,6 +36,10 @@ 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 +Rollup recommends prefixing the module ID for 'virtual modules' (e.g. for helper functions) with `\0`. This prevents other plugins from trying to process it. But this convention for paths isn't browser-friendly. + +Vite convention for virtual modules is to prefix the path with `virtual:`. If possible the plugin name should be used as a namespace to avoid collisions with other plugins in the ecosystem. For example, a `vite-plugin-posts` could ask users to import a `virtual:posts` or `virtual:posts/helpers` virtual modules to get build time information. + ## Plugins config Users will add plugins to the project `devDependencies` and configure them using the `plugins` array option.