# vitepress-tuck

> Enhance vitepress configuration, provide plugins capability.

Latest version **0.12.2** (published 2026-09-07) · MIT license · 0 weekly downloads

## Install

```sh
npm install vitepress-tuck
pnpm add vitepress-tuck
yarn add vitepress-tuck
bun add vitepress-tuck
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.12.2 |
| Published | 2026-09-07 |
| First published | 2026-06-05 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Dependencies | 2 |
| Unpacked size | 26.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 3 |
| Author | pengzhanbo <q942450674@outlook.com> (https://github.com/pengzhanbo/) |
| Maintainers | pengzhanbo |
| Keywords | vitepress, vitepress-plugin |

## Links

- npm: https://www.npmjs.com/package/vitepress-tuck
- Repository: https://github.com/pengzhanbo/vitepress-tuck
- Homepage: https://tuck.pengzhanbo.cn/
- Issues: https://github.com/pengzhanbo/vitepress-tuck/issues
- npm.io page: https://npm.io/package/vitepress-tuck

## Dependencies (2)

- [@pengzhanbo/utils](https://npm.io/package/@pengzhanbo/utils.md) ^3.11.0
- [unplugin-vue-components](https://npm.io/package/unplugin-vue-components.md) ^32.1.0

## Alternatives

- [raw-loader](https://npm.io/package/raw-loader.md) — 4.3M weekly downloads
- [plop](https://npm.io/package/plop.md) — 1.4M weekly downloads
- [webpack-deadcode-plugin](https://npm.io/package/webpack-deadcode-plugin.md) — 80.3K weekly downloads
- [@storybook/preact-vite](https://npm.io/package/@storybook/preact-vite.md) — 54.2K weekly downloads
- [vite-plugin-transform](https://npm.io/package/vite-plugin-transform.md) — 2.4K weekly downloads

## Recent versions

- 0.12.2 (latest) — 2026-09-07
- 0.12.1 — 2026-08-31
- 0.12.0 — 2026-08-08
- 0.11.1 — 2026-07-27
- 0.11.0 — 2026-07-08
- 0.10.0 — 2026-07-04
- 0.9.0 — 2026-07-02
- 0.8.0 — 2026-06-30
- 0.7.0 — 2026-06-27
- 0.6.0 — 2026-06-26
- 0.5.0 — 2026-06-24
- 0.4.0 — 2026-06-22
- 0.3.0 — 2026-06-14
- 0.2.0 — 2026-06-07
- 0.1.1 — 2026-06-05
- … 1 more at https://npm.io/package/vitepress-tuck/versions

## README

# vitepress-tuck

Enhance vitepress configuration and provide plugin development capabilities.

> [!NOTE]
> vitepress itself does not provide complete plugin development capabilities.
> Some existing slightly complex plugins often need to be configured in both the `markdown` and `vite` sections of the configuration file.
> The process of integrating plugins in vitepress for users is scattered and difficult to maintain.
>
> `tuck` provides vitepress with simple, flexible, and low-barrier plugin development capabilities:
>
> - Developers can directly develop plugins using `definePlugin`;
> - Users only need to add plugins in the `plugins` configuration.

## Install

```bash
# npm
npm install vitepress vitepress-tuck

# pnpm
pnpm add vitepress vitepress-tuck

# yarn
yarn add vitepress vitepress-tuck
```

## Using tuck in vitepress

Replace `defineConfig` from `vitepress` with `defineConfig` from `vitepress-tuck`

```ts
// .vitepress/config.ts
import { defineConfig } from 'vitepress-tuck'

export default defineConfig({
  plugins: [
    // Add plugins here
  ],
  // Other vitepress configuration items
})
```

In the client configuration file, import `virtual:enhance-app` to automatically inject the plugin's client code:

```ts
// .vitepress/theme/index.ts
import type { Theme } from 'vitepress'
import enhanceApp from 'virtual:enhance-app'
import DefaultTheme from 'vitepress/theme'

export default {
  extends: DefaultTheme,
  enhanceApp(ctx) {
    enhanceApp(ctx)
  },
} satisfies Theme
```

## Plugin Development

Develop plugins using `definePlugin`.

```ts
// Plugin development
import { definePlugin } from 'vitepress-tuck'

export default definePlugin((options?: MyPluginOptions) => ({
  name: 'vitepress-plugin-my-plugin',
  // Client configuration of the plugin, used to inject into the client config file
  client: {
    imports: [], // Modules that the client needs to import, e.g., style files
    enhance: 'enhanceAppWithMyPlugin', // Named export of the client enhancement function
  },
  markdown: {
    config: (md) => {
      // Configure markdown plugin here
      md.use(myMarkdownPlugin, options?.markdownOptions)
    }
  },
  vite: {
    // Configure vite here
    plugins: [myVitePlugin(options?.viteOptions)]
  },
  // Other vitepress related hooks
  buildEnd: () => {},
  transformHead: () => {},
  transformHtml: () => {},
  transformPageData: () => {},
  postRender: () => {},
}))
```

When a plugin needs to provide components or other client code:

Use the `client` field in the `exports` of `package.json` to export client code:

```json
{
  "exports": {
    ".": "./node/index.js",
    "./client": "./client/index.js"
  }
}
```

In `./client/index.js`, export a named function with the same name as `client.enhance`:

```ts
// client/index.js
export function enhanceAppWithMyPlugin({ app }: EnhanceAppContext) {
  // Add plugin's client code here
  app.component('MyComponent', MyComponent)
}
```

`vitepress-tuck` will check the `client` configuration and automatically inject the code into `virtual:enhance-app`.

When a plugin provides Vue components that should be auto-imported, declare them via the `componentResolver` field.
The simplest form is an array of component names — they will be resolved from `<plugin-name>/client`:

```ts
import { definePlugin } from 'vitepress-tuck'

export default definePlugin(() => ({
  name: 'vitepress-plugin-my-plugin',
  // Components listed here are auto-imported from 'vitepress-plugin-my-plugin/client'
  componentResolver: ['MyComponent', 'OtherComponent'],
  // ...other config
}))
```

For more advanced use cases, you can also pass a custom `ComponentResolver` object from `unplugin-vue-components`:

```ts
import type { ComponentResolver } from 'unplugin-vue-components'
import { definePlugin } from 'vitepress-tuck'

const myResolver: ComponentResolver = {
  type: 'component',
  resolve: (name) => {
    if (name.startsWith('My')) {
      return { name, from: 'vitepress-plugin-my-plugin/client' }
    }
  },
}

export default definePlugin(() => ({
  name: 'vitepress-plugin-my-plugin',
  componentResolver: myResolver,
  // ...other config
}))
```

## Auto Components

`vitepress-tuck` integrates [`unplugin-vue-components`](https://github.com/unplugin/unplugin-vue-components) as
a built-in plugin, enabling automatic on-demand component importing for `.vue` and `.md` files.
You no longer need to manually import and register components.

By default, the built-in plugin scans `.vue` and `.md` files and generates type declarations
at `node_modules/.vite/components.d.ts`. You can customize the behavior via the `components` option:

```ts
// .vitepress/config.ts
import { defineConfig } from 'vitepress-tuck'

export default defineConfig({
  components: {
    // Any unplugin-vue-components options, e.g.:
    dirs: ['src/components'],
    directoryAsNamespace: true,
  },
  plugins: [],
})
```

When a plugin provides Vue components, it can declare them via the `componentResolver` field so that they
are automatically resolved by `unplugin-vue-components` — see [Plugin Development](#plugin-development).

---
_Source: https://npm.io/package/vitepress-tuck · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._