React hooks: Overview

You can display the live progress of a Job Run to your users, including the status of individual tasks and the final output of the Run.

This updates live as the Job progresses, until we show the "Posted to Slack" output

Setting up your project for hooks

This guide assumes that your project is already setup and you have a Job running. If not, you should follow the quick start guide first.

Install the package

Add the @trigger.dev/react package to your project:

npm install @trigger.dev/react@latest

Get your public API key

In the Trigger.dev dashboard you should go to your Project and then the “Environments & API Keys” page.

You should copy the PUBLIC API key for the dev environment.

What's a public API key?

Setting up environment variables

Add the NEXT_PUBLIC_TRIGGER_PUBLIC_API_KEY environment variable to your project. This will be used by the TriggerProvider component to connect to the Trigger API.

.env.local

#...
TRIGGER_API_KEY=[your_private_api_key]
NEXT_PUBLIC_TRIGGER_PUBLIC_API_KEY=[your_public_api_key]
#...

Your private API key should already be in there.

NEXT_PUBLIC_ is a special prefix that exposes the environment variable to your users’ web browsers.

Add the NEXT_PUBLIC_TRIGGER_PUBLIC_API_KEY environment variable to your project. This will be used by the TriggerProvider component to connect to the Trigger API.

.env.local

#...
TRIGGER_API_KEY=[your_private_api_key]
NEXT_PUBLIC_TRIGGER_PUBLIC_API_KEY=[your_public_api_key]
#...

Your private API key should already be in there.

NEXT_PUBLIC_ is a special prefix that exposes the environment variable to your users’ web browsers.

Add the TRIGGER_PUBLIC_API_KEY environment variable to your project. This will be used by the TriggerProvider component to connect to the Trigger API.

.env

#...
TRIGGER_API_KEY=[your_private_api_key]
TRIGGER_PUBLIC_API_KEY=[your_public_api_key]
#...

You will need to pass this value from the server to the client. We recommend you do this in your Root loader.

Add the <TriggerProvider> component

The TriggerProvider component is a React Context Provider that will make the Trigger API client available to all child components.

Generally you’ll want to add this to the root of your app, so that it’s available everywhere. However, you can add it lower in the hierarchy but it must be above any of the hooks.

app/layout.tsx

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body className={inter.className}>
        <TriggerProvider publicApiKey={process.env.NEXT_PUBLIC_TRIGGER_PUBLIC_API_KEY!}>
          {children}
        </TriggerProvider>
      </body>
    </html>
  );
}

app/layout.tsx

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body className={inter.className}>
        <TriggerProvider publicApiKey={process.env.NEXT_PUBLIC_TRIGGER_PUBLIC_API_KEY!}>
          {children}
        </TriggerProvider>
      </body>
    </html>
  );
}

app/root.tsx

//return the public key env var from the loader so it's available in the browser
export const loader = async ({ request }: LoaderFunctionArgs) => {
  //...other code

  const triggerPublicApiKey = env.TRIGGER_PUBLIC_API_KEY!;

  return json({
    //...other data
    triggerPublicApiKey
  });
}

//Your default export, i.e. the page component
export default function App() {
    const {
      //...other data
      triggerPublicApiKey
    } = useLoaderData<typeof loader>();

    return (
      <html lang="en">
        <head>
          <Meta />
          <Links />
        </head>
        <body className={inter.className}>
          {/* wrap your outlet in this  */}
          <TriggerProvider publicApiKey={triggerPublicApiKey}>
            <Outlet />
          </TriggerProvider>
          <ScrollRestoration />
          <ExternalScripts />
          <Scripts />
          <LiveReload />
        </body>
      </html>
    );
}

Two ways to report Run progress

Automatic progress – without writing additional code in your Job you can get updates on the overall run status and individual tasks inside the run.

Explicit status – add code to your Job that reports the status of the things you’re doing. This gives you full flexibility for displaying progress in your UI.

Automatic hooks

Receive coarse updates without writing additional Job code

Explicit status hooks

Add statuses to your Job code for fine-grained UI updates

Getting Started

Concepts

Guides

Community & Support

Overview

React hooks: Overview

Setting up your project for hooks

Install the package

Get your public API key

Setting up environment variables

Add the <TriggerProvider> component

Two ways to report Run progress

Automatic hooks

Explicit status hooks

Getting Started

Concepts

Guides

Community & Support

Overview

​Setting up your project for hooks

Install the package

Get your public API key

Setting up environment variables

Add the <TriggerProvider> component

​Two ways to report Run progress

Automatic hooks

Explicit status hooks

Setting up your project for hooks

Two ways to report Run progress