Tutorial: Config file

In this example codebase, the design system repository has entry points in the dist folder where the application projects import the published components. This is causing duplicate components issues since the components from both src and dist folders appear in Omlet.

Acme design system

The package.json of the design system repository has the main property set as dist/index.js.

package.json

{
  "name": "acme-design",
  "version": "1.0.0",
  "description": "Acme design system",
  "main": "dist/index.js",
  "scripts": {
    "build": "npm run clean && webpack --mode production",
    "clean": "rm -rf dist"
  },
  ...
}

The index.js file under the src folder exporting the Button and DatePicker components.

src/index.js

export * from "./button";
export * from "./date-picker";

We have a button.jsx file under src/button to define the Button component.

src/button/button.jsx

import react from 'react';
export const Button = ({ onClick, children }) => {
    return <button style={{ border: "none", backgroundColor: "#f0f0f0" }} onClick={onClick}>{children}</button>
}

Also, there is an index.js file under src/button exporting the Button component.

src/button/index.js

export { Button } from './button';

We have a date-picker.jsx file under src/date-picker to define the DatePicker component.

src/date-picker/date-picker.jsx

import react from 'react';
import { Button } from '@/button';

export const DatePicker = ({ onClick, children }) => {
    return <Button onClick={onClick}>📅{children}</Button>
}

There is an index.js file under src/date-picker exporting the DatePicker component.

src/date-picker/index.js

export { DatePicker } from './date-picker';

Imports from application packages

If the application projects import the design system component with statements such as:

import { DatePicker } from "acme-design/dist/date-picker";
import { Button } from "acme-design";

The CLI will detect these usages as external while scanning the application projects, and we'll have duplicate components for Button and DatePicker. The components in the src folder will have 0 usages since the imports resolve to the published components in the dist folder instead of the actual components in the src folder.

Config file

Exports configuration

To help CLI resolve the correct entry points, we need to create a .omletrc file in the root directory of the design system repository and define the exports configuration below.

.omletrc

{
  "$schema": "https://json.schemastore.org/omletrc.json",
  "exports": {
    "dist/*": "src/*",
    ".": "src/index.js"
  }
}

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": {
        ...
    }
}

Also, to prevent the CLI from scanning the dist folder, we need to add its glob pattern to the ignore property so that the published components in the dist folder will not appear in Omlet anymore.

.omletrc

{
  "$schema": "https://json.schemastore.org/omletrc.json",
  "exports": {
    "dist/*": "src/*",
    ".": "src/index.js"
  },
  "ignore": [
    "dist/**"
  ]
}

Alias configuration

Assuming we use a bundler in our design system and have the alias for the src folder resolving any entry point that starts with @ to the src folder. We need to map these aliases to help CLI resolve the correct entry points. The final configuration file for the design system repository should look like below.

.omletrc

{
  "$schema": "https://json.schemastore.org/omletrc.json",
  "exports": {
    "dist/*": "src/*",
    ".": "src/index.js"
  },
  "aliases": {
    "@/*": "src/*"
  },
  "ignore": [
    "dist/**"
  ]
}

If you need to define exports or aliases for other repositories, the configuration files need to be created separately under each repository's root directory.

Package-specific configuration for monorepos

If we would have a monorepo with both the design system and the application projects, .omletrc file will need to be placed in the root directory of the repository, and the exports and aliases will need to be defined under the corresponding package using the workspaces property.

.omletrc

{
  "$schema": "https://json.schemastore.org/omletrc.json",
  "workspaces": {
    "acme-design": {
      "exports": {
        "dist/*": "src/*",
        ".": "src/index.js"
      },
      "aliases": {
        "@/*": "src/*"
      }
    },
    "acme-app": {
      "aliases": {
        "@utils": ["src/utils/index.ts"]
      }
    }
  },
  "ignore": [
    "dist/**"
  ]
}

Need more help?

If you need more help or have questions, feel free to contact us at [email protected].