Registry / web-framework / vue-component-meta

vue-component-meta

library3.2.7jsnpmunverified

vue-component-meta is a library designed to statically extract rich metadata such as props, events, slots, and exposed properties from Vue Single File Components (SFCs). It is a core part of the official Vue Language Tools and Volar ecosystem, leveraging the TypeScript compiler for deep type inference. The current stable version is 3.2.7, with frequent patch releases indicating an active development cadence, often several times a month. This tool is invaluable for scenarios like auto-generating comprehensive component documentation (e.g., for Storybook), displaying component APIs in development tools, or for advanced static analysis of Vue projects. Its primary differentiator is its deep integration with TypeScript and the Vue Language Server, ensuring highly accurate and up-to-date metadata extraction that reflects modern Vue 3 features like `defineSlots` and `defineExpose`, which alternative tools like `vue-docgen-api` have struggled to keep up with.

web-framework

npm install vue-component-meta

github ↗package ↗

INSTALL

IMPORT

SIG · VUE-COMPONENT-META

vue-component-meta

web-frameworkjavascriptv3.2.7

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createChecker

✓ import { createChecker } from 'vue-component-meta';

✗ const createChecker = require('vue-component-meta');

Primary entry point for creating a checker from a tsconfig.json file. This package is ESM-first.

createCheckerByJson

✓ import { createCheckerByJson } from 'vue-component-meta';

✗ const createCheckerByJson = require('vue-component-meta');

Alternative entry point for creating a checker with an inline JSON configuration, useful for programmatic setups without a physical tsconfig.json.

ComponentMeta

✓ import type { ComponentMeta } from 'vue-component-meta';

✗ import { ComponentMeta } from 'vue-component-meta';

Use 'import type' for importing the TypeScript interface, as it's not a runtime value. This helps tree-shaking and avoids potential bundling issues.

This quickstart demonstrates how to create a metadata checker from a `tsconfig.json` file and extract comprehensive metadata for a Vue component, including props, events, slots, and exposed properties.

import { createChecker } from 'vue-component-meta'; import path from 'path'; import process from 'process'; // Determine the project root from the current working directory const projectRoot = process.cwd(); const tsconfigPath = path.resolve(projectRoot, 'tsconfig.json'); try { // Ensure TypeScript is installed in your project as a peer dependency. // It's crucial for the checker to function correctly. // This example assumes a tsconfig.json exists at the project root. const checker = createChecker(tsconfigPath, { schema: true, // Enable schema parsing for detailed type structures }); // Replace with the actual path to your Vue component const componentPath = path.resolve(projectRoot, 'src/components/MyComponent.vue'); // Get metadata for the default export of the component const meta = checker.getComponentMeta(componentPath); console.log('Component Name:', meta.name); console.log('Component Description:', meta.description); console.log('Props:', meta.props.map(p => ({ name: p.name, type: p.type, required: p.required }))); console.log('Events:', meta.events.map(e => ({ name: e.name, type: e.type }))); console.log('Slots:', meta.slots.map(s => ({ name: s.name, type: s.type }))); console.log('Exposed:', meta.exposed.map(ex => ({ name: ex.name, type: ex.type }))); // You can also get all export names from a file const exportNames = checker.getExportNames(componentPath); console.log('Export Names:', exportNames); } catch (error) { console.error('Failed to extract component metadata:', error.message); if (error.message.includes('tsconfig.json')) { console.error('Ensure your tsconfig.json path is correct and accessible.'); } else if (error.message.includes('typescript')) { console.error('Ensure TypeScript is installed as a dependency in your project: `npm install typescript`.'); } }

Debug

Known issues

gotchavue-component-meta requires 'typescript' as a peer dependency. You must install TypeScript in your project separately (e.g., `npm install typescript`) to ensure the checker can function correctly and use the expected TypeScript version. Mismatched or missing TypeScript installations can lead to unexpected errors or incorrect metadata extraction.

fix

Ensure `typescript` is installed in your project: `npm install typescript` (or `yarn add typescript`). For monorepos, make sure the `typescript` version is resolvable and compatible with the project where `vue-component-meta` is used.

affects: >=3.0.0

gotchaWhen initializing `createChecker`, providing an incorrect or inaccessible `tsconfig.json` path will prevent metadata extraction. For Vue SFCs, your `tsconfig.json` also needs appropriate `vueCompilerOptions` for correct type inference within `<script setup>` and templates.

fix

Verify that the `tsconfigPath` passed to `createChecker` is an absolute path to a valid `tsconfig.json`. Ensure your `tsconfig.json` includes `"vueCompilerOptions": { "target": "esnext" }` (or similar) and correctly includes your Vue files.

affects: >=3.0.0

gotchaThis library may have limitations with barrel files (re-exporting components from an `index.ts` or `index.js`). In some cases, `vue-component-meta` might silently skip adding metadata for components re-exported through barrel files, leading to incomplete documentation.

fix

If you encounter missing metadata for components organized in barrel files, try directly importing the component from its source file path instead of the barrel export. Monitor GitHub issues for updates on barrel file support.

affects: >=3.0.0

gotchaThe `schema` option in `MetaCheckerOptions` (defaulting to `false`) controls whether detailed schema structures of types are parsed. Enabling it (`schema: true`) provides richer type information but might increase processing time for large projects. It can also be configured to `ignore` specific types.

fix

Consider the trade-off between detail and performance. For basic documentation, `schema: false` might suffice. For deep type analysis, set `schema: true`. If performance is an issue with schema enabled, use the `ignore` option to exclude common or complex types like `HTMLElement` or internal utility types.

affects: >=3.0.0

Errors

Common errors & fixes

Error: Could not find 'tsconfig.json' at /path/to/project/tsconfig.json

The provided path to tsconfig.json is incorrect or the file does not exist.

fix

Double-check the `tsconfigPath` argument passed to `createChecker` to ensure it's an absolute and correct path to your project's `tsconfig.json`.

Failed to extract component metadata: Cannot read properties of undefined (reading 'getComponentMeta')

This usually indicates an issue with checker initialization, possibly due to a missing TypeScript installation or a severely malformed tsconfig.json that prevents the checker from being created successfully.

fix

Verify that `typescript` is installed as a dependency (`npm install typescript`) and that your `tsconfig.json` is syntactically correct and includes valid configurations, especially for Vue language features.

No exports found for component at /path/to/MyComponent.vue

The specified component file does not have a default export, or the `exportName` argument to `getComponentMeta` is incorrect for a named export.

fix

Ensure your Vue component has a `default` export (which is common for SFCs). If it's a named export, pass the correct `exportName` string to `checker.getComponentMeta(filePath, 'MyNamedExport')`.

Upgrade

Version history

3.2.7latest on npm

Audit

Dependencies

typescriptrequiredRequired as a peer dependency for type inference and component metadata extraction.

Agent activity

5 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/vuejs/language-tools ↗

packagehttps://www.npmjs.com/package/vue-component-meta ↗