Component metadata

A Component's metadata consists of the aspects it uses and the information each of them generates. Metadata is re-calculated during development and persisted when a component is versioned.

A component's metadata helps you understand how a component is to be used and maintained. What's its package name, which env it uses, which peer dependencies it requires, and so on. In addition to that, metadata can be used by aspects, internally, or even by external tools. For example, Bit.cloud uses component labels, provided by teambit.docs/docs, to search and filter components.

Head over to your component's 'aspect' page in its workspace or scope, to inspect its full metadata. See an example, here.

Run the following to inspect a component in the terminal:

bit aspect get COMPONENT_ID [--json]
Copied

For example:

bit import teambit.base-react/navigation/link
bit aspect get teambit.base-react/navigation/link
Copied

The output contains a list of aspects used by the component and their corresponding data (in the component's current state). The following snippet shows the teambit.docs/docs aspect metadata as an example:

"teambit.docs/docs": {
    "name": "teambit.docs/docs",
    "data": {
      "doc": {
        "filePath": "link.docs.mdx",
        "props": [
          {
            "name": "description",
            "value": "A universal Link component."
          },
        ]
      }
    }
  },
Copied

To get a shorter list of the component's most critical metadata, like dependencies, package name, and more, use the bit show command.

You can retrieve a component's current metadata (its latest version or its locally modified state) using one of the following APIs:

• Workspace: workspace.get(componentId)
• Scope: scope.get(componentId)
• Component (host agnostic): component.getHost().get(componentId)

For example:

import { Workspace, WorkspaceAspect } from '@teambit/workspace';
// ...
export class MetadataRetrieval {
  // ...
  static dependencies = [WorkspaceAspect];
  static async provider([workspace]: [Workspace]) {
    // ...
    const component = await this.workspace.get(componentId);
    /* retrieve the custom metadata provided by this aspect */
    const componentCustomMetadata = component.state.aspects.get(MetadataRetrievalAspect.id).data;
    return new CustomMetadataMain();
  }
}
Copied

Run the following to import a demo aspect that retrieves its own metadata:

bit import learnbit.extending-bit/metadata/custom-metadata
Copied

You can add metadata to a component, using the workspace.componentOnLoad API, or indirectly, via a build task's return metadata property.

This option adds the data during development and persists it during tags and snaps. The data will be listed in the component's metadata, directly under the aspect Id.

import { MainRuntime } from '@teambit/cli';
import { Workspace, WorkspaceAspect } from '@teambit/workspace';
// ...

export class CustomMetadataMain {
  static dependencies = [WorkspaceAspect];
  static runtime = MainRuntime;
  static async provider([workspace]: [Workspace]) {
    workspace.onComponentLoad(async (component) => {
      return {
        newProp: 'new-prop',
      };
    });
}

// ...
Copied

Run the following to import a demo aspect that adds its own metadata:

bit import learnbit.extending-bit/metadata/custom-metadata
Copied

This option adds metadata using a build task. The data will be listed under the aspect id, nested under the builder aspect.

For example:

// ...
export class LintTask implements BuildTask {
  // ...
  async execute(context: BuildContext): Promise<BuiltTaskResult> {
    // ...
    const results = await linter.lint(context);
    const componentsResults = results.results.map((lintResult): ComponentResult => {
      return {
        component: lintResult.component,
        metadata: {
          output: lintResult.output,
          results: lintResult.results,
        },
        errors: [],
      };
    });
    return {
      componentsResults,
    };
  }
}
Copied

To learn how to add metadata during build see 'Implement a build task'.