Config file

Learn more about the CLI configuration and their use cases.

The config file enables you to customize the scanning process. You can define include and ignore properties to designate which directories to scan and utilize exports and aliases properties to let the CLI resolve the correct entry points and recognize the aliases to ensure data accuracy.

Locating the config file

The configuration file for the CLI can be placed in the following locations:

• An omlet property in the package.json file.

• An .omletrc file in JSON or YAML format in the root directory of your repository

• An .omletrc.json, .omletrc.yaml, .omletrc.yml, or .omletrc.js file in the root directory of your repository

Alternatively, you can also specify a custom configuration file name and location using the --config option in the CLI command:

npm

npx @omlet/cli analyze --config './path/file'

yarn

yarn dlx @omlet/cli analyze --config './path/file'

pnpm

pnpm dlx @omlet/cli analyze --config './path/file'

Auto-completion and error highlighting are available for the CLI configuration in popular IDEs like JetBrains and VS Code. Make sure to add Omlet's schema to your config file and have the CLI version 1.7.0 or above.

.omletrc

{
    "$schema": "https://json.schemastore.org/omletrc.json",
    "exports": {
        ...
    }
}

Properties

The configuration file can include the following properties:

include

Specifies an array of filenames or glob patterns to include in the scan.

.omletrc

{
  "include": string[]
}

The paths and patterns are resolved relative to the root project path, where the -r parameter points to—or to the current working directory if -r is not provided.

.omletrc

{
  "include": [
    "glob/one", 
    "glob/two"
  ]
}

You can learn more about the include property here.

ignore

Specifies an array of filenames or glob patterns that should be excluded from the scan.

.omletrc

{
    "ignore": string[]
}

Similar to the include property, these are resolved relative to the root project path.

.omletrc

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

You can learn more about the ignore property here.

tsconfigpath

A string that specifies the path to your tsconfig file.

.omletrc

{
  "tsconfigPath": "tsconfig.frontend.json"
}

exports

The exports property is a series of entries that tells the CLI about the corresponding entry points of a package in the source code. This is required to resolve imports from external dependencies.

.omletrc

"exports": {
    [name: string]: string[]
}

The Omlet CLI follows the same format and convention as Node.js for the exports configuration—except for the conditional exports. The main entry point,import { … } "@acme/design-system", is designated with "."

The exports property should be an object consisting of key-value pairs. The key represents the package export, while the value should be a string that specifies the location of the corresponding source module.

.omletrc

{
  "exports": {
    ".": "src/index.ts"
  }
}

You can learn more about the exports property here.

aliases

The aliases field allows you to define custom alias configurations that are used by bundlers such as Webpack, Vite, or Babel. If you have a custom alias configuration for your bundler, it's also important to configure it for Omlet.

.omletrc

{
    "aliases": {
        [name: string]: string[]
    }
}

The aliases property should be an object consisting of key-value pairs. The key represents the alias string used in the codebase, while the value should be an array of strings that specify the location(s) of the corresponding file or files.

.omletrc

{
  "aliases": {
    "@utils": ["./src/utils/index.ts"],
    "@components/*": [
      "./src/components/*/index.ts",
      "./src/legacy-components/*/index.ts"
    ]
  }
}

This structure is adopted from the paths property in tsconfig. For more in-depth information, please refer to the tsconfig documentation on paths.

You can learn more about the aliases property here.

workspaces

An object to define package-specific configurations for exports and aliases.

.omletrc

"workspaces": {
  [packageName: string]: {
    "aliases": {
      [name: string]: string[]
    }
  }
}

If your project is a monorepo with multiple packages, then you can use the "workspaces" field for package-specific configuration.

.omletrc

{
  "workspaces": {
    "@acme/design-system": {
      "exports": {
        ".": "./src/index.ts"
      },
      "aliases": {}
    },
    "@acme/components": {
      "aliases": {
        "@utils": ["./src/utils/index.ts"]
      }
    }
  }
}

Paths and patterns used in package-specific configurations are resolved relative to the root of corresponding packages.

For example, if @acme/components is located under packages/components, then the pattern used for the @utils alias is resolved to packages/component/src/utils/index.ts.

include, ignore, and tsconfigPath properties can be set using either command-line arguments or the configuration file. If a property is provided as a command-line argument, the corresponding value in the configuration file will be ignored. A default value will be used if a property is not set via the configuration file or command-line argument.

Next steps

Below are the docs explaining the most common use cases for the config file.

• Exports configuration
• Mapping aliases
• Excluding certain components & files
• Tutorial: Config file

Issues with your component data?

If you think your component data in Omlet is inaccurate or if you see data issues on the Web app, you might need to set exports and/or aliases. Learn more here.