@lwc/metadata

@lwc/metadata

This package can be used to collect metadata about a Lightning Web Component(LWC) by statically analysing html, js and css files of the component. In general, this information about the component is referred to as "component metadata". The metadata can be used for referential integrity checking, dependency analysis, code editor features like type ahead support for component attribute.

To learn more about the detailed design of this package and the schema of the metadata that is produced, refer the component metadata rfc.

Installation

npm install @lwc/metadata --save

APIs

collectBundleMetadata(config: BundleConfig)

Statically analyse the raw source of an LWC bundle and return gathered metadata. This API analyses bundle resources ending with a .html, .js and .css file extensions.

Note: This API is designed to work with the raw source as authored by an LWC developer and is expected to run before any tranformations applied by the @lwc/compiler.

import { collectBundleMetadata } from '@lwc/metadata';

const htmlSource = `
    <template>
        <h1>Hello World!</h1>
    </template>
`;

const jsSource = `
    import { LightningElement } from 'lwc';
    export default class MyComponent extends LightningElement {}
`;

const cssSource = `
    h1 {
        font-size: xx-large;
    }
`;

const metadata = collectBundleMetadata({
    type: 'platform',
    name: 'myComponent',
    namespace: 'c',
    namespaceMapping: { c: 'ns1' },
    files: [
        {
            fileName: 'c/myComponent/myComponent.html',
            source: htmlSource,
        },
        {
            fileName: 'c/myComponent/myComponent.js',
            source: jsSource,
        },
        {
            fileName: 'c/myComponent/myComponent.css',
            source: cssSource,
        },
    ],
});

Parameters:

• config (BundleConfig, required) - Represents information about the LWC bundle that needs to be analysed. The config also contains the raw source code for all files(.html, .js & .css) that make up the bundle.

type BundleType = 'internal' | 'platform';

interface BundleConfig {
    type: BundleType; // Represents whether the bundle was authored by salesforce or a customer
    name: string; // name of the bundle
    namespace: string; // namespace of the bundle
    namespaceMapping: NamespaceMapping; // namespaceMapping to be used to transform module references like 'c/button' to 'namespaceA/button'. This is useful when the given bundle will be part of a managed package.
    files: {
        fileName: string;
        source: string;
    }[]; // List of file name and source code for each file in utf-8 encoding
    enableKomaci?: boolean; // Advance feature meant to analyze data dependencies of given module. It is meant for internal usage.
}

Return value: A BundleMetadata representing the collected metadata about the LWC bundle.

interface BundleMetadata {
    version: string; // version of @lwc/metadata used to collect metadata
    moduleSpecifier: string; // Full canonical name in camel case
    name: string; // same as input name field
    namespace: string; // same as intput naemspace field
    entryFileName?: string; // main entry file of the bundle
    // A list of metadata objects for each file processed in the bundle
    // The order of file is same as order of 'files' in the input config
    files: (HTMLTemplateFile | ScriptFile | CSSFile)[];
    // All diagnostic issues discovered while collecting bundle metadata.
    diagnostics: CompilerDiagnostic[];
}

The schema used for @lwc/metadata package is well defined in TypeScript. Refer to the type definitions that are included in the package distribution. It can be viewed in an IDE that has TypeScript support.