triggery (Vite plugin)

Stable · since 0.1.0

A Vite plugin that globs every *.trigger.{ts,tsx,js,jsx} file in the project at build time and generates a virtual module — virtual:triggery-registry — that imports all of them. Import the virtual module once at your app entry point and every trigger registers itself with the runtime automatically; no manual wiring, no per-file import './foo.trigger' lines.

HMR-aware: editing an existing trigger file re-runs its createTrigger(...) call and the runtime’s last-mount-wins replaces the old registration. Adding, removing, or renaming a trigger file invalidates the virtual module so the import list is rebuilt on the next request.

Import

import triggery from '@triggery/vite';

// or
import { triggery } from '@triggery/vite';

Signature

function triggery(options?: TriggeryViteOptions): Plugin;

type TriggeryViteOptions = {
  readonly glob?: string | readonly string[];
};

Options

Field	Type	Default	Description
glob	string | readonly string[]	'src/**/*.trigger.{ts,tsx,js,jsx}'	Pattern(s) for trigger files. Resolved relative to the project root reported by Vite.

Examples

Default — drop into vite.config

import { defineConfig } from 'vite';
import triggery from '@triggery/vite';

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

Then in your app entry:

// src/main.tsx
import 'virtual:triggery-registry';
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { App } from './App';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />
  </StrictMode>,
);

Custom glob

import { defineConfig } from 'vite';
import triggery from '@triggery/vite';

export default defineConfig({
  plugins: [
    triggery({
      glob: 'src/features/**/*.trigger.ts',
    }),
  ],
});

Multiple globs

import { defineConfig } from 'vite';
import triggery from '@triggery/vite';

export default defineConfig({
  plugins: [
    triggery({
      glob: ['src/**/*.trigger.ts', 'packages/*/src/**/*.trigger.ts'],
    }),
  ],
});

Typing the virtual module

Add to a global .d.ts so TypeScript stops complaining about the bare-string import:

declare module 'virtual:triggery-registry' {
  export {};
}

Notes

Tip

The virtual module is sorted alphabetically by file path — registration order is deterministic between builds and machines. The runtime’s last-mount-wins is the tiebreaker if two triggers share an id (you should fix that, but it won’t crash).

Side-effect imports

Each glob match is imported for its side effects, not for any export. Make sure every *.trigger.ts file calls createTrigger(...) at module scope — lazy-init inside a function won’t be picked up.

Pre-bundle order

The plugin sets enforce: 'pre' so the virtual module resolves before user imports. If you stack plugins that also use enforce: 'pre', the order is whatever Vite’s dependency-graph resolves to — usually the order you list them in plugins: array.

Related

createTrigger The constructor each `*.trigger.ts` file calls.

createRuntime Triggers register against the default runtime by default.

Vite project layout guide Conventions for organizing trigger files.

CLI scaffold trigger Generate a new `*.trigger.ts` from the terminal.