Comment on page
Config file

You can define a configuration file to extend the CLI functionality. The configuration 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.
An .omletrc.json, .omletrc.yaml, .omletrc.yml, or .omletrc.js file.
Alternatively, you can also specify a custom configuration file name and location using the --config option in the CLI command:
npx omlet analyze --config './path/file'
Properties
The configuration file can include the following properties:
1
{
2
  "include": string[]
3
  "ignore": string[]
4
  "aliases": {
5
    [name: string]: string[]
6
  }
7
  "exports": {
8
    [name: string]: string[]
9
  }
10
  "tsconfigPath": string
11
  "workspaces": {
12
    [packageName: string]: {
13
      "aliases": {
14
        [name: string]: string[]
15
      }
16
      "exports": {
17
        [name: string]: string[]
18
      }
19
      "tsconfigPath": string
20
    }
21
  }
22
}
include
Specifies an array of filenames or glob patterns to include in the scan. 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.json
1
{
2
  "include": [
3
    "glob/one",
4
    "glob/two"
5
  ]
6
}
ignore
Specifies an array of filenames or glob patterns that should be excluded from the scan. Similar to the include property, these are resolved relative to the root project path.
.omletrc.json
1
{
2
    "ignore": [
3
        "**/test_folder/**",
4
        "**/another_test_folder/**"
5
    ]
6
}
tsconfigPath
A string that is equivalent to the -tsconfig-path parameter.
.omletrc.json
1
{
2
    "tsconfigPath": "tsconfig.frontend.json"
3
}
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.
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.
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. This structure is adopted from the paths property in tsconfig. For more in-depth information, please refer to the tsconfig documentation on paths.
.omletrc.json
1
{
2
  "aliases": {
3
    "@utils": [
4
        "./src/utils/index.ts"
5
      ],
6
    "@components/*": [
7
        "./src/components/*/index.ts", 
8
        "./src/legacy-components/*/index.ts"
9
      ]
10
  }
11
}
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 for resolving imports from external packages.

For example, if your design system library is built and published as a separate package and used in your application repositories as an external dependency, the CLI will need to map imports from the build to their sources correctly.

This is very similar to the Node.js package entry point configuration (i.e., exports and main fields of the package.json file). The difference is, unlike Node.js exports mapping, these patterns should point to the corresponding source module for each package export.
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  "."
Let's say there's a project with the following structure:
projectRoot
├── build/               // Build artifacts
│   ├── index.js
│   └── components
│       └── index.js
|       ...
├── src                  // Source code
│   ├── index.ts
│   └── components
│       └── index.ts
|       ...
│   └── lib
│       └── index.ts
|       ...
│   └── feature
│       └── index.ts
|       ...
└── package.json
If the package.json file has the entry point defined via the "main" field:
package.json
1
{
2
  "name": "@acme/design-system",
3
  "main": "build/index.js"
4
}
The following configuration is needed so that the CLI can map exported modules and names to their corresponding sources:
.omletrc.json
1
{
2
  "exports": {
3
    ".": "src/index.ts"
4
  }
5
}
If you have a more complex entry-point setup in the package.json file similar to the following:
package.json
1
{
2
  "name": "@acme/design-system",
3
  "exports": {
4
    ".": "./build/index.js",
5
    "./lib": "./build/lib/index.js",
6
    "./lib/*": "./build/lib/*.js",
7
    "./lib/*.js": "./build/lib/*.js",
8
    "./feature": "./build/feature/index.js"
9
  }
10
} 
Then, the corresponding export configuration should look like this:
.omletrc.json
1
{
2
  "exports": {
3
    ".": "./src/index.ts",
4
    "./lib": "./src/lib/index.ts",
5
    "./lib/*": "./src/lib/*.tjs",
6
    "./lib/*.js": "./src/lib/*.ts",
7
    "./feature": "./src/feature/index.ts",
8
  }
9
} 
workspaces
If your project is a monorepo with multiple packages, then you can use the "workspaces" field for package-specific configuration.
.omletrc.json
1
{
2
  "workspaces": {
3
    "@acme/design-system": {
4
      "exports": {
5
        ".": "./src/index.ts",
6
      },
7
      "aliases": {
8
      }
9
    },
10
    "@acme/components": {
11
      "aliases": {
12
        "@utils": ["./src/utils/index.ts"],
13
      }
14
    }
15
  }
16
}
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.
Troubleshooting config file
The CLI picks up export and alias configurations from package.json and tsconfig.json files. If you have an .omletrc file, it'll merge them together. Any configuration for the same alias or export you have in the CLI config file overrides the detected ones.
The CLI also validates the merged configuration before scanning your project and reports any errors found in the configuration. You may see error messages similar to these:
Errors:
Cannot find export source in the project
  Source: packages/design-system/package.json
   - Package: @acme/components, Export "./feature", Patterns: ["./build/feature/index.js"]
​
Cannot find alias target in the project
  Source: .omletrc.json
   - Package: @acme/components, Alias "@utils/*", Patterns: ["src/utils-not-exist/*/index.ts"]
The first error shows that there's an export configuration in your  package.json file, but there's no correct configuration that maps the export to its source. Adding the following entry to the package's exports config would fix this issue:
.omletrc.json
1
{
2
  "exports": {
3
    "./feature": "./src/feature/index.ts"
4
  }
5
}
The second error points out that there's no matching source file in your project for the pattern used for the alias @utils/*. In this case, you need to make sure that patterns point to an existing path or a file in your codebase.
CLI - Previous
Commands & options
Next - Learn More
How detection works?
Last modified 2mo ago
Config file

Properties

`include`

`ignore`

`tsconfigPath`

`aliases`

`exports`

`workspaces`

Troubleshooting config file
