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 thepackage.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'
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
}
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
}
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
}
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.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
}
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
}
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
.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.Last modified 2mo ago