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

pnpm i -D vite-plugin-component-tagger

Compatibility

This plugin requires Vite 5 or later.

Features

• 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:

// 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

Basic Usage

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

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

Custom File Extensions

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

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

Specific File Extensions

// 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

Svelte

The plugin is specifically optimized for Svelte components and handles:

• Self-closing tags (<input />, <img />, etc.)
• Special Svelte elements (<svelte:window>, <svelte:head>, etc.)
• Control flow blocks ({#if}, {#each}, {:else}, etc.)
• Conditional rendering
• Nested components

Example with a Svelte Component

<!-- src/components/Button.svelte -->
<script>
	export let type = 'primary';
	export let size = 'medium';
</script>

<button class="button button--{type} button--{size}">
	<slot></slot>
</button>

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

<!-- src/components/Button.svelte -->
<script>
	export let type = 'primary';
	export let size = 'medium';
</script>

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

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:

Workflow Overview

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

Workflow Optimizations

• 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

Setup Instructions

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