Background Jobs

Background Jobs are server functions that can be configured to be triggered on website events to do background tasks without impeding the web flow of a user. In our templates, they are mainly used to send emails to users and update databases upon successful purchases or sign-ups. However, background jobs are very versatile and can be configured to serve a many number of functions.

Features

  • Powered by Inngest: modern queuing and orchestration library.
  • Email notifications upon successful checkouts, subscriptions, purchases and newsletter sign-ups.
  • Asynchronously update databases without impeding user web flow.
  • Easy to configure to your needs and brand.

What's Included

< SubscriptionSuccess />

Asynchronously updates the database and sends congratulatory email to users with successful subscription purchases. The email can easily be configured using the Email Templates.

< CheckoutSuccess />

Similar to SubscriptionSuccess, asynchronously updates the database and sends congratulatory email to users with successful purchases.

< Welcome />

Asynchronously sends a welcome email to users for signing up to Newsletter.

Setup

Acquire environment variables from inngest.com by signing up and configure the variables as follows:

INNGEST_SIGNING_KEY=your-signing-key
INNGEST_EVENT_KEY=your-event-key

Configure inngest client located at /lib/inngest/client.ts:

import { Inngest } from 'inngest';
 
const eventKey = process.env.INNGEST_EVENT_KEY;
 
if (!eventKey)
  throw new Error('Missing environment variables: INNGEST_EVENT_KEY');
 
export const inngest = new Inngest({
  id: '<your-app-id>', // Configure your app id
  eventKey,
});

Customization

Creating Background Jobs

To create your own background jobs start by creating a file under src/jobs.

import { ingest } from '@/lib/inngest/client';
 
interface ExampleEvent {
  event: {
    data: Record<string, unknown>;
  };
}
 
export const exampleJob = inngest.createFunction(
  { id: 'example-id' },
  { event: 'app/examples.example' },
  async ({ event }: ExampleEvent) => {
    // Run an asynchronous job here
  }
);

event.data is an object containing any value sent to the api endpoint.

Add this job function to the api in src/app/(routes)/api/inngest/route.ts.

import { exampleJob } from '@/jobs/exampleJob';
import { serve } from 'inngest/next';
 
import { inngest } from '@/lib/inngest/client';
 
const signingKey = process.env.INNGEST_SIGNING_KEY;
 
if (!signingKey)
  throw new Error('Missing environment variable: INNGEST_SIGNING_KEY');
 
export const { GET, POST, PUT } = serve({
  client: inngest,
  functions: [exampleJob],
  signingKey,
});

Customizing Email Templates

Customizing emails sent to your users asynchronously is so much easier with our Email Templates components. You can learn more about customizing email templates in its documentation page. Here we will just show how to send those email templates using background jobs.

// src/jobs/welcome.ts
import { inngest } from '@/lib/inngest/client';
import { resend } from '@/lib/resend';
 
import { emailSubjects } from '@/content/emailSubjects';
 
import Welcome from '../../emails/transactional/Welcome';
 
interface RegisterEvent {
  event: {
    data: {
      email: string;
    };
  };
}
 
const email = process.env.NEXT_PUBLIC_EMAIL;
 
if (!email) throw new Error('Missing environment variable: NEXT_PUBLIC_EMAIL');
 
export const welcome = inngest.createFunction(
  { id: 'register' },
  { event: 'app/register.welcome' },
  async ({ event }: RegisterEvent) => {
    await resend.emails.send({
      from: `Startbase <${email}>`,
      to: event.data.email,
      subject: emailSubjects.welcome,
      react: Welcome(),
    });
  }
);

This real example showcases how an email template can be used in conjecture with a background job. It uses the resend library to send emails that contain React frontend.