vue-component-meta

vue-component-meta

vue-component-meta allows you to extract the meta-data like props, slots, events, etc from your components via static code analysis. You can even generate description for your props from your source code. This helps document your components via automation. Please refer to the reference section for references.

Guide 📗

First of all, you need to create a component meta checker using createChecker:

import * as url from 'url'
import path from 'path'

import type { MetaCheckerOptions } from 'vue-component-meta'
import { createChecker } from 'vue-component-meta'

const __dirname = url.fileURLToPath(new URL('.', import.meta.url))

const checkerOptions: MetaCheckerOptions = {
  forceUseTs: true,
  schema: { ignore: ['MyIgnoredNestedProps'] },
  printer: { newLine: 1 },
}

const tsconfigChecker = createChecker(
  // Write your tsconfig path
  path.join(__dirname, 'path-to-tsconfig'),
  checkerOptions,
)

Now, you can extract the component meta using getComponentMeta method of checker:

import * as url from 'url'
import path from 'path'

const __dirname = url.fileURLToPath(new URL('.', import.meta.url))

const componentPath = path.join(__dirname, 'path-to-component');
const meta = checker.getComponentMeta(componentPath);

This meta contains really useful stuff like component props, slots, events and more. You can refer to its type definition for more details.

Extracting prop meta

vue-component-meta will automatically extract the prop details like its name, default value, is required or not, etc. Additionally, you can even write prop description in source code via JSDoc comment for that prop.

/**
 * Hide/Show alert based on v-model value
 */
modelValue: {
  type: Boolean,
  default: null,
},

When you extract the component meta and extract the description property of that prop it will be "Hide/Show alert based on v-model value" 😍

Warning

Do note that meta.props will be array of props so you can't access it via meta.props.<prop-name>. Moreover, meta.props will also contain some global prop which you can identify via prop.global property.

You can use it to document your component as you build your project without writing additional documentation.

Pitfalls 👀

As vue-component-meta uses static code analysis, it can't extract the dynamic prop definition.

default value

vue-component-meta won't be able to extract default value for prop as props can't be analyzed.

props: {
  // Props definition by function execution
  ...useLayerProps({
    color: {
      default: 'primary',
    },
    variant: {
      default: 'light',
    },
  }),
}

In this scenario, to get the correct default value you can let vue-component-meta know it by writing them explicitly:

props: {
  // let vue-component-meta found it
  color: { default: 'primary' },
  variant: { default: 'light' },

  // Props definition by function execution
  ...useLayerProps({
    color: {
      default: 'primary',
    },
    variant: {
      default: 'light',
    },
  }),
}

description

Same as above scenario you might have issue with description not generating when prop definition is dynamic. In this case writing prop description can be tricky.

When it's function execution, write prop description in function definition:

export const useLayerProp = (...) => {
  const props = {
       /**
        * Layer variant
        */
       variant: {
         type: String,
         default: 'text',
       },
  }

  export { props }
}

required

For generating the correct required value for props like below:

// @/composables/useProps.ts
export const disabled = {
  type: Boolean,
  default: false,
}

import { disabled } from '@/composables/useProps'

export default defineComponent({
  props: {
    disabled,
  },
})

You need to add as const to variable definition:

 export const disabled = {
   type: Boolean,
   default: false,
- }
+ } as const

Used by 🎉

• Anu UI library uses vue-component-meta to generate components' API via automation.

Reference 📚

• tests
• Anu's components' API automation
• Discord chat for dynamic usage

Sponsors ❤️

Changelog

2.2.4 ^official, 2.2.5 ^insiders (2025-02-22)

Features

• feat(language-service): map sfc compiler errors outside the template inner content (#5045) - Thanks to @KazariEX!
• feat(language-core): introduce options to control type inference of $attrs, $el, $refs and $slots (#5135) - Thanks to @KazariEX!
• feat(language-core): enhance single root nodes collection (#4819) - Thanks to @KazariEX!

Bug Fixes

• fix(language-core): move generateSfcBlockSection to the end to fix missing comma errors (#5184) - Thanks to @zhiyuanzmj!
• fix(language-core): handle edge case of default slot name mismatch - Thanks to @KazariEX!
• fix(language-core): combine dollar variable keys from the upper level interface - Thanks to @KazariEX!
• fix(language-core): hoist the variables that may cause TS4081 (#5192) - Thanks to @KazariEX!
• fix(language-core): adjust regex match for @vue-generic to improve offset calculation (#5193) - Thanks to @Gehbt!
• fix(language-core): correct codegen of native element refs - Thanks to @KazariEX!
• fix(language-core): ignore latex block content (#5151) - Thanks to @KazariEX!
• fix(language-core): do not emit undefined for model with default value (#5198) - Thanks to @RylanBueckert-Broadsign!
• fix(language-service): typescript-semantic renaming first in style blocks (#4685) - Thanks to @KazariEX!
• fix(typescript-plugin): prevent removed components from appearing in the completion list - Thanks to @KazariEX!

Other Changes

• refactor(language-core): drop invalid v-scope implemention - Thanks to @KazariEX!
• refactor(language-core): improve type declaration of v-for - Thanks to @KazariEX!
• test: enable declaration to track more errors - Thanks to @KazariEX!
• refactor(language-core): remove semantic highlight of style module names - Thanks to @KazariEX!
• chore(language-core): add docs for @vue-expect-error support (#5176) - Thanks to @machty!
• ci: upload extension as artifact for each commit - Thanks to @KazariEX!