vitepress-plugin-package-managers

Display package manager commands with synced, persistent tabs for VitePress. Users pick their package manager once — the choice is remembered across pages and browser sessions.

Inspired by starlight-package-managers.

Install

npm install vitepress-plugin-package-managers

Setup

1. Register the markdown plugin

// .vitepress/config.mts
import { packageManagersMarkdownPlugin } from "vitepress-plugin-package-managers";

export default defineConfig({
  markdown: {
    config(md) {
      md.use(packageManagersMarkdownPlugin);
    },
  },
});

2. Register the Vue components

// .vitepress/theme/index.ts
import { enhanceAppWithPackageManagers } from "vitepress-plugin-package-managers/client";

export default {
  extends: DefaultTheme,
  enhanceApp({ app }) {
    enhanceAppWithPackageManagers(app);
  },
};

With icons

Icons are opt-in for tree-shaking. Import the preset and pass it:

import { enhanceAppWithPackageManagers } from "vitepress-plugin-package-managers/client";
import { icons } from "vitepress-plugin-package-managers/icons";

enhanceAppWithPackageManagers(app, { icons });

Usage

Markdown syntax

The simplest way — use :::pm-<type> containers directly in .md files:

::: pm-add gramio
:::

::: pm-add -D @gramio/types
:::

::: pm-run dev
:::

::: pm-install
:::

::: pm-create gramio
:::

::: pm-dlx gramio
:::

::: pm-remove gramio
:::

Vue component

For more control, use the <PackageManagers> component:

<PackageManagers pkg="gramio" />

<PackageManagers pkg="@gramio/types" dev />

<PackageManagers type="run" pkg="dev" />

<PackageManagers type="install" />

<PackageManagers type="create" pkg="gramio" />

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | pkg | string | — | Package name | | type | "add" \| "create" \| "dlx" \| "exec" \| "install" \| "run" \| "remove" | "add" | Command type | | dev | boolean | false | Add as dev dependency (-D / -d) | | args | string | — | Extra arguments appended to the command | | prefix | string | — | Prefix prepended to the command (e.g. sudo) | | comment | string | — | Comment line above the command. {PKG} is replaced with the manager name | | jsr | string | — | JSR package specifier (see JSR support) | | pkgManagers | PackageManager[] | ["npm", "yarn", "pnpm", "bun"] | Which tabs to show |

JSR support

Pass the jsr prop to generate correct commands for every package manager:

<PackageManagers jsr="@gramio/bot" />

Generates:

| Manager | Command | |---------|---------| | npm | npx jsr add @gramio/bot | | yarn | yarn dlx jsr add @gramio/bot | | pnpm | pnpm dlx jsr add @gramio/bot | | bun | bunx jsr add @gramio/bot | | deno | deno add jsr:@gramio/bot |

Navbar switcher

PackageManagerSwitch is a dropdown you can put in the navbar so users can change their preference from anywhere:

<!-- .vitepress/theme/Layout.vue -->
<script setup>
import DefaultTheme from "vitepress/theme";
import { PackageManagerSwitch } from "vitepress-plugin-package-managers/client";
</script>

<template>
  <DefaultTheme.Layout>
    <template #nav-bar-content-after>
      <PackageManagerSwitch />
    </template>
  </DefaultTheme.Layout>
</template>

Persistence

All components share state through three mechanisms:

1. localStorage — persists the choice across pages and sessions
2. CustomEvent — syncs all instances on the same page instantly
3. storage event — syncs across browser tabs

Supported package managers

npm, yarn, pnpm, bun, deno, ni

Default: ["npm", "yarn", "pnpm", "bun"]

Icons

Icons are not bundled by default — you opt in for tree-shaking.

// Use all built-in icons (npm, yarn, pnpm, bun, deno)
import { icons } from "vitepress-plugin-package-managers/icons";
enhanceAppWithPackageManagers(app, { icons });

Cherry-pick only what you need:

import { npm, bun } from "vitepress-plugin-package-managers/icons";
enhanceAppWithPackageManagers(app, { icons: { npm, bun } });

Use your own SVG or disable an icon:

import { icons } from "vitepress-plugin-package-managers/icons";
enhanceAppWithPackageManagers(app, {
  icons: {
    ...icons,
    bun: '<svg>...</svg>',  // custom SVG
    npm: false,              // hide icon
  }
});

Configuring defaults

Pass options to the markdown plugin to change the default set of package managers:

md.use(packageManagersMarkdownPlugin, {
  pkgManagers: ["npm", "pnpm", "bun"],
});

Or per-instance via the pkgManagers prop:

<PackageManagers pkg="gramio" :pkg-managers='["npm", "bun", "deno"]' />

License

MIT