@layuplabs/layup-autoid/README.md

A tool to inject stable, unique IDs into React components

# Layup ID Injector

A tool to automatically inject stable, unique IDs into React components for testing purposes.

## Installation

```bash
npm install --save-dev @layuplabs/layup-autoid
```

### Local Development

To use the package locally during development:

1. Clone the repository and install dependencies:

```bash
git clone https://github.com/layuplabs/layup-autoid.git
cd layup-autoid
npm install
```

2. Link the package locally:

```bash
npm link
```

3. In your project directory, link to the local package:

```bash
npm link layup-autoid
```

Now you can use the package in your project as if it were installed from npm. Any changes you make to the source code will be immediately reflected in your project.

```bash
layup-autoid
```

To unlink the package when you're done:

```bash
# In your project directory
npm unlink layup-autoid

# In the layup-autoid directory
npm unlink
```

## Usage

### Command Line

You can run the injector on your entire project:

```bash
npx @layuplabs/layup-autoid
```

You can specify a specific path to search within:

```bash
npx @layuplabs/layup-autoid --path src
# or with short flag
npx @layuplabs/layup-autoid -p packages/my-package
```

### Pre-commit Hook

To automatically run the injector on modified files before each commit:

1. Install the package:

```bash
npm install --save-dev @layuplabs/layup-autoid
```

2. Initialize husky:

```bash
npm run prepare
```

3. Add the pre-commit hook:

```bash
npx husky add .husky/pre-commit "npx @layuplabs/layup-autoid --staged"
```

### Programmatic Usage

```javascript
const { injectIdsInFile, setCustomElements, setIgnoreDefaults, setIgnorePaths, setRemoveTestIds } = require("@layuplabs/layup-autoid");

// Inject IDs in a single file
injectIdsInFile("path/to/your/component.jsx");

// Process with custom elements
setCustomElements(["ButtonCustom", "StyledSpan"]);
injectIdsInFile("path/to/your/component.jsx");

// Process only custom elements (ignoring default HTML elements)
setCustomElements(["ButtonCustom", "StyledSpan"]);
setIgnoreDefaults(true);
injectIdsInFile("path/to/your/component.jsx");

// Ignore specific paths when processing
setIgnorePaths(["src/ignored-dir", "src/another-ignored-dir"]);
injectIdsInFile("path/to/your/component.jsx");

// Remove data-testid attributes instead of adding them
setRemoveTestIds(true);
injectIdsInFile("path/to/your/component.jsx");

// Or process multiple files
const glob = require("glob");
const files = glob.sync("src/**/*.{js,jsx,ts,tsx}");
files.forEach(injectIdsInFile);
```

## What it does

The tool scans your React components and automatically adds unique `data-testid` attributes to standard HTML elements that don't already have one. With the new custom elements feature, it can also process your custom components (like `ButtonCustom` or `StyledDiv`). This makes it easier to write stable end-to-end tests.

You can also use the tool to remove `data-testid` attributes from your components. This is useful when you want to clean up your components or when you want to regenerate all IDs.

Example:

```jsx
// Before
<div className="container">
  <span>Hello World</span>
  <ButtonCustom>Custom Button</ButtonCustom>
</div>

// After
<div className="container" data-testid="auto-id-123e4567-e89b-12d3-a456-426614174000">
  <span data-testid="auto-id-987fcdeb-a89b-12d3-a456-426614174001">Hello World</span>
  <ButtonCustom data-testid="auto-id-456fcded-a45b-78d9-c321-987654321002">Custom Button</ButtonCustom>
</div>
```

## Configuration

### Command Line Options

- `--staged`: Only process files that are staged in git
- `--path` or `-p`: Specify a starting path for file search (e.g., `--path src` or `-p packages/my-package`)
- `--custom-elements` or `-c`: Specify a JSON array of custom component names to process (e.g., `--custom-elements '["ButtonCustom", "StyledSpan"]'`)
- `--ignore-defaults` or `-i`: Ignore the default HTML elements and only process custom elements (requires `--custom-elements` to be provided)
- `--ignore-path` or `-ip`: Specify a path to ignore when processing files (e.g., `--ignore-path src/ignored-dir`)
- `--remove` or `-r`: Remove data-testid attributes instead of adding them (works with all other options)

### Default Behavior

By default, the tool will:

- Process all `.js`, `.jsx`, `.ts`, and `.tsx` files in your project
- Skip files in `node_modules`, `dist`, and `build` directories
- Skip files in paths specified with `--ignore-path`
- Inject IDs into standard HTML elements
- Generate UUID v4 for each ID
- Process custom elements specified with the `--custom-elements` option
- Include standard HTML elements unless `--ignore-defaults` is specified
- Add data-testid attributes unless `--remove` is specified

## License

ISC