Vue Academy · Lesson

Publishing and Typing Vue Plugins

Package structure, TypeScript augmentation of ComponentCustomProperties, npm distribution.

Publishing and Typing Vue Plugins is a free Vue Academy lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Vue Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Packaging a Plugin for npm

To share a Vue plugin you publish it as an npm package. The package must declare the right dependencies, ship a proper build, include TypeScript types, and be published correctly. This lesson covers each step.

peerDependencies for Vue

List Vue as a peerDependency, not a regular dependency. This ensures the host app provides Vue, avoiding two copies of Vue in one bundle (which breaks reactivity).

{
  "name": "vue-toast-kit",
  "peerDependencies": {
    "vue": "^3.4.0"
  },
  "devDependencies": {
    "vue": "^3.4.0"
  }
}

Vite Library Mode

Build the package with Vite's library mode. Configure build.lib with the entry, name, and output formats (ES + UMD), and externalize Vue so it is not bundled.

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  build: {
    lib: {
      entry: 'src/index.ts',
      name: 'VueToastKit',
      fileName: 'index',
      formats: ['es', 'umd']
    }
  }
})

Externalizing Vue in rollupOptions

Mark vue as external and map it to a global for the UMD build, so the consumer's Vue is used.

build: {
  lib: { /* ... */ },
  rollupOptions: {
    external: ['vue'],
    output: {
      globals: { vue: 'Vue' }
    }
  }
}

Generating Type Declarations

Ship .d.ts files so consumers get autocomplete and type checking. Use vite-plugin-dts to emit declarations during the library build.

import dts from 'vite-plugin-dts'

export default defineConfig({
  plugins: [
    vue(),
    dts({ insertTypesEntry: true })
  ]
})

package.json exports Map

Point consumers at the right files with the exports field, exposing the ESM build and the type declarations. Set type: module for ESM-first packages.

{
  "type": "module",
  "main": "./dist/index.umd.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.umd.cjs"
    }
  }
}

Shipping Type Augmentation

If your plugin adds global properties (like this.$toast), include the ComponentCustomProperties augmentation in your published types so consumers' editors recognize it automatically.

// src/types.d.ts (included in the build)
import type { ToastService } from './toast'

declare module 'vue' {
  interface ComponentCustomProperties {
    $toast: ToastService
  }
}

export {}

The Public Entry Point

The src/index.ts entry should export the plugin as default plus any composables, keys, and types consumers need.

import ToastPlugin from './plugin'
export default ToastPlugin

export { useToast } from './composable'
export { toastKey } from './toast'
export type { ToastService, Toast } from './toast'

The files Field

Use the files field to publish only the build output, keeping the package small and excluding source and config.

{
  "files": ["dist"],
  "sideEffects": false
}

Publishing with Provenance

Publish to npm with provenance, which cryptographically links the package to the CI build and source commit. Run it from a trusted CI (GitHub Actions) with the right permissions.

# in CI (GitHub Actions)
npm publish --provenance --access public

# package.json can also set:
# "publishConfig": { "provenance": true }

Pre-Publish Checklist

Before publishing verify: Vue is a peer dep, the dist contains ESM + types, exports resolves correctly, the version is bumped, and a dry run looks right.

# inspect what will be published
npm publish --dry-run

# verify the tarball contents
npm pack

Quick Check

Test your understanding of publishing Vue plugins.

Recap

You learned publishing and typing plugins:

List Vue as a peerDependency to avoid duplicate Vue copies
Build with Vite library mode, externalizing Vue
Emit .d.ts (vite-plugin-dts) and ship type augmentation
Configure exports, files, and type: module
Publish with --provenance from trusted CI

Frequently asked questions

Is the “Publishing and Typing Vue Plugins” lesson free?

Yes — the full text of “Publishing and Typing Vue Plugins” is free to read here on the web, and the Vue Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Vue Academy course, upgrade to CoddyKit PRO.

What will I learn in “Publishing and Typing Vue Plugins”?

Package structure, TypeScript augmentation of ComponentCustomProperties, npm distribution. You practise Vue Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Vue Academy?

No prior experience is required. Vue Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Publishing and Typing Vue Plugins” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Vue Academy lesson?

Yes. Every Vue Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

Plugin Architecture and app.use()
Global Properties and provide/inject in Plugins
Notification and Toast Plugin Example
Publishing and Typing Vue Plugins

← Back to Vue Academy