@wc-toolkit/vuejs-types

WC Toolkit Custom Element VueJS Types Generator

This package generates Vue-specific TypeScript declaration files for your Custom Elements so consuming Vue projects get inline documentation, autocomplete, and type-safe validation when using your components in templates.

Types are generated from a Custom Elements Manifest (CEM) and include documentation for:

• Custom elements (types + docs)
• Attributes & properties (types + docs)
• Events (strongly typed when enabled)
• Methods (docs)
• Slots (docs)
• CSS custom properties & states (docs)

Usage

Three primary ways to generate types:

1. Programmatically, from a build script
2. As a plugin for the Custom Elements Manifest Analyzer
3. As a plugin for @wc-toolkit/cem-generator

Install

npm i -D @wc-toolkit/vuejs-types

Build pipeline

import { generateVuejsTypes, VuejsTypesOptions } from "@wc-toolkit/vuejs-types";
import manifest from "./path/to/custom-elements.json";

const options: VuejsTypesOptions = {
  /* see Configuration Options below */
};

generateVuejsTypes(manifest, options);

Run the script as part of your build:

node scripts/generate-types.js

CEM Analyzer plugin

// custom-elements-manifest.config.js
import { vuejsTypesPlugin } from "@wc-toolkit/vuejs-types";

export default {
  plugins: [
    vuejsTypesPlugin({
      outdir: "./dist/types",
      fileName: "custom-elements.vue.d.ts",
    }),
  ],
};

cem-generator Plugin

import { generateCem } from "@wc-toolkit/cem-generator";
import { vuejsTypesGeneratorPlugin } from "@wc-toolkit/vuejs-types";

generateCem({
  plugins: [vuejsTypesGeneratorPlugin({ outdir: "./dist/types" })],
});

Implementation / Integrating generated types

There are two common ways consumers can include the generated types in their Vue projects.

Option 1: tsconfig

Add the generated types to tsconfig.json so the compiler picks them up automatically:

{
  "compilerOptions": {
    "types": ["path/to/custom-elements.vue.d.ts"]
  }
}

Option 2: Small module file

Create a tiny module under src/ to ensure the file is part of the TS program (recommended for libraries):

// src/custom-elements.d.ts
import "../dist/types/custom-elements.vue.d.ts";
export {};

Vue compiler notes

• For Vite + Vue, add compilerOptions.isCustomElement so the template compiler treats your custom tags as native custom elements.
• Ensure the generated .d.ts is included in the consuming project's TS program (tsconfig include or the module file approach above).

Configuration Options

The Vue generator accepts a VuejsTypesOptions object to customize output.

Common options

Type source & imports

Template checking behavior

Docs & troubleshooting

See src/types.ts for the authoritative option definitions.

Example complete configuration

import { generateVuejsTypes } from "@wc-toolkit/vuejs-types";
import manifest from "./custom-elements.json";

generateVuejsTypes(manifest, {
  fileName: "custom-elements.vue.d.ts",
  outdir: "./dist/types",
  stronglyTypedEvents: true,
  useCemTypes: true,
  tagFormatter: (tag) => tag.toLowerCase(),
});

Troubleshooting

• No editor completions: confirm the consuming project's TS program includes the generated .d.ts (module file or tsconfig types/include).
• No hover docs on the tag: ensure your CEM includes a component description (it is emitted as JSDoc on the GlobalComponents entry).
• Event names clobbered by native events: avoid reusing native DOM event names for custom events.

Contributing

See CONTRIBUTING.md for developer instructions and guidance for automated agents.