Idomatic

Idomatic is a CLI tool that automatically injects id attributes into your HTML/JSX/TSX components.

It helps ensure better testability, maintainability, and traceability in your codebase by adding stable, unique id attributes where they’re missing.

Installation

To install Idomatic, run the initializer:

npm init @idomatic

This command creates a .idomatic.config.json configuration file tailored to your tech stack (React, HTML, Vue, etc).

Scripts

You can define Idomatic scripts in your package.json:

{
  "scripts": {
    "scan": "idomatic scan",
    "scan:dry": "idomatic scan --dry"
  }
}

scan

Scans your files and injects missing id attributes based on your config. It modifies source files directly.

scan:dry

Dry run mode – logs which files would be updated, but doesn’t write anything to disk. Useful for CI or testing changes.

Configuration

Idomatic uses a .idomatic.config.json config file to customize how and where IDs are applied.

Example .idomatic.config.json

{
  "prefix": "idomatic-",
  "attributeName": "id",
  "includeExtensions": ["js", "jsx", "ts", "tsx", "html", "vue"],
  "excludeFiles": ["node_modules", "dist"],
  "excludeTags": ["html", "head", "meta", "link", "script", "style"]
}

Explanation

⚠️

• The new Angular and Vue Considerations section provides guidance tailored for both frameworks.
• Angular guidance emphasizes external HTML files via templateUrl, ensuring that Idomatic picks up the component templates.
• Vue guidance reassures that the <template> block is processed correctly—but advises caution if using inline templates.

Option Reference

Examples

JSX Before

<div>
  <button>Submit</button>
</div>

JSX After idomatic scan

<div id="idomatic-uuid">
  <button id="idomatic-uuid">Submit</button>
</div>

HTML Before

<section>
  <p>Hello world</p>
</section>

HTML After

<section id="idomatic-uuid">
  <p id="idomatic-uuid">Hello world</p>
</section>