@omlet/cli

Omlet CLI

Omlet (https://omlet.dev) is a component analytics tool that uses a CLI to scan your codebase to detect components and their usage. Get real usage insights from customizable charts to measure adoption across all projects and identify opportunities to improve your components.

To learn more about Omlet and how to use it check out our documentation.

Table of Contents

1. Features
2. Installation
3. Usage
4. Advanced
5. Security
6. Frequently Asked Questions
7. Support

Features

• Calculates React Components and their usage in your code base
• Analyze component usage and adoption with provided charts
• Create custom charts for more detailed component analysis
• Create a dashboard for a collection of charts
• View a dependency tree for each component to surface where and how the component is used and view parent/child relationships
• Gain insights into props usage for each component

Installation

1. Install Omlet CLI as a dependency:

$ npm i --save-dev @omlet/cli

1. Log in to Omlet CLI:

npx omlet login

Usage

To start the component analysis, navigate to the root of the repo you wish to scan and run the Omlet CLI:

npx omlet init

Follow the link in the CLI to take you to the Omlet Web App at feta.omlet.dev and view your analytics dashboard. Check out our docs on how to get started with insights from Omlet: https://docs.omlet.dev/getting-started/getting-insights-with-omlet

If you have multiple respositories, you can scan them into the same Omlet workspace and it will automatically correlate components defined in one repo that are used in another. No duplicate components or double counting of usage!

To scan a new repo, add @omlet/cli as a dependency like before and run:

npx omlet analyze

Advanced

Custom Configuration

You might need to define a configuration file in your repository if:

• You have alias setup in your bundler configuration.
• Your design system library is published as an npm package and is utilized as an external dependency.

If you require extra configuration, create a new files named .omletrc.js at the root of your repository and follow the instructions in the Omlet docs.

Ignoring Components

Omlet supplies sensible default configurations to ignore certain files such as Storybook stories documentation or test files.

• **/node_modules/**
• **/*.d.ts
• **/stories/**/*
• **/.storybook/**/*
• **/*.stories.{jsx,tsx,js,ts}
• **/*.{spec,test}.{jsx,tsx,js,ts}
• **/{__test__,tests}/**/*.{jsx,tsx,js,ts}

To exclude more glob patterns, add the "ignore" array to your .omletrc.js config:

{
    "ignore": [
        "**/test_folder/**",
        "**/another_test_folder/**"
    ]
}

You can also pass a glob pattern to the --ignore option in the analyze CLI command to filter out directories, files, or components you do not want to track. The --ignore option can be passed in multiple times for multiple patterns, e.g. --ignore 'glob/one/' --ignore 'glob/two/'

Security

Omlet is a product developed and provided by Zeplin, Inc. which has SOC 2 Type II attestation. For Omlet, we implement the same security controls as the rest of the Zeplin ecosystem. For more details, please head to the Security page in the Omlet docs.

Frequently Asked Questions

How does component detection work?

Omlet detects and tracks only the components that are defined and exported from JS/TS modules. Local components, which are components used within the same module that are not exported, are not surfaced in Omlet.

In the example below, only ExportedButton will be tracked and reported in Omlet because it is defined and exported. Button is a local component used only within the button.tsx module, so it is excluded from the scanned results.

function Button() {
  ...
}

export function ExportedButton() {
  ...

  return <Button/>;
}

How does component usage get calculated?

Omlet detects and counts the unique usage of each component. If a component is used multiple times within the same component, Omlet considers it as a single usage.

In the given example, there are multiple instances of ListItem within ListView but Omlet will count this as a single usage of ListItem.

Using the same example below, Omlet will also recognize that ListView is using Button indirectly through a local component ListButton. However, ListButton will not appear in the results.

import Button from "./Button";
import  ListItem from "./ListItem";

function ListButton() {
  ...

  return <Button/>;
}

export function ListView() {
  ...

  return (
    <div>
      <div><ListItem/></div>
      ...
      <div><ListItem/></div>
      <div><ListButton/></div>
    </div>
  );
}

How is the data collected for Omlet?

Omlet never collects, stores or upload your code. The scanning process is always done locally using the Omlet CLI available for download via NPM. Only metadata is collected. As a user, you have full control over what code Omlet will scan by choosing which repository it should scan. You also have the option to limit scanning to certain files or directories.

What data is collected for Omlet?

Regarding metadata, Omlet collects:

• Function names related to frontend code
• File paths of where the functions are defined
• Where the functions are called from

For troubleshooting purposes, other metadata we collect are:

• IP address of the user who uploads the data
• Node.js version
• OS type/version
• URL to the git repository and current branch name

Omlet CLI has an option to generate the output locally which you can use to inspect the data. You can do this by running:

omlet analyze --dry-run 

This will generate a local file omlet.out.json with the scanned output that is normally uploaded to Omlet's Web app. When using --dry-run, the results are never uploaded.

Support

• Join the Omlet Community on Discord
• Take a look at the Omlet Docs for troubleshooting your issue
• Email us at [e-mail]