CLI hooks

Learn more about CLI hooks to add custom component properties.

CLI hooks allow you to run custom scripts on scans before the final result is sent to the backend. This offers an interface to process the component data and add custom component properties.

Scanning with a hook script

You can place your hook script in a preferred directory/folder. Once your script is ready, you scan your repository using the --hook-script command line argument.

npm

npx @omlet/cli analyze --hook-script ./path/to/hook-script.js

yarn

yarn dlx @omlet/cli analyze --hook-script ./path/to/hook-script.js

pnpm

pnpm dlx @omlet/cli analyze --hook-script ./path/to/hook-script.js

afterScan hook

Currently, afterScan is the only hook supported by Omlet CLI. This hook is executed after a scan is completed successfully.

Here is a sample hook script uses the afterScan hook:

hook-script.js

module.exports = {
    async afterScan(components) {
        for (const component of components) {
            component.setMetadata("hasStories", await hasStories(component.filePath));
            component.setMetadata("hasTests", await hasTests(component.filePath));
        }
    }
}

If you have the @omlet/cli package installed as a dependency, the @type annotation will enable auto-complete features and inline documentation for functions and components.

The setMetadata function can add properties to components with string, number, date or boolean values, such as:

• Owner: The code owner information in the CODEOWNERS file or any custom source. i.e. @acme/design-system, @acme/backoffice, @acme/marketplace

• Has stories: True or false depending on whether Storybook stories exist for a given component

• # of props: Number of props of each individual component

Here are a few things to know about the afterScan hook:

• afterScan hook can be defined both as an async or sync function.

• The data passed to the hook is read-only, except the metadata that is editable with the setMetadata function.

• You can use npm packages as long as they're available in the Node.js runtime.

Component object properties

Here are the properties of the Componentobject provided by the afterScan hook:

Property	Type	Description
id	String	Unique identifier for the component.
name	String	Name of the component as exported in the source code.
createdAt	Date	Creation date of the component, extracted from the git history. Optional.
updatedAt	Date	Last updated date of the component, extracted from the git history. Optional.
packageName	String	Package name the component belongs to.
filePath	String	File path to the component within the repository.
props	Array of objects [{ name: String, defaultValue: String }, ...]	List of props of the component, including name and optional default value.
htmlElementsUsed	String[]	List of HTML elements used within the component.
children	Component[]	Child components detected in the scan.
parents	Component[]	Parent components detected in the scan.

Analyzing custom component properties

Once you have your custom properties on Omlet, you can create tags based on them to analyze the component usage. To learn more, check out Component tags and take a look at Create custom charts documentations.

For string-based custom properties, such as Team or Codeowner, you can directly analyze them in the charts—no need to create individual tags for their values.

Next up

Check these tutorials for popular use cases CLI hooks:

Tutorial 1: Team/code owner usage

Tutorial 2: Package version tracking

Here are some other examples scripts to identify components based on Test and Storybook coverage, visual elements and @deprecated comments:

Other example scripts