@miyaoka/vite-plugin-doc-block


Vite plugin to strip custom blocks from Vue SFC.

Write documentation directly in your Vue components. The plugin removes them during build, so they don't affect bundle size.

Install

``bash
pnpm add -D @miyaoka/vite-plugin-doc-block
`

Usage

`ts
// vite.config.ts
import vue from '@vitejs/plugin-vue'
import { defineConfig } from 'vite'
import { docBlockPlugin } from '@miyaoka/vite-plugin-doc-block'

export default defineConfig({
plugins: [docBlockPlugin(), vue()],
})
`

> Note: Place docBlockPlugin() before other Vue-related plugins.
> This plugin must run before vite-plugin-vue-inspector (used by vite-plugin-vue-devtools),
> which would error when parsing HTML-like strings (e.g. ) inside blocks.

Then you can write blocks in your Vue components:

`vue



MyComponent

This component displays user information.

Props

- userId - The user ID to display

Usage

Used in the user profile page.



`

The block will be removed during build.

Why

- Colocation: Keep documentation next to the code it describes
- Zero runtime cost: Stripped at build time
- IDE friendly: Documentation is visible when editing the component

Why not a simpler approach?

A common approach to ignore custom blocks is to return an empty module:

`ts
// This does NOT work with vite-plugin-vue-inspector
const vueDocsPlugin = {
name: 'vue-docs',
transform(_code, id) {
if (!/vue&type=doc/.test(id))
return
return export default ''
},
}
`

However, this doesn't solve the vite-plugin-vue-inspector issue. The inspector parses the SFC before this transform runs, and HTML-like strings inside blocks (e.g. ) cause parsing errors.

This plugin uses enforce: 'pre'` to run before the inspector and removes the content from the SFC source directly, preventing the error.

License

MIT