vite-plugin-component-tagger

A Vite plugin that automatically adds identifying attributes to your components during development, making it easier to debug and inspect your component structure.


Installation

``bash
pnpm i -D vite-plugin-component-tagger
`

Compatibility

This plugin requires Vite 5 or later.

$3

- Improved performance with fast HMR updates
- Excellent error handling and diagnostics
- Full TypeScript support
- Enhanced build optimization

Usage

Add the plugin to your Vite configuration:

`js
// vite.config.js / vite.config.ts
import { defineConfig } from 'vite';
import componentTagger from 'vite-plugin-component-tagger';

export default defineConfig({
plugins: [
componentTagger({
// options
})
]
});
`

Options

| Option | Type | Default | Description |
| ---------------- | ---------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| extensions | string[] | ['.svelte'] | File extensions to process |
| enableInProd | boolean | false | Whether to enable the plugin in production builds |
| tagType | string | 'components' | Tagging mode: 'components' only tags the first HTML element in components (not component tags) |

Examples

$3

`js
// vite.config.js
import { defineConfig } from 'vite';
import componentTagger from 'vite-plugin-component-tagger';

export default defineConfig({
plugins: [componentTagger()]
});
`

$3

`js
// vite.config.js
import { defineConfig } from 'vite';
import componentTagger from 'vite-plugin-component-tagger';

export default defineConfig({
plugins: [
componentTagger({
extensions: ['.svelte', '.vue'],
enableInProd: true
})
]
});
`

$3

`js
// vite.config.js
import { defineConfig } from 'vite';
import componentTagger from 'vite-plugin-component-tagger';

export default defineConfig({
plugins: [
componentTagger({
extensions: ['.svelte']
})
]
});
`

How It Works

This plugin transforms your component files during development by adding identifying attributes to components. It adds:

1. A reference attribute to the first HTML element in each component with precise line range information (data-ref="/path/to/Button.svelte#L42-45")

This makes it easier to:

- Debug component hierarchies in the browser
- Track exactly which line and column position of code generated each element
- Write more targeted CSS selectors for testing
- Understand component relationships in complex UI structures

For example, if you have a src/components/Button.svelte component, the plugin will add data-ref="src/components/Button.svelte#L12-14" attributes to elements in the component, making it easy to locate them in your source code.

> Note: The plugin automatically skips files from node_modules directories. External components are not tagged.

Framework-specific Features

$3

The plugin is specifically optimized for Svelte components and handles:

- Self-closing tags (, , etc.)
- Special Svelte elements (, , etc.)
- Control flow blocks ({#if}, {#each}, {:else}, etc.)
- Conditional rendering
- Nested components

#### Example with a Svelte Component

`svelte






`

After transformation (note only the first HTML element is tagged):

`svelte



class="button button--{type} button--{size}"
data-ref="src/components/Button.svelte#L7-9"
>


`

#### Important Notes About Tagging

The plugin:
- Only tags the first HTML element in each component (skips component tags)
- Skips uppercase element names (which are likely component calls)
- Skips self-closing tags
- Only adds the data-ref attribute (for tracing back to source location)
- Only processes files not in node_modules

CI/CD

This project uses GitHub Actions for continuous integration and deployment with an optimized workflow:

$3

We've implemented a streamlined CI/CD pipeline with three distinct workflows:

1. CI Workflow (ci.yml) - Runs on pull requests and non-main branches
- Lints, tests, and builds the project
- Provides early feedback on code quality

2. Publish Workflow (npm-publish.yml) - Runs when changes are merged to main
- Lints, tests, and builds the project
- Automatically bumps the version number based on commit messages
- Publishes the package to npm
- Creates a git tag for the new version

3. Release Workflow (release.yml) - Runs when a new version tag is created
- Generates a comprehensive changelog
- Creates a GitHub release with release notes

$3

- Avoiding Duplicate Runs: The CI workflow excludes the main branch to prevent duplicate runs when changes are merged
- Efficient Publishing Process: The npm publish workflow handles all verification, versioning, and publishing in a single job
- Automated Versioning: Uses conventional commits to determine version increments automatically
- Cache Optimization: Uses pnpm cache to speed up dependency installation

$3

To set up automatic npm publishing for your fork:

1. Generate an npm access token with publishing rights:

- Go to npmjs.com → User Settings → Access Tokens
- Create a new token with "Automation" type
- Copy the token value

2. Add the token as a GitHub repository secret:

- Go to your GitHub repository → Settings → Secrets and variables → Actions
- Create a new repository secret named NPM_TOKEN
- Paste your npm token as the value

3. Use conventional commit messages to control version bumping:

- fix: ... - Patch release (0.0.x)
- feat: ... - Minor release (0.x.0)
- feat!: ... or fix!: ... or any commit with BREAKING CHANGE` in the footer - Major release (x.0.0)

4. Push changes to the main branch to trigger a release

License

MIT