@wayfinder/vite-plugin

A Vite plugin for @wayfinder/core that auto-injects data-tour attributes into your source files at build time — zero runtime cost, zero manual markup changes needed.

Installation

npm install -D @wayfinder/vite-plugin

The problem

When class names are obfuscated at build time, you cannot target elements by class. The @wayfinder/react and @wayfinder/vue helpers solve this at the component level by requiring small code changes. This plugin solves it at the build level — no component changes required at all.

Setup

// vite.config.ts
import { wayfinderPlugin } from '@wayfinder/vite-plugin';

export default {
  plugins: [
    wayfinderPlugin({
      inject: {
        // Add data-tour="create-btn" to every <CreateButton …> JSX tag
        'create-btn': { component: 'CreateButton' },

        // Add data-tour="search-bar" next to existing data-testid="search-input"
        'search-bar': { testId: 'search-input' },

        // Add data-tour="nav-home" to any element containing id="nav-home"
        'nav-home': { selector: 'id="nav-home"' },
      }
    })
  ]
}

Then target elements in your Wayfinder config using tourId():

import { Wayfinder, tourId } from '@wayfinder/core';

const tour = new Wayfinder({
  steps: [
    { id: 'create-btn', target: tourId('create-btn'), title: '...', description: '...' },
    { id: 'search-bar', target: tourId('search-bar'), title: '...', description: '...' },
  ],
});

Injection rules

Each key in inject is a tour step ID. The value is an InjectRule with one of three match strategies:

| Strategy | Matches | Example | |---|---|---| | component | JSX/TSX opening tag by display name | { component: 'CreateButton' } | | testId | Elements with an existing data-testid value | { testId: 'search-input' } | | selector | Any raw attribute string on an opening tag | { selector: 'id="nav-home"' } |

Options

| Option | Type | Default | Description | |---|---|---|---| | inject | Record<string, InjectRule> | — | Required. Map of step IDs to injection rules | | attribute | string | 'data-tour' | The attribute name to inject. Must match tourAttribute in WayfinderConfig | | include | string[] | ['.jsx','.tsx','.vue','.svelte'] | File extensions to transform |

Custom attribute

wayfinderPlugin({
  attribute: 'data-wf-target',
  inject: { 'create-btn': { component: 'CreateButton' } }
})

// Pair with WayfinderConfig:
new Wayfinder({ tourAttribute: 'data-wf-target', steps: [...] })

How it works

The plugin runs as a pre transform on matching source files. For each injection rule it applies a lightweight regex replacement — no full AST parsing. The plugin never double-injects: if the attribute already exists in the source, it is skipped.