Getting started

In five minutes you’ll have a single file that declares a scenario (“when a new message arrives and the user has notifications on — show a toast”), and three small components that plug into it. None of the components know about each other.

Skip ahead — open the counter example in StackBlitz Skip ahead — open the counter example in GitHub

Prerequisites

• Node 20+ for the development tooling.
• A React 18+/19, Solid 1.8+, or Vue 3.4+ project. (If you don’t have one yet, run pnpm dlx @triggery/cli create my-app to scaffold a minimal Vite project — see @triggery/cli.)
• TypeScript is recommended but not required. Examples on this site assume TS.

1. Install

You need two packages: @triggery/core (the runtime) and one binding for your framework.

React

pnpm

pnpm add @triggery/core @triggery/react

npm

npm install @triggery/core @triggery/react

yarn

yarn add @triggery/core @triggery/react

bun

bun add @triggery/core @triggery/react

Peer deps: react >= 18.0.0, react-dom >= 18.0.0.

Solid

pnpm

pnpm add @triggery/core @triggery/solid

npm

npm install @triggery/core @triggery/solid

yarn

yarn add @triggery/core @triggery/solid

bun

bun add @triggery/core @triggery/solid

Peer dep: solid-js >= 1.8.0.

Vue

pnpm

pnpm add @triggery/core @triggery/vue

npm

npm install @triggery/core @triggery/vue

yarn

yarn add @triggery/core @triggery/vue

bun

bun add @triggery/core @triggery/vue

Peer dep: vue >= 3.4.0.

Tip

Both packages are ESM-only. If you’re on a tool that doesn’t speak ESM yet (Jest classic config, some older bundlers), switch to Vitest or use --experimental-vm-modules.

2. Wrap your app with a runtime provider

The runtime is what holds the registry of triggers, conditions and actions. Most apps create one runtime at the root.

React

src/main.tsx

import { createRuntime } from '@triggery/core';
import { TriggerRuntimeProvider } from '@triggery/react';
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { App } from './App';

const runtime = createRuntime();

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <TriggerRuntimeProvider runtime={runtime}>
      <App />
    </TriggerRuntimeProvider>
  </StrictMode>,
);

Solid

src/index.tsx

import { createRuntime } from '@triggery/core';
import { TriggerRuntimeProvider } from '@triggery/solid';
import { render } from 'solid-js/web';
import { App } from './App';

const runtime = createRuntime();

render(
  () => (
    <TriggerRuntimeProvider runtime={runtime}>
      <App />
    </TriggerRuntimeProvider>
  ),
  document.getElementById('root')!,
);

Vue

src/main.ts

import { createRuntime } from '@triggery/core';
import { TriggerRuntimePlugin } from '@triggery/vue';
import { createApp } from 'vue';
import App from './App.vue';

const runtime = createRuntime();

createApp(App).use(TriggerRuntimePlugin, { runtime }).mount('#root');

You can omit the provider altogether — in that case Triggery uses a lazily created default runtime. The provider exists so testing, micro-frontends and multi-tenant setups can isolate runtimes.

3. Write your first trigger

Triggery’s house style is one trigger per file, suffixed .trigger.ts. The file reads top-to-bottom as a specification.

src/triggers/message.trigger.ts

import { createTrigger } from '@triggery/core/builder';

type Settings = { sound: boolean; notifications: boolean };
type Message  = { author: string; text: string; channelId: string };

export const messageTrigger = createTrigger<{
  events:     { 'new-message': Message };
  conditions: { settings: Settings; activeChannelId: string | null };
  actions:    { showToast: { title: string; body: string }; playSound: 'beep' };
}>()
  .id('message-received')
  .events(['new-message'])
  .require('settings')
  .handle(({ event, conditions, actions, check }) => {
    // Skip if the user is already looking at this conversation.
    if (conditions.activeChannelId === event.payload.channelId) return;

    // Skip if notifications are off — `check.is` narrows the value.
    if (!check.is('settings', s => s.notifications)) return;

    // Debounce sound so a burst of messages plays one beep.
    actions.debounce(800).playSound?.('beep');
    actions.showToast?.({
      title: event.payload.author,
      body: event.payload.text,
    });
  });

The single inline-generic captures the whole port surface — three maps for events, conditions and actions. .require('settings') narrows conditions.settings to its non-null type inside .handle(...), so we read s.notifications without a ! or an early-return guard. The handler ctx is now strongly typed: try to fire a wrong event name or pass the wrong action payload and TypeScript stops you.

Imperative form still works

If you prefer a single object config, createTrigger({ id, events, required, handler }) is fully supported — import it from @triggery/core (no /builder subpath). The builder above is the new recommended path for v0.10+; the imperative form keeps working through v1.0.

4. Wire components

Triggery splits “who does what” into three component roles:

• Producer — fires an event with useEvent.
• Provider — exposes a snapshot through useCondition so handlers can read it lazily.
• Reactor — registers an action with useAction.

A real chat app puts each of these in its own component, in whichever feature folder it naturally belongs.

React

src/features/SettingsPanel.tsx (provider)

import { useCondition } from '@triggery/react';
import { useState } from 'react';
import { messageTrigger } from '../triggers/message.trigger';

export function SettingsPanel() {
  const [settings, setSettings] = useState({ sound: true, notifications: true });
  useCondition(messageTrigger, 'settings', () => settings, [settings]);
  // …UI for editing settings
}

src/features/Chat.tsx (producer + provider for activeChannelId)

import { useEvent, useCondition } from '@triggery/react';
import { messageTrigger } from '../triggers/message.trigger';

export function Chat({ channelId }: { channelId: string }) {
  const fireMessage = useEvent(messageTrigger, 'new-message');
  useCondition(messageTrigger, 'activeChannelId', () => channelId, [channelId]);

  return (
    <button type="button" onClick={() => fireMessage({ author: 'Alice', text: 'hi', channelId: 'b' })}>
      send a fake message
    </button>
  );
}

src/features/NotificationLayer.tsx (reactor)

import { useAction } from '@triggery/react';
import { toast } from 'sonner';
import { messageTrigger } from '../triggers/message.trigger';

export function NotificationLayer() {
  useAction(messageTrigger, 'showToast', payload => {
    toast.success(payload.title, { description: payload.body });
  });
  useAction(messageTrigger, 'playSound', () => {
    new Audio('/beep.mp3').play().catch(() => {});
  });
  return null;
}

Solid

src/features/SettingsPanel.tsx (provider)

import { useCondition } from '@triggery/solid';
import { createSignal } from 'solid-js';
import { messageTrigger } from '../triggers/message.trigger';

export function SettingsPanel() {
  const [settings] = createSignal({ sound: true, notifications: true });
  useCondition(messageTrigger, 'settings', settings);
}

src/features/Chat.tsx (producer + provider)

import { useEvent, useCondition } from '@triggery/solid';
import { messageTrigger } from '../triggers/message.trigger';

export function Chat(props: { channelId: string }) {
  const fireMessage = useEvent(messageTrigger, 'new-message');
  useCondition(messageTrigger, 'activeChannelId', () => props.channelId);
  return <button onClick={() => fireMessage({ author: 'Alice', text: 'hi', channelId: 'b' })}>send</button>;
}

src/features/NotificationLayer.tsx (reactor)

import { useAction } from '@triggery/solid';
import { messageTrigger } from '../triggers/message.trigger';

export function NotificationLayer() {
  useAction(messageTrigger, 'showToast', payload => console.log('toast', payload));
  useAction(messageTrigger, 'playSound', () => console.log('beep'));
  return null;
}

Vue

src/features/SettingsPanel.vue (provider)

<script setup lang="ts">
import { useCondition } from '@triggery/vue';
import { ref } from 'vue';
import { messageTrigger } from '../triggers/message.trigger';

const settings = ref({ sound: true, notifications: true });
useCondition(messageTrigger, 'settings', () => settings.value);
</script>

src/features/Chat.vue (producer + provider)

<script setup lang="ts">
import { useEvent, useCondition } from '@triggery/vue';
import { defineProps } from 'vue';
import { messageTrigger } from '../triggers/message.trigger';

const props = defineProps<{ channelId: string }>();
const fireMessage = useEvent(messageTrigger, 'new-message');
useCondition(messageTrigger, 'activeChannelId', () => props.channelId);
</script>

<template>
  <button @click="fireMessage({ author: 'Alice', text: 'hi', channelId: 'b' })">send</button>
</template>

src/features/NotificationLayer.vue (reactor)

<script setup lang="ts">
import { useAction } from '@triggery/vue';
import { messageTrigger } from '../triggers/message.trigger';

useAction(messageTrigger, 'showToast', payload => console.log('toast', payload));
useAction(messageTrigger, 'playSound', () => console.log('beep'));
</script>

Mount the three components anywhere in the tree under your provider — they discover each other through the trigger, not through React/Solid/Vue context.

5. Verify

Click “send a fake message” in the Chat component. The notification layer logs (or pops a toast). Toggle settings.notifications off and it falls silent. That’s it — the whole scenario is one file, and every component is free to grow in isolation.

What’s next

Why Triggery Read this if you want the underlying reason this pattern exists — and the problems it doesn't try to solve.

Trigger anatomy Every field of createTrigger config explained, with what each one buys you.

Notification pipeline recipe The full version of this example, with sound debouncing, badge counters and DND mode.

Testing See how to test a trigger without ever rendering React.