@dumijs/vue-meta

Extracting the metadata of Vue components more effectively.

This project is heavily inspired by vue-component-meta, and reuses a significant amount of its code.

Install

pnpm i @dumijs/vue-meta

Usage

@dumijs/vue-meta uses TypeScript's TypeChecker for metadata extraction.

[!NOTE] When configuring tsconfig.json, set strictNullCheck to false

{
  "compilerOptions": {
    "strictNullChecks": false
  }
}

import { createProject } from '@dumijs/vue-meta';
import * as path from 'path';

const projectRoot = '<project-root>';
const project = createProject({
  rootPath: projectRoot,
  // If tsconfigPath is not set, tsconfig will be <rootPath>/tsconfig.json
  tsconfigPath: path.resolve(projectRoot, './tsconfig.json');
});

const entry = path.resolve(projectRoot, './src/index.ts');

const meta = project.service.getComponentLibraryMeta(entry);

meta.components['Button'];

// Reusable types, queried and referenced through `ref`
// (`ref` is the md5 value calculated from the name of the file where the type is located and its type name.)
meta.types;

After updating the file locally, use patchFiles to update the file in memory, and TypeChecker will recheck.

project.patchFiles([
  {
    action: 'add',
    fileName: '...',
    text: '...',
  },
  {
    update: 'add',
    fileName: '....',
    text: '....',
  },
]);

// Then you can get the new type metadata
const meta = project.service.getComponentLibraryMeta(entry);

API

project

createProject()

Create a meta checker for Vue project with rootPath

If no parameters are passed in, tsconfig.json in the current workspace will be read.

Type

export declare function createProject(rootPath?: string): Project;

Examples

import { createProject } from '@dumijs/vue-meta';
createProject();

Parameters

• rootPath string

Returns Project

createProject()

Create a meta checker for Vue project by options

Type

export declare function createProject(options: CheckerProjectOptions): Project;

Examples

import { createProject } from '@dumijs/vue-meta';
// Manually pass in the tsconfig.json path
createProject({
  // If neither rootPath nor tsconfigPath is set, rootPath will be process.cwd()
  rootPath: '<project-root>',
  // If tsconfigPath is not set, tsconfig will be <rootPath>/tsconfig.json
  tsconfigPath: '<project-root>/tsconfig.json',
  checkerOptions: {},
});

Parameters

• options CheckerProjectOptions

Returns Project

createProjectByJson()

Create component metadata checker through json configuration

Type

export declare function createProjectByJson(
  options: CheckerProjectJsonOptions,
): Project;

Parameters

• options CheckerProjectJsonOptions

Returns Project

options

MetaCheckerOptions

Checker Options

Type

export interface MetaCheckerOptions extends MetaCheckerSchemaOptions

Extends: MetaCheckerSchemaOptions

Properties

• disableGit boolean

  Prohibit obtaining git repo URL, git revision, and other information through git commands, the default is false

• disableSources boolean

  Disable production of source links, the default is false

• filterExposed boolean

  Whether to enable filtering for exposed attributes, the default is true.

  If true, only methods or properties identified by release tags like @public will be exposed in jsx

• filterGlobalProps boolean

  Whether to filter global props, the default is true

  If it is true, global props in vue, such as key and ref, will be filtered out

• forceUseTs boolean

• gitRemote string

  Default is "origin"

• gitRevision string

  https://git-scm.com/book/en/v2/Git-Tools-Revision-Selection

• printer ts.PrinterOptions

• sourceLinkTemplate string

  source link template, must be set when you set disableGit.

  A typical template looks like this: https://github.com/umijs/dumi/{gitRevision}/{path}#L{line}.

  The parser will replace the parts {gitRevision|path|line}

MetaCheckerSchemaOptions

Schema resolver options

Type

export interface MetaCheckerSchemaOptions

Properties

• disableExternalLinkAutoDectect boolean

  By default, this option is false, the resolver will automatically capture the MDN links contained in the comments of all declaration files under node_modules/typescript/lib. Users do not need to configure externalSymbolLinkMappings themselves.

  Of course, you can also overwrite the captured links through externalSymbolLinkMappings

• exclude string | RegExp | (string | RegExp)[] | ((name: string) => boolean)

  By default, type resolution in node_module will be abandoned.

• externalSymbolLinkMappings Record<string, Record<string, string>>

  The types/interfaces mapping method is provided as follows:

  {
    typescript: {
      Promise:
        'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise',
    },
  },

  For more complex mapping methods, please use unknownSymbolResolvers

• ignore (string | ((name: string, type: ts.Type, typeChecker: ts.TypeChecker) => boolean | void | undefined | null))[]

  A list of type names to be ignored in expending in schema. Can be functions to ignore types dynamically.

• ignoreTypeArgs boolean

  In addition to ignoring the type itself, whether to ignore the type parameters it carries. By default, the type parameters it carries will be parsed. For example, Promise<{ a: string }>, if you use optionexclude or ignore to ignore Promise, { a: string } will still be parsed by default.

• propertyResovlers PropertySchemaResolver<PropertyMeta>[]

  Property schema resolvers for some special props definition methods, such as vue-types

• unknownSymbolResolvers UnknownSymbolResolver[]

  unknownSymbol resolver

PropertySchemaResolver

property schema resolver

Type

export type PropertySchemaResolver<T extends ComponentItemMeta> = (
  originMeta: Partial<T>,
  options: {
    ts: typeof import('typescript/lib/tsserverlibrary');
    typeChecker: ts.TypeChecker;
    schemaOptions: MetaCheckerSchemaOptions;
    symbolNode: ts.Expression;
    prop: ts.Symbol;
    targetNode?: ts.Declaration;
    targetType?: ts.Type;
  },
) => Partial<T>;

References: ComponentItemMeta, MetaCheckerSchemaOptions

UnknownSymbolResolver

Type

export type UnknownSymbolResolver<
  T extends PropertyMetaSchema = PropertyMetaSchema,
> = (options: {
  ts: typeof import('typescript/lib/tsserverlibrary');
  typeChecker: ts.TypeChecker;
  targetSymbol: ts.Symbol;
  schemaOptions: MetaCheckerSchemaOptions;
  targetNode: ts.Declaration;
}) => Partial<T>;

References: PropertyMetaSchema, MetaCheckerSchemaOptions

project.service

TypeCheckService

Provide component metadata checker services

Type

export declare class TypeCheckService

Constructors

• (constructor)

  Constructs a new instance of the TypeCheckService class

Methods

• (constructor)

  Constructs a new instance of the TypeCheckService class

• close

  Close the Type checker service

• getComponentLibraryMeta

  Get component metadata through the entry file, this method will automatically filter vue components

• getComponentMeta

  Get metadata of single component If the component to be obtained is not a vue component, an error will be thrown

• getExported

  Get the export

• getExportNames

  only get value export

Supported JSDoc tags

[!NOTE] It is recommended to define events in props so that you can get complete JSDoc support

@description

Description of the property.

@default

When the prop option default uses as function, default will be ignored. In this case, you can use @default to override it.

defineComponent({
  props: {
    /**
     * @default {}
     */
    foo: {
      default() {
        return {};
      },
    },
  },
});

@component

This is used to distinguish between ordinary functions and function components.

Currently, there are two situations that cannot be automatically recognized as components:

/**
 * @component
 */
function InternalComponent(props: { a: string }) {
  return h('div', props.a);
}

/**
 * @component
 */
export const GenericComponent = defineComponent(
  <T>(props: { item: T }) => {
    return () => (<div>{item}</div>);
  },
);

It needs to be annotated with @component, otherwise it will be recognized as a function

Release related

@public

@deprecated

@experimental/@beta

@alpha

[!NOTE] These release tags cannot take effect in defineEmits

For methods on the component instance itself, use release tags like @public to expose

defineExpose({
  /**
   * @public
   */
  focus() {},
});

If you set filterExposed in MetaCheckerOptions to false, those release tags will become invalid.

The component instance of vue will not only expose the properties and methods exposed through expose, but also expose the props passed in from the outside.

@ignore/@internal

Properties marked with @ignore or @internal will not be checked.

Version control related

@version

@since

TODO

• [x] externalSymbolLinkMap support
• [x] resolve Functional component
• [ ] ~~resolve Vue class component~~