# custom-element-vuejs-integration

> Types for integrating custom elements into Vue.js projects

Latest version **1.4.0** (published 2025-01-20) · MIT license · 0 weekly downloads

## Install

```sh
npm install custom-element-vuejs-integration
pnpm add custom-element-vuejs-integration
yarn add custom-element-vuejs-integration
bun add custom-element-vuejs-integration
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 1.4.0 |
| Published | 2025-01-20 |
| First published | 2023-12-09 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 34.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 140 |
| Maintainers | breakstuff |
| Keywords | custom-elements, custom-elements-manifest, web-components, components, jsx, autocomplete, intellisense |

## Links

- npm: https://www.npmjs.com/package/custom-element-vuejs-integration
- Repository: https://github.com/break-stuff/cem-tools
- Homepage: https://github.com/break-stuff/cem-tools/tree/main/packages/vuejs-integration
- Issues: https://github.com/break-stuff/cem-tools/issues
- npm.io page: https://npm.io/package/custom-element-vuejs-integration

## Dependencies (1)

- [@prettier/sync](https://npm.io/package/@prettier/sync.md) ^0.5.2

## Recent versions

- 1.4.0 (latest) — 2025-01-20
- 1.3.3 — 2024-10-10
- 1.3.2 — 2024-07-24
- 1.3.1 — 2024-07-21
- 1.2.0 — 2024-05-20
- 1.1.0 — 2024-02-26
- 1.0.1 — 2024-01-21
- 1.0.0 — 2023-12-19
- 1.0.0-beta.7 — 2023-12-19
- 1.0.0-beta.6 — 2023-12-11
- 1.0.0-beta.5 — 2023-12-10
- 1.0.0-beta.4 — 2023-12-10
- 1.0.0-beta.3 — 2023-12-10
- 1.0.0-beta.2 — 2023-12-10
- 1.0.0-beta.1 — 2023-12-10
- … 1 more at https://npm.io/package/custom-element-vuejs-integration/versions

## README

# Custom Elements Vue.js Integration

This package is designed to generate types for your custom elements in a project using [Vue.js](https://vuejs.org/). These types will generate inline documentation, autocomplete, and type-safe validation for your custom elements in a Vue.js application.

> _***NOTE:*** This will generate types for both vue templates and JSX._

<!-- ![demo of autocomplete features for custom elements in a solidjs project](https://github.com/break-stuff/cem-tools/blob/main/demo/images/solid-js-integration/solid-js-integration.gif?raw=true) -->

## Usage

This package includes two ways to generate the custom data config file:

1. calling a function in your build pipeline
2. as a plugin for the [Custom Element Manifest Analyzer](https://custom-elements-manifest.open-wc.org/)

### Install

```bash
npm i -D custom-element-vuejs-integration
```

### Build Pipeline

```js
import { generateVuejsTypes } from "custom-element-vuejs-integration";
import manifest from "./path/to/custom-elements.json" assert { type: "json" };

const options = {
  outdir: "./",
  fileName: "my-library-vuejs.d.ts",
  globalTypePath: "./dist/components/index.js", // relative to `outdir`
};

generateVuejsTypes(manifest, options);
```

#### Update `tsconfig.json` with Local Reference

Now you can add a reference to the types in your `tsconfig.json`.

```json
{
  "compilerOptions": {
    "types": ["./my-library-vuejs"]
  }
}
```

### CEM Analyzer

#### Set-up

Ensure the following steps have been taken in your component library prior to using this plugin:

- Install and set up the [Custom Elements Manifest Analyzer](https://custom-elements-manifest.open-wc.org/analyzer/getting-started/)
- Create a [config file](https://custom-elements-manifest.open-wc.org/analyzer/config/#config-file)

#### Import

```js
// custom-elements-manifest.config.js

import { customElementVuejsPlugin } from "custom-element-vuejs-integration";

const options = {
  outdir: "./dist",
  fileName: "my-library-vuejs.d.ts",
  globalTypePath: "./components/index.js", // relative to `outdir`
};

export default {
  plugins: [customElementVuejsPlugin(options)],
};
```

#### Update `tsconfig.json` with Package Reference

Now you can add a reference to the types in your `tsconfig.json`.

```json
{
  "compilerOptions": {
    "types": ["my-library/my-library-vuejs"]
  }
}
```

## Configuring Your Vue.js Project

If you haven't configured your Vue.js project to work with custom element/web components, follow [the instructions here](https://vuejs.org/guide/extras/web-components.html#using-custom-elements-in-vue) based on your project type to ensure the components work correctly.

## Configuration

The configuration has the following optional parameters:

```ts
{
  /** Path to output directory */
  outdir?: string;
  /** File name for the types */
  fileName?: string | null;
  /** Class names of any components you would like to exclude from the types */
  exclude?: string[];
  /** Indicates if the component classes are a default export rather than a named export */
  defaultExport?: boolean;
  /** Used to get type reference for components from a single source */
  globalTypePath?: string;
  /** Used to get types from specific path for a given component */
  componentTypePath?: (name: string, tag?: string) => string;
  /** The property form your CEM component object to display your types */
  typesSrc?: string;
  /** Used to add global element props to all component types */
  globalEvents?: string;
  /** Hides logs produced by the plugin */
  hideLogs?: boolean;
  /** Prevents plugin from executing */
  skip?: boolean;
  /** Adds a prefix to tag name references */
  prefix?: string;
  /** Adds a suffix to tag name references */
  suffix?: string;
}
```

## Configuration

### Output

You can configure the destination and the file name of the generated type file using the `outdir` and `fileName` configuration.

```ts
{
  /** Path to output directory */
  outdir: 'dist',
  /** File name for the types */
  fileName: 'vuejs-integration.d.ts'
}
```

### Default Exports

If you component class does not provide a named export and is the default export, be sure to set `defaultExport` to `true`. This will endure the import for the class gets resolved correctly.

### Types

If your components were built using TypeScript, the types should automatically be used when you reference the corresponding module.

> _***NOTE:*** All type paths should be relative to the location specified in the `outdir` option._

If your types are rolled up into a single type declaration file, you can set the `globalTypePath` option to the location of that file.

```ts
{
  globalTypePath: ".dist/components/index.js";
}
```

If each of the component type definitions are split out by each component, you can use the `componentTypePath` to reference individual component paths.

```ts
{
  componentTypePath: (name, tag) => `./components/${tag}/${name}.js`;
}
```

#### Custom Types

If you have custom types configured in your Custom Elements Manifest and do not have types or are unable to use them, you can specify the property name of that type using the `typeSrc` option.

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