DEV Community: Soma Somorjai

Building Dynamic User Journeys: Your Guide to Next.js Onboarding with OnboardJS

Soma Somorjai — Sat, 12 Jul 2025 09:22:23 +0000

Next.js developers love the power and flexibility of the framework, but even with its advantages, building an engaging, multi-step user onboarding experience can quickly become a significant undertaking. Managing step logic, dynamic navigation, persistence across sessions, and analytics can turn your elegant codebase into a complex web of conditional rendering and state management.

Imagine an onboarding library that handles all this complexity for you, letting you focus on crafting beautiful UI components and compelling content, perfectly integrated within your Next.js application.

This is where OnboardJS comes in. It's an open-source, headless onboarding engine designed to abstract away the intricate logic of multi-step flows. This post will guide you through setting up OnboardJS to build a robust Next.js onboarding flow, making your first-user experiences intuitive and efficient.

What is OnboardJS? The Headless Advantage for Next.js

OnboardJS offers a powerful, framework-agnostic onboarding engine (from @onboardjs/core). This "headless" nature means it focuses solely on the intricate backend logic of your flow:

Dynamically determining the next/previous step
Managing the flow's internal state and context
Handling conditional navigation and step skipping
Seamlessly integrating with data persistence and analytics layers
Providing a robust plugin system for extended functionality

For Next.js developers, this headless approach is a perfect fit. The core engine runs independently, and our @onboardjs/react package provides the necessary hooks and a context provider to integrate it effortlessly into your Next.js Client Components, allowing you to render any step dynamically and respond to user actions.

Before we dive in, we have a full Next.js example on our GitHub so you don't have to start from scratch! All we ask is a ⭐ in return 😉.

Why OnboardJS for Your Next.js App?

Simplifies Complex Logic: No more tangled if/else trees or manual state machines for your Next.js onboarding flow. OnboardJS handles the entire orchestration.
SSR/CSR Compatibility: OnboardJS's headless nature means its core logic isn't tied to the DOM, making it ideal for Next.js environments. The React components that consume it live in Client Components, where they belong.
Extensible by Design: Need to persist user progress to PostgreSQL via Supabase or Neon? Or track onboarding events with PostHog? Our plugin system makes it incredibly easy – and we already offer official plugins for these!

Getting Started: Installation

Let's install the necessary packages for your Next.js project. This tutorial assumes that you already have a Next.js project set up. If you don't have that yet, follow the official Next.js Docs.

npm install @onboardjs/core @onboardjs/react

Step 1: Define Your Onboarding Steps (Configuration)

The core definition of your Next.js onboarding flow lies in its configuration. This is where you outline each step: its unique ID, its type (e.g., "INFORMATION", "CUSTOM_COMPONENT"), and any specific data (payload) it needs for rendering. This configuration file can be shared between server and client components as needed.

Create a config/onboardingConfig.ts file (or similar):

// config/onboardingConfig.ts
// Optionally, define your custom onboarding context type
export interface MyAppContext extends OnboardingContext {
  currentUser?: {
    id: string;
    email: string;
    firstName?: string;
  };
  // Add any other global data you need throughout the flow
}

export const onboardingSteps: OnboardingStep<MyAppContext>[] = [
  {
    id: "welcome",
    payload: {
      mainText: "Welcome to our product! Let's get you set up.",
      subText: "This quick tour will guide you through the basics.",
    },
    nextStep: "collect-info", // Go to next step by ID
  },
  {
    id: "collect-info",
    type: "CUSTOM_COMPONENT", // We'll render this with a custom React component
    payload: {
      componentKey: "UserProfileForm", // Key to map to your React component
      formFields: [
        // Example form field data
        { id: "name", label: "Your Name", type: "text", dataKey: "userName" },
        { id: "email", label: "Email", type: "email", dataKey: "userEmail" },
      ],
    },
    // Conditionally skip if user data already exists
    condition: (context) => !context.currentUser?.firstName,
    isSkippable: true,
    skipToStep: "select-plan",
  },
  {
    id: "select-plan",
    type: "SINGLE_CHOICE",
    payload: {
      question: "Which plan are you interested in?",
      options: [
        { id: "basic", label: "Basic", value: "basic" },
        { id: "pro", label: "Pro", value: "pro" },
      ],
      dataKey: "chosenPlan", // Data will be stored as flowData.chosenPlan
    },
    // nextStep defaults to the next step in array if not specified
  },
  {
    id: "all-done",
    payload: {
      mainText: "You're all set!",
      subText: "Thanks for completing the onboarding.",
    },
  },
];

export const onboardingConfig: OnboardingEngineConfig<MyAppContext> = {
  steps: onboardingSteps,
  initialStepId: "welcome", // Start here or from persisted data
  initialContext: {
    // Initial global context, can be overwritten by loaded data
    currentUser: { id: "user_123", email: "test@example.com" },
  },
  // You can define load/persist/clearData functions here,
  // or use the localStoragePersistence option in OnboardingProvider
};

For more details on defining steps and configurations, refer to the OnboardJS Core Documentation: Configuration.

Step 2: Wrap Your App with OnboardingProvider (Next.js Specifics)

This is a crucial step for Next.js, especially with the App Router. The OnboardingProvider from @onboardjs/react must be defined as a Client Component (using "use client";) because it relies on React Hooks and browser APIs (like localStorage if used for device persistence). It then makes the OnboardJS engine's state and actions available throughout your Client Component tree.

Create a dedicated Client Component wrapper component (e.g.: OnboardingWrapper.tsx):

// app/OnboardingWrapper.tsx
"use client"; // REQUIRED: This makes the component a Client Component

import { OnboardingProvider } from "@onboardjs/react";
import { onboardingConfig, type MyAppContext } from "@/config/onboardingConfig"; // Adjust path as needed

export function OnboardingWrapper({ children }: { children: React.ReactNode }) {
  // Example: Using localStorage for persistence - great for quick demos!
  const localStoragePersistenceOptions = {
    key: "onboardjs-demo-state",
    ttl: 7 * 24 * 60 * 60 * 1000, // 7 days TTL
  };

  // Optional: Listen for flow completion to clear local storage
  const handleFlowComplete = async (context: MyAppContext) => {
    console.log("Onboarding Flow Completed!", context.flowData);
    // Any final actions like redirecting, showing success message etc.
    // The provider automatically clears local storage if localStoragePersistence is active.
  };

  // Optional: Listen for step changes for debugging or custom logic
  const handleStepChange = (newStep, oldStep, context) => {
    console.log(
      `Step changed from ${oldStep?.id || "N/A"} to ${newStep?.id || "N/A"}`,
      context.flowData,
    );
  };

  return (
    <OnboardingProvider
      {...onboardingConfig} // Pass your defined steps, initialStepId, initialContext etc.
      localStoragePersistence={localStoragePersistenceOptions}
      onFlowComplete={handleFlowComplete}
      onStepChange={handleStepChange}
      // You can also pass custom loadData/persistData/clearPersistedData here
    >
      {children}
    </OnboardingProvider>
  );
}

// In your root layout.tsx:
// import { OnboardingWrapper } from "./OnboardingWrapper";
// export default function RootLayout({ children }) {
//   return (
//     <html>
//       <body>
//         <OnboardingWrapper>{children}</OnboardingWrapper>
//       </body>
//     </html>
//   );
// }

Step 3: Render Your Current Step with useOnboarding

The useOnboarding hook gives you access to the current state of the engine (like currentStep) and actions (next, previous, skip, goToStep, updateContext).You'll also need a StepComponentRegistry to map your step types or step IDs (e.g., "INFORMATION", "CUSTOM_COMPONENT") to actual React components.

First, define your StepComponentRegistry:

// config/stepRegistry.tsx
import React from "react";
import {
  useOnboarding,
  type StepComponentRegistry,
  type StepComponentProps,
} from "@onboardjs/react";
import type { InformationStepPayload } from "@onboardjs/core";
import type { MyAppContext } from "@/config/onboardingConfig";

// --- Step Components (examples) - Feel free to put these into separate component files ---
const InformationStep: React.FC<StepComponentProps<InformationStepPayload>> = ({
  payload,
}) => {
  return (
    <div>
      <h2 className="text-2xl font-bold mb-4">{payload.mainText}</h2>
      {payload.subText && <p className="text-gray-600">{payload.subText}</p>}
    </div>
  );
};

const UserProfileFormStep: React.FC<StepComponentProps> = ({
  payload,
  coreContext,
}) => {
  const { updateContext } = useOnboarding<MyAppContext>();
  const [userName, setUserName] = React.useState(
    coreContext.flowData.userName || "",
  );
  const [userEmail, setUserEmail] = React.useState(
    coreContext.flowData.userEmail || "",
  );

  React.useEffect(() => {
    // Update the context whenever userName or userEmail changes
    // Note: There are more sophisticated ways to handle this,
    // such as debouncing or only updating on form submission.
    updateContext({ flowData: { userName, userEmail } });
  }, [userName, userEmail, updateContext]);

  return (
    <div>
      <h2 className="text-2xl font-bold mb-4">Tell us about yourself!</h2>
      <input
        type="text"
        placeholder="Your Name"
        value={userName}
        onChange={(e) => setUserName(e.target.value)}
        className="border p-2 rounded mb-2 w-full"
      />
      <input
        type="email"
        placeholder="Your Email"
        value={userEmail}
        onChange={(e) => setUserEmail(e.target.value)}
        className="border p-2 rounded mb-4 w-full"
      />
      {payload.formFields?.map((field: any) => (
        <div key={field.id}>
          {/* Render other form fields based on payload.formFields */}
        </div>
      ))}
    </div>
  );
};

// Map your step types to React components
export const stepComponentRegistry: StepComponentRegistry = {
  INFORMATION: InformationStep,
  CUSTOM_COMPONENT: UserProfileFormStep, // Map 'CUSTOM_COMPONENT' to your form
  // You'd add components for 'SINGLE_CHOICE', 'MULTIPLE_CHOICE', etc. here
  // For example, you could defined a one-off component for the 'select-plan' id step
  // 'select-plan': SelectPlanStep, // Example for a custom step
};

Then, add it to your OnboardingProvider:

import { stepComponentRegistry } from "@/config/stepRegistry"
// In your OnboardingWrapper
return (
    <OnboardingProvider
      componentRegistry={stepComponentRegistry}
      >
      {children}
    </OnboardingProvider>
  );

And finally, we provide our Onboarding UI:

// components/OnboardingUI.tsx
import React from "react";
import {
  useOnboarding,
} from "@onboardjs/react";
import type { OnboardingContext } from "@onboardjs/core";

export default function OnboardingUI() {
  const { engine, state, next, previous, isCompleted, currentStep, renderStep, error } =
    useOnboarding<MyAppContext>();

  if (!engine || !state) {
    return <div className="p-4">Loading onboarding...</div>;
  }

  if (error) {
    return (
      <div className="p-4 text-red-500">
        Error: {error.message} (Please check console for details)
      </div>
    );
  }

  if (currentStep === null || isCompleted) {
    return (
      <div className="p-8 text-center bg-green-50 rounded-lg">
        <h2 className="text-3xl font-bold text-green-700">
          Onboarding Complete!
        </h2>
        <p className="text-gray-700 mt-4">
          Thanks for walking through the flow. Check your console for the final
          context!
        </p>
        <button
          onClick={() => engine.reset()}
          className="mt-6 px-6 py-3 bg-blue-600 text-white rounded-md hover:bg-blue-700 transition-colors"
        >
          Reset Onboarding
        </button>
      </div>
    );
  }

  const { isLastStep, canGoPrevious } = state;


  return (
    <div className="p-8 bg-white rounded-lg shadow-xl max-w-md mx-auto my-10">
      <h3 className="text-xl font-semibold mb-6">
        Step: {String(currentStep?.id)} ({currentStep?.type})
      </h3>
      <div className="mb-6">
        {renderStep()}
      </div>
      <div className="flex justify-between mt-8">
        <button
          onClick={() => previous()}
          disabled={!canGoPrevious}
          className="px-6 py-3 bg-gray-300 text-gray-800 rounded-md disabled:opacity-50 disabled:cursor-not-allowed hover:bg-gray-400 transition-colors"
        >
          Previous
        </button>
        <button
          onClick={() => next()}
          className="px-6 py-3 bg-blue-600 text-white rounded-md disabled:opacity-50 disabled:cursor-not-allowed hover:bg-blue-700 transition-colors"
        >
          {isLastStep ? "Finish" : "Next"}
        </button>
      </div>
      <div className="mt-4 text-sm text-center text-gray-500">
        Current flow data:{" "}
        <pre className="bg-gray-100 p-2 rounded text-xs mt-2 overflow-x-auto">
          {JSON.stringify(state.context.flowData, null, 2)}
        </pre>
      </div>
    </div>
  );
}

The custom step components and the Onboarding UI is where *YOU * shine. These are the components where you can realise your beautiful design!

Next Steps: Beyond the Basics

You've now got a functional Next.js onboarding flow! But OnboardJS offers much more:

Conditional Steps: Use the condition property on any step to dynamically include or skip it based on your context.
Plugins for Persistence & Analytics: Integrate seamlessly with your backend or analytics tools. Check out our dedicated @onboardjs/supabase-plugin and @onboardjs/posthog-plugin for automated data handling.
- Build Robust User Onboarding with Supabase & OnboardJS (No More Lost Progress!)
- PostHog Onboarding Analytics in 5 Minutes (OnboardJS Plugin)
Advanced Step Types: Explore CHECKLIST, MULTIPLE_CHOICE, and SINGLE_CHOICE steps for common onboarding patterns, or define even more CUSTOM_COMPONENT types.
Custom Context: Extend the OnboardingContext to store any global data your flow needs, making it accessible across all steps.
Error Handling: Leverage the built-in error handling and error state from useOnboarding to provide graceful fallbacks.

Conclusion: Build Better Onboarding, Faster

Building a compelling Next.js onboarding flow doesn't have to be a drag. OnboardJS empowers you to create dynamic, data-driven user journeys with a clear separation of concerns, robust features, and excellent developer experience. By handling the complex orchestration, OnboardJS lets you focus on what truly matters: designing an intuitive and effective first impression for your users.

Ready to build your next Next.js onboarding?

Explore the live demo: https://onboardjs.com/
Get the source code and ⭐ us on GitHub!
Join our Discord community

What challenges have you faced building Next.js onboarding flows, and how could a tool like OnboardJS help you overcome them? Tell me on Discord!

Building Seamless User Journeys: Your Guide to React Onboarding with OnboardJS

Soma Somorjai — Fri, 11 Jul 2025 08:03:52 +0000

Every product developer knows the pain: building an engaging onboarding experience. It often starts simple, but quickly spirals into a tangled mess of state management, conditional logic, persistence layers, and endless UI components. You end up building an "onboarding engine" from scratch, reinventing the wheel with every new product tour or multi-step form.

What if there was a better way? What if you could focus solely on the user interface and content, leaving the complex flow management to a robust core?

Enter OnboardJS. It's an open-source, headless onboarding engine designed to liberate you from this complexity. In this tutortial I will show you exactly how to get started with React onboarding using OnboardJS, enabling you to build powerful and flexible React onboarding flows that delight your users.

Before we dive in, we have a full React example on our GitHub so you don't have to start from scratch! All we ask is a ⭐ in return 😉.

What is OnboardJS? The Headless Advantage

At its core, OnboardJS provides a powerful, framework-agnostic onboarding engine. This "headless" approach means the engine handles all the intricate logic:

Determining the next/previous step
Managing the flow's state and context
Handling conditional navigation and skips
Integrating with data persistence and analytics
Providing a robust plugin system for extensibility

This core engine is entirely separate from your UI. For React developers, this is where the @onboardjs/react package comes in. It provides hooks and a context provider to seamlessly connect the OnboardJS engine to your React components, allowing you to render any step dynamically.

Why OnboardJS for Your React App?

Simplify Complex Logic: Stop writing endless if/else statements for navigation. OnboardJS handles it.
Clean Separation of Concerns: Your React components focus purely on rendering and user interaction, while the engine manages the flow. This makes your code cleaner and easier to maintain.
Extensible by Design: Need to persist user progress to Supabase or track events with PostHog? Our plugin system makes it a breeze (and we already have plugins for these!).
Developer Experience (DX) Focused: Built with TypeScript, OnboardJS offers type safety and a predictable API, making your React onboarding flow development much smoother.
Future-Proof: The headless nature means your core onboarding logic isn't tied to React, giving you flexibility down the line.

Getting Started: Installation

Let's dive into setting up OnboardJS in your React project. In this example, we assume you already have a React project set up.

If you don't, I follow this React + Vite documentation to get started with a new project.

First, install the necessary packages:

npm install @onboardjs/core @onboardjs/react

Step 1: Define Your Onboarding Steps (Configuration)

The heart of your React onboarding flow is its configuration. This is where you define your steps: their IDs, types, and the data (payload) they need to render.

Create a config/onboardingConfig.ts file (or similar):

// config/onboardingConfig.ts
// Optionally, define your custom onboarding context type
export interface MyAppContext extends OnboardingContext {
  currentUser?: {
    id: string;
    email: string;
    firstName?: string;
  };
  // Add any other global data you need throughout the flow
}

export const onboardingSteps: OnboardingStep<MyAppContext>[] = [
  {
    id: "welcome",
    payload: {
      mainText: "Welcome to our product! Let's get you set up.",
      subText: "This quick tour will guide you through the basics.",
    },
    nextStep: "collect-info", // Go to next step by ID
  },
  {
    id: "collect-info",
    type: "CUSTOM_COMPONENT", // We'll render this with a custom React component
    payload: {
      componentKey: "UserProfileForm", // Key to map to your React component
      formFields: [
        // Example form field data
        { id: "name", label: "Your Name", type: "text", dataKey: "userName" },
        { id: "email", label: "Email", type: "email", dataKey: "userEmail" },
      ],
    },
    // Conditionally skip if user data already exists
    condition: (context) => !context.currentUser?.firstName,
    isSkippable: true,
    skipToStep: "select-plan",
  },
  {
    id: "select-plan",
    type: "SINGLE_CHOICE",
    payload: {
      question: "Which plan are you interested in?",
      options: [
        { id: "basic", label: "Basic", value: "basic" },
        { id: "pro", label: "Pro", value: "pro" },
      ],
      dataKey: "chosenPlan", // Data will be stored as flowData.chosenPlan
    },
    // nextStep defaults to the next step in array if not specified
  },
  {
    id: "all-done",
    payload: {
      mainText: "You're all set!",
      subText: "Thanks for completing the onboarding.",
    },
  },
];

export const onboardingConfig: OnboardingEngineConfig<MyAppContext> = {
  steps: onboardingSteps,
  initialStepId: "welcome", // Start here or from persisted data
  initialContext: {
    // Initial global context, can be overwritten by loaded data
    currentUser: { id: "user_123", email: "test@example.com" },
  },
  // You can define load/persist/clearData functions here,
  // or use the localStoragePersistence option in OnboardingProvider
};

For more details on defining steps and configurations, refer to the OnboardJS Core Documentation: Configuration.

Step 2: Wrap Your App with OnboardingProvider

The OnboardingProvider from @onboardjs/react sets up the OnboardingEngine and makes its state and actions available throughout your React component tree via Context.

If you're using Next.js App Router, you'll place this in your layout.tsx or a dedicated client component wrapper. For our case, it goes into index.tsx or App.tsx.

// app/OnboardingWrapper.tsx
"use client"; // Important only for Next.js App Router

import { OnboardingProvider } from "@onboardjs/react";
import { onboardingConfig, type MyAppContext } from "@/config/onboardingConfig"; // Adjust path as needed

export function OnboardingWrapper({ children }: { children: React.ReactNode }) {
  // Example: Using localStorage for persistence - great for quick demos!
  const localStoragePersistenceOptions = {
    key: "onboardjs-demo-state",
    ttl: 7 * 24 * 60 * 60 * 1000, // 7 days TTL
  };

  // Optional: Listen for flow completion to clear local storage
  const handleFlowComplete = async (context: MyAppContext) => {
    console.log("Onboarding Flow Completed!", context.flowData);
    // Any final actions like redirecting, showing success message etc.
    // The provider automatically clears local storage if localStoragePersistence is active.
  };

  // Optional: Listen for step changes for debugging or custom logic
  const handleStepChange = (newStep, oldStep, context) => {
    console.log(
      `Step changed from ${oldStep?.id || "N/A"} to ${newStep?.id || "N/A"}`,
      context.flowData,
    );
  };

  return (
    <OnboardingProvider
      {...onboardingConfig} // Pass your defined steps, initialStepId, initialContext etc.
      localStoragePersistence={localStoragePersistenceOptions}
      onFlowComplete={handleFlowComplete}
      onStepChange={handleStepChange}
      // You can also pass custom loadData/persistData/clearPersistedData here
    >
      {children}
    </OnboardingProvider>
  );
}

// In your root layout.tsx:
// import { OnboardingWrapper } from "./OnboardingWrapper";
// export default function RootLayout({ children }) {
//   return (
//     <html>
//       <body>
//         <OnboardingWrapper>{children}</OnboardingWrapper>
//       </body>
//     </html>
//   );
// }

Step 3: Render Your Current Step with useOnboarding

The useOnboarding hook gives you access to the current state of the engine (like currentStep) and actions (next, previous, skip, goToStep, updateContext).You'll also need a StepComponentRegistry to map your step types or step IDs (e.g., "INFORMATION", "CUSTOM_COMPONENT") to actual React components.

First, define your StepComponentRegistry:

// config/stepRegistry.tsx
import React from "react";
import {
  useOnboarding,
  type StepComponentRegistry,
  type StepComponentProps,
} from "@onboardjs/react";
import type { InformationStepPayload } from "@onboardjs/core";
import type { MyAppContext } from "@/config/onboardingConfig";

// --- Step Components (examples) - Feel free to put these into separate component files ---
const InformationStep: React.FC<StepComponentProps<InformationStepPayload>> = ({
  payload,
}) => {
  return (
    <div>
      <h2 className="text-2xl font-bold mb-4">{payload.mainText}</h2>
      {payload.subText && <p className="text-gray-600">{payload.subText}</p>}
    </div>
  );
};

const UserProfileFormStep: React.FC<StepComponentProps> = ({
  payload,
  coreContext,
}) => {
  const { updateContext } = useOnboarding<MyAppContext>();
  const [userName, setUserName] = React.useState(
    coreContext.flowData.userName || "",
  );
  const [userEmail, setUserEmail] = React.useState(
    coreContext.flowData.userEmail || "",
  );

  React.useEffect(() => {
    // Update the context whenever userName or userEmail changes
    // Note: There are more sophisticated ways to handle this,
    // such as debouncing or only updating on form submission.
    updateContext({ flowData: { userName, userEmail } });
  }, [userName, userEmail, updateContext]);

  return (
    <div>
      <h2 className="text-2xl font-bold mb-4">Tell us about yourself!</h2>
      <input
        type="text"
        placeholder="Your Name"
        value={userName}
        onChange={(e) => setUserName(e.target.value)}
        className="border p-2 rounded mb-2 w-full"
      />
      <input
        type="email"
        placeholder="Your Email"
        value={userEmail}
        onChange={(e) => setUserEmail(e.target.value)}
        className="border p-2 rounded mb-4 w-full"
      />
      {payload.formFields?.map((field: any) => (
        <div key={field.id}>
          {/* Render other form fields based on payload.formFields */}
        </div>
      ))}
    </div>
  );
};

// Map your step types to React components
export const stepComponentRegistry: StepComponentRegistry = {
  INFORMATION: InformationStep,
  CUSTOM_COMPONENT: UserProfileFormStep, // Map 'CUSTOM_COMPONENT' to your form
  // You'd add components for 'SINGLE_CHOICE', 'MULTIPLE_CHOICE', etc. here
  // For example, you could defined a one-off component for the 'select-plan' id step
  // 'select-plan': SelectPlanStep, // Example for a custom step
};

Then, add it to your OnboardingProvider:

import { stepComponentRegistry } from "@/config/stepRegistry"
// In your OnboardingWrapper
return (
    <OnboardingProvider
      componentRegistry={stepComponentRegistry}
      >
      {children}
    </OnboardingProvider>
  );

And finally, we provide our Onboarding UI:

// components/OnboardingUI.tsx
import React from "react";
import {
  useOnboarding,
} from "@onboardjs/react";
import type { OnboardingContext } from "@onboardjs/core";

export default function OnboardingUI() {
  const { engine, state, next, previous, isCompleted, currentStep, renderStep, error } =
    useOnboarding<MyAppContext>();

  if (!engine || !state) {
    return <div className="p-4">Loading onboarding...</div>;
  }

  if (error) {
    return (
      <div className="p-4 text-red-500">
        Error: {error.message} (Please check console for details)
      </div>
    );
  }

  if (currentStep === null || isCompleted) {
    return (
      <div className="p-8 text-center bg-green-50 rounded-lg">
        <h2 className="text-3xl font-bold text-green-700">
          Onboarding Complete!
        </h2>
        <p className="text-gray-700 mt-4">
          Thanks for walking through the flow. Check your console for the final
          context!
        </p>
        <button
          onClick={() => engine.reset()}
          className="mt-6 px-6 py-3 bg-blue-600 text-white rounded-md hover:bg-blue-700 transition-colors"
        >
          Reset Onboarding
        </button>
      </div>
    );
  }

  const { isLastStep, canGoPrevious } = state;


  return (
    <div className="p-8 bg-white rounded-lg shadow-xl max-w-md mx-auto my-10">
      <h3 className="text-xl font-semibold mb-6">
        Step: {String(currentStep?.id)} ({currentStep?.type})
      </h3>
      <div className="mb-6">
        {renderStep()}
      </div>
      <div className="flex justify-between mt-8">
        <button
          onClick={() => previous()}
          disabled={!canGoPrevious}
          className="px-6 py-3 bg-gray-300 text-gray-800 rounded-md disabled:opacity-50 disabled:cursor-not-allowed hover:bg-gray-400 transition-colors"
        >
          Previous
        </button>
        <button
          onClick={() => next()}
          className="px-6 py-3 bg-blue-600 text-white rounded-md disabled:opacity-50 disabled:cursor-not-allowed hover:bg-blue-700 transition-colors"
        >
          {isLastStep ? "Finish" : "Next"}
        </button>
      </div>
      <div className="mt-4 text-sm text-center text-gray-500">
        Current flow data:{" "}
        <pre className="bg-gray-100 p-2 rounded text-xs mt-2 overflow-x-auto">
          {JSON.stringify(state.context.flowData, null, 2)}
        </pre>
      </div>
    </div>
  );
}

The custom step components and the Onboarding UI is where YOU shine. These are the components where you can realise your beautiful design!

Next Steps: Beyond the Basics

You've now got a functional React onboarding flow! But OnboardJS offers much more:

Conditional Steps: Use the condition property on any step to dynamically include or skip it based on your context.
Plugins for Persistence & Analytics: Integrate seamlessly with your backend or analytics tools. Check out our dedicated @onboardjs/supabase-plugin and @onboardjs/posthog-plugin for automated data handling.
- Build Robust User Onboarding with Supabase & OnboardJS (No More Lost Progress!)
- PostHog Onboarding Analytics in 5 Minutes (OnboardJS Plugin)
Advanced Step Types: Explore CHECKLIST, MULTIPLE_CHOICE, and SINGLE_CHOICE steps for common onboarding patterns, or define even more CUSTOM_COMPONENT types.
Custom Context: Extend the OnboardingContext to store any global data your flow needs, making it accessible across all steps.
Error Handling: Leverage the built-in error handling and error state from useOnboarding to provide graceful fallbacks.

Conclusion: Build Better Onboarding, Faster

Building a compelling React onboarding flow doesn't have to be a drag. OnboardJS empowers you to create dynamic, data-driven user journeys with a clear separation of concerns, robust features, and excellent developer experience. By handling the complex orchestration, OnboardJS lets you focus on what truly matters: designing an intuitive and effective first impression for your users.Ready to build your next React onboarding masterpiece?

Explore the live demo: https://onboardjs.com/
Get the source code and ⭐ us on GitHub!
Join our Discord community

What challenges have you faced building React onboarding flows, and how could a tool like OnboardJS help you overcome them?

My Learnings from 2.6K Views and 0 Form Submissions

Soma Somorjai — Wed, 09 Jul 2025 08:51:33 +0000

Building OnboardJS in Public:

As a mainly front-end dev my passion lies in creating seamless UX. But sometimes, even the most well-intentioned ideas for enhancing that experience can fail, especially when building in public. I recently had a stark reminder of this truth when I launched a new demo for OnboardJS, our open-source user onboarding engine, and saw a significant disconnect between interest and action. Let me tell you the story of 2.6K views, 0 conversions, and a valuable lesson learned.

The Experiment: A "Meta Onboarding" Demo

For those unfamiliar, OnboardJS helps developers build multi-step user onboarding flows effortlessly, providing a headless engine and a React integration. I wanted to showcase its power with a "meta onboarding" demo on our landing page – an interactive tour about OnboardJS, built with OnboardJS.

My initial thought process was this: developers would love this interactive tour. At the end, they could fill out a simple form (Firstname, Lastname, Email) to receive the demo code (a ZIP file) along with an "onboarding optimization guide." My idea was to add extra value, perhaps offer a slightly more personalized starter kit, and yes, collect a few leads to understand who was interested.

Here's what the "Form" step with the Personal Information gathering looked like:

The Data Speaks: Loud and Clear

Yesterday, I shared the demo on the popular /r/reactjs subreddit with a post titled "Multi-Step user onboarding with OnboardJS." The response was surprising. As of this morning, the post had gotten 2.6K views, alongside positive engagement (upvotes, and an ever favorite comment, "good bro"). Traffic to our demo surged.

I was really happy. Developers were clearly interested in the problem OnboardJS solves, and they were clicking through to the demo. My analytics confirmed a good number of unique visitors interacting with the onboarding flow.

But then I checked the form submissions.

The result: 0.

Yes, zero. Not one single person, out of thousands of interested developers, completed that form.

Understanding the Developer Mindset: Friction Kills

A 0% conversion rate isn't an optimization problem that subtle A/B testing can fix. I thought about A/B testing having the form vs having a direct download button, however, it's a fundamental misjudgment of user expectations and developer psychology. This wasn't about the button color or the form field labels; it was about the gate itself.

Here's why, looking back, it was a colossal misstep for an open-source project:

Trust Deficit: As a relatively new open-source project, OnboardJS hasn't yet built the immense trust that larger, established projects command. Asking for Personally Identifiable Information (PII) like names and email addresses is a high barrier when trust isn't fully cemented. Developers are inherently wary of being added to unwanted mailing lists.
Expectation of Free Access: Open source ethos champions immediate, unfettered access to code. Putting a form in front of demo code feels counter-intuitive and stupid in hindsight. Developers expect to go straight to GitHub, clone a repo, or download a ZIP file with a single click.
Perceived Value vs. Friction: The "exclusive optimization guide" and "customized starter kit" might have sounded valuable to me, but to a developer, the value of that specific demo's source code likely didn't outweigh the friction and privacy concerns of filling out a multi-field form. They likely assumed much of it was already in the main repo anyway.
Interruption to Flow: The primary goal of clicking the Reddit link was to experience the demo and potentially see how it works. Introducing a form interrupts that flow with a "sales-y" interaction that doesn't align with the exploratory, learn-by-doing mindset.

The data (or lack thereof) was a harsh but invaluable teacher: for open-source code, friction is the enemy of adoption.

The Fix: Immediate & Frictionless Access

Based on this lesson, I've done the obvious thing: I've removed the form completely.

Now, when you complete the "meta onboarding" demo on our site, you'll be greeted with a direct download link for the full demo example code. No hoops, no forms, no strings attached. Just pure, immediate access to the code.

This change isn't just about fixing a bug; it's about re-aligning with the core values of building open source. OnboardJS is about making developer's lives easier, and that starts with making it easy to try and use the project.

The Broader Lesson for Building in Public

This experience has reinforced a crucial lesson for anyone building open-source projects or developer tools:

Listen to Implicit Feedback: Sometimes the loudest feedback isn't what people say, but what they don't do. A zero conversion rate is screaming at you.
Prioritize Developer Experience (DX) Above All Else: This includes the DX of getting started with your project. Minimize friction at every possible touchpoint.
Build Trust Through Transparency: Being open about failures, learnings, and how you adapt based on user behavior builds immense goodwill and trust within the community.
Value Community Over Leads (Especially Early On): For an open-source project, GitHub stars, Discord joins, and contributions are often more valuable "leads" than email addresses.

My goal for OnboardJS is to be the go-to extensible framework for user onboarding. This journey means constantly learning and adapting. If we can't get developers to access a simple demo, how can we expect them to adopt a whole framework?

Conclusion: Always Be Learning

This incident was a humbling but incredibly useful part of my journey building OnboardJS in public. It's a reminder that even when you think you're adding value, you might be creating unnecessary friction. My commitment remains steadfast: building a powerful, flexible, and developer-friendly onboarding solution.

So, please, go try the OnboardJS demo here. Experience the flow, grab the code, and tell me: what other barriers can we break down to make developer onboarding truly frictionless?

Stop Wasting Time: Build Your First Onboarding Flow with OnboardJS in Under 10 Minutes

Soma Somorjai — Mon, 23 Jun 2025 09:28:03 +0000

I Hate When Building Simple Onboarding Feels Like a Whole New App

As a developer, I've spent countless hours wrestling with custom onboarding logic. The state management, the routing, the persistence, the conditional steps... it's a headache most libraries just ignore, leaving you to piece together a complex state machine from scratch.

You're trying to ship a great product, but instead, you're deep in the weeds of boilerplate code, managing all the possible states your app could be in as users navigate back and forth, or worse, worrying about losing their progress on a simple page refresh.

The truth is: You shouldn't have to build a complex state machine for every single onboarding flow. OnboardJS does it for you.

In this post, you'll learn how to leverage OnboardJS to create robust, maintainable onboarding experiences in minutes, not days. We'll build a simple two-step flow from scratch using Next.js and React.

Introducing OnboardJS: The Headless Advantage

OnboardJS is a headless, type-safe, and extensible engine designed specifically for managing multi-step user flows. What does "headless" mean? It means OnboardJS gives you the powerful "brain" to manage your flow's state, logic, and persistence, while you provide the "beauty" – your own React UI components.

This separation is crucial:

Your UI, Your Rules: Use any component library (Tailwind, Chakra UI, Shadcn UI, custom components!).
Built-in Logic: Handle complex navigation, conditional steps, and data collection effortlessly.
Automatic Persistence: Store user progress seamlessly, preventing frustrating restarts.
Type-Safe: Catch errors early with full TypeScript support, making your flows more robust.

Combined with the @onboardjs/react package, it becomes incredibly intuitive to integrate OnboardJS into your Next.js application.

Hands-On: Building Your First Flow (The 10-Minute Challenge!)

Ready to see how easy it is? We'll create a simple two-step onboarding flow: a "Welcome" step to collect a user's name, and a "Finish" step to display collected data.

No boilerplate, no complex state machines. Just define your steps, map your UI, and let OnboardJS handle the rest.

4.1. Project Setup

First, you will need a Next.js app (or use your existing one).
Then, install OnboardJS:

npm install @onboardjs/core @onboardjs/react

4.2. Define Your Onboarding Steps & Components

OnboardJS steps define the flow's logic, not the UI. For our quick start, we'll use CUSTOM_COMPONENT steps, which let you bring any React component into your flow.

Create a file like src/onboarding-config.ts (or onboarding-config.tsx if your components are in the same file) and add the following:

// src/onboarding-config.ts
// Import your actual React components here
import ProfileSetupForm from './components/ProfileSetupForm';
import FinishStepComponent from './components/FinishStepComponent';

// Define your onboarding flow steps
export const steps: OnboardingStep[] = [
  {
    id: 'welcome',
    type: 'CUSTOM_COMPONENT',
    payload: {
      componentKey: 'ProfileSetupForm', // Maps to our component registry
      title: 'Welcome to Our App!', // Example custom payload data
      description: 'Let\'s get your profile set up quickly.',
    },
  },
  {
    id: 'finish',
    type: 'CUSTOM_COMPONENT',
    payload: {
      componentKey: 'FinishStepComponent', // Maps to our finish component
      title: 'Setup Complete!',
      message: 'You\'re all set to explore our amazing features!',
    },
    nextStep: null, // Critical: 'null' indicates the end of the flow
  },
];

// Define your component registry to map componentKeys to actual React components
// This tells OnboardJS which UI component to render for each custom step.
export const componentRegistry: StepComponentRegistry = {
  ProfileSetupForm: ProfileSetupForm,
  FinishStepComponent: FinishStepComponent,
};

The payload object allows you to pass any custom data your React component needs (like a title or description). The componentKey is how OnboardJS knows which of your React components to render for this step type.

4.3. Create Your React Components

Now, let's create the actual React components that OnboardJS will render. These components receive payload (your custom data), coreContext (the global onboarding data), and onDataChange (a function to update collected data).

src/components/ProfileSetupForm.tsx:

// src/components/ProfileSetupForm.tsx
"use client"; // Required for Next.js App Router client components
import React from "react";
import { useOnboarding, StepComponentProps } from "@onboardjs/react"; // <-- Essential hook for navigation

interface ProfileSetupPayload {
  title: string;
  description: string;
}

const ProfileSetupForm: React.FC<StepComponentProps<ProfileSetupPayload>> = ({
  payload, // Access the payload data passed from the engine
  coreContext, // Access global onboarding data here if needed
}) => {
  const { next, isLoading, state, updateContext } = useOnboarding(); // Get navigation functions and current state

  const updateName = (newName: string) => {
    // Then, you update the context here
    updateContext({ flowData: { profileName: newName } });
  };

  return (
    <div>
      <h2>{payload.title}</h2>
      <p>{payload.description}</p>

      <label htmlFor="name-input">Your Name:</label>
      <input
        id="name-input"
        type="text"
        defaultValue={coreContext?.flowData?.profileName || ""}
        onChange={(e) => updateName(e.target.value)}
        placeholder="Enter your name"
      />

      <button
        onClick={() => next()} // Calls the engine's 'next' function
        disabled={isLoading || !state?.canGoNext} // Disable if loading or if step isn't valid
      >
        {isLoading ? "Loading..." : "Next"}
      </button>
    </div>
  );
};

export default ProfileSetupForm;

In ProfileSetupForm.tsx, we use the useOnboarding hook to get next() (to advance the flow), isLoading (to provide visual feedback), and state (to check if canGoNext).

src/components/FinishStepComponent.tsx:

// src/components/FinishStepComponent.tsx
"use client"; // Required for Next.js App Router client components

import React from "react";
import { StepComponentProps, useOnboarding } from "@onboardjs/react";
// No need for useOnboarding here if no navigation action is taken on this final step

interface FinishPayload {
  title: string;
  message: string;
}

const FinishStepComponent: React.FC<StepComponentProps<FinishPayload>> = ({
  payload,
  coreContext,
}) => {
  const { next } = useOnboarding();
  // You can access all collected data from coreContext.flowData
  const finalUserName = coreContext.flowData.profileName || "Guest"; // Use 'profileName' collected from previous step

  return (
    <div
      style={{
        padding: "20px",
        border: "1px solid #eee",
        borderRadius: "8px",
        maxWidth: "400px",
        margin: "auto",
      }}
    >
      <h2>{payload.title}</h2>
      <p>{payload.message}</p>
      <p>Welcome, {finalUserName}!</p>
      <p>
        Your collected data:
        <pre
          style={{
            backgroundColor: "#f0f0f0",
            padding: "10px",
            borderRadius: "4px",
            overflowX: "auto",
            fontSize: "0.9em",
          }}
        >
          {JSON.stringify(coreContext.flowData, null, 2)}
        </pre>
      </p>
      {/* The Finish button */}
      <button
        onClick={() => {
          // Finish the onboarding flow by calling next()
          next();
        }}
      >
        Finish
      </button>
    </div>
  );
};

export default FinishStepComponent;

The FinishStepComponent.tsx demonstrates how easily you can access all collected data from coreContext.flowData, allowing you to personalize the final step or display a summary.

4.4. Render your Onboarding UI

Now combining these previous steps and components will be your Onboarding UI.

This component will allow you to render the current step automatically and wrap your steps in an optional frame.

// ./components/OnboardingUI.tsx
"use client"; // REQUIRED for client-side hooks like useOnboarding and useRouter

import React from 'react';
import { useOnboarding } from "@onboardjs/react";

// Create a simple wrapper component to manage global UI and navigation
export default function OnboardingUI() {
  const { state, isLoading, next, previous, skip, reset, renderStep } = useOnboarding();

  // Basic Loading/Completion/Error States for brevity in this guide
  if (!state) {
    return <div style={{ textAlign: 'center', padding: '20px' }}>Loading onboarding...</div>;
  }
  if (state.error) {
    return (
      <div style={{ textAlign: 'center', padding: '20px', color: 'red' }}>
        Error: {state.error.message} <button onClick={() => reset()} style={{ marginLeft: '10px' }}>Reset</button>
      </div>
    );
  }
  if (state.isCompleted) {
    return (
      <div style={{ textAlign: 'center', padding: '20px' }}>
        <h2>Onboarding Completed! 🎉</h2>
        <p>You're all set. Redirecting to dashboard...</p>
      </div>
    );
  }

  return (
    <div style={{ maxWidth: '600px', margin: '20px auto', padding: '20px', border: '1px solid #ccc', borderRadius: '8px' }}>
      {/* The function that renders your current step's UI */}
      {renderStep()}

      {/* (Optional) Basic Navigation Buttons */}
      <div style={{ marginTop: '20px', display: 'flex', justifyContent: 'space-between' }}>
        {state.canGoPrevious && (
          <button onClick={previous} disabled={isLoading} style={{ padding: '8px 15px', cursor: 'pointer' }}>
            Back
          </button>
        )}
        {state.isSkippable && (
          <button onClick={skip} disabled={isLoading} style={{ padding: '8px 15px', cursor: 'pointer', marginLeft: 'auto' }}>
            Skip
          </button>
        )}
        {state.canGoNext && (
          <button onClick={next} disabled={isLoading || !state.canGoNext} style={{ padding: '8px 15px', cursor: 'pointer', backgroundColor: '#0070f3', color: 'white', border: 'none' }}>
            Next
          </button>
        )}
        {state.isLastStep && !state.isCompleted && (
          <button onClick={next} disabled={isLoading} style={{ padding: '8px 15px', cursor: 'pointer', backgroundColor: '#28a745', color: 'white', border: 'none' }}>
            Finish
          </button>
        )}
      </div>
    </div>
  );
}

Here, we've created a simple OnboardingUI component that uses useOnboarding() to get the current state and navigation functions. The {renderStep()} is the core, telling OnboardJS to render the correct React component you defined in your componentRegistry for the active step. We also added basic 'Next', 'Back', 'Skip', and 'Finish' buttons, leveraging state.canGoNext, state.canGoPrevious, and state.isSkippable for intelligent button control. This simple wrapper centralizes your onboarding UI logic.

4.5. Integrate OnboardJS into Your React App

Finally, wrap your application with the OnboardingProvider. This makes the OnboardJS engine available throughout your app via the useOnboarding hook, and tells it which steps to manage.

In your main application file (e.g., src/app/layout.tsx for Next.js App Router, or src/App.tsx for a Create React App). Remember to include "use client"; at the top if you're using Next.js App Router and this is a Server Component by default.

You can also wrap your OnboardingProvider in a client component first as to avoid making the whole layout.tsx a client component!

// src/app/layout.tsx (for Next.js App Router example)
"use client"; // REQUIRED for client-side hooks like useOnboarding and useRouter

import React from "react";
import { OnboardingProvider } from "@onboardjs/react";
import { steps, componentRegistry } from "./onboarding-config";
import { useRouter } from "next/navigation"; // Import useRouter for redirection example

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  const router = useRouter(); // Initialize router if you want to redirect after flow completion

  return (
    <html lang="en">
      <body>
        <OnboardingProvider
          steps={steps}
          componentRegistry={componentRegistry} // Link your UI components
          onFlowComplete={(context) => {
            console.log("Onboarding flow completed!", context);
            alert(
              `Onboarding complete for ${
                context.flowData.profileName || "user"
              }!`
            );
            // Example: Redirect the user to their dashboard after onboarding
            router.push("/dashboard"); // Make sure you have a /dashboard page!
          }}
          onStepChange={(newStep, oldStep, context) => {
            console.log("Step changed:", oldStep?.id, "->", newStep?.id);
            // You could use this to send analytics events, update UI, etc.
          }}
          localStoragePersistence={{ key: "myAppOnboardingState" }} // Magical persistence!
          initialStepId="welcome" // Optional: Specify starting step if not the first in array
        >
          <main>
            {/* You can render your application UI here */}
            <YourApplicationUI />
          </main>
        </OnboardingProvider>
      </body>
    </html>
  );
}

The OnboardingProvider is your central hub. It takes your steps and componentRegistry to render the correct UI. Notice onFlowComplete and onStepChange for powerful lifecycle hooks, and localStoragePersistence for automatic state saving – a common pain point solved with a single line!

4.5. Run Your App!

npm run dev

Navigate to your app in the browser. You should see your 'Welcome' step! Try filling in your name and clicking 'Next'.

Then, refresh the page – your progress will be saved automatically thanks to localStoragePersistence! If you go back to the app, you'll land directly on the 'Finish' step.

Final Thoughts

You've just built a fully functional, stateful onboarding flow in minutes, not hours or days, without a single line of state management boilerplate. This is just the beginning of what OnboardJS can do:

Conditional Logic: Implement dynamic flows where steps appear or change based on user input or coreContext values, using condition and dynamic nextStep/previousStep functions.
Deep Customization: Use updateContext to modify the global flow data dynamically.
The Powerful Plugin System: Extend OnboardJS with custom integrations, like connecting to your backend for cross-device persistence.

Read more on how to integreate with Supabase to achieve a consistent cross-device onboarding flow!

Ready to build smarter onboarding experiences that delight users and save you development time?

React Email in Azure Functions via Resend

Soma Somorjai — Fri, 31 Jan 2025 12:26:41 +0000

The story about using Azure Functions to render and send emails via React Email and Resend.

The need: At Domainly.shop, our Next.js front-end was originally responsible for handling tasks like sending emails (e.g., for user sign-ups). However, to avoid burdening the web app with email rendering and delivery, we decided to offload this functionality to an Azure function.

Step-by-step:

Create a new Azure Function.
Add React, React Email and Resend requirements
Create an email, render it with some props and send it on its way!

Introduction

Sending emails is a critical part of many modern web applications, whether it’s for user sign-ups, password resets, or transactional notifications. However, handling email rendering and delivery directly within your front-end application can lead to performance bottlenecks and unnecessary complexity. Us at Domainly.shop, we faced this challenge with our Next.js front-end, which was initially responsible for sending emails. To improve scalability and offload this workload, we turned to Azure Functions, a serverless compute service, combined with React Email for building dynamic email templates and Resend for reliable email delivery.

This guide walks you through the process of setting up an Azure Function to render and send emails using React Email and Resend. By the end, you’ll have a scalable, maintainable solution for handling email workflows without burdening your front-end application.

Step 1: Setting Up an Azure Function.

Create your Typescript Azure Function from the default template. For this, the easiest if you follow this Microsoft official guide. For simplicity’s sake I will use an HttpTrigger . But you may use any trigger which best fits your needs.

The initial state of our project.

Step 2: Installing Dependencies for React Email and Resend.

Now that we have our Azure Function it is time to add our dependencies for React Email and Resend by running the following commands:
npm install react-email @react-email/components resend
npm install --save-dev @types/react
Add the following scripts to your package.json:

// These scripts will allow you to run and test your emails in dev mode.
"scripts": {
  ...
   // Once we add our first email, npm run email will let us view our emails.
  "email": "email dev -p 4001",
  "export": "email export"
  ...
},

And finally, update your tsconfig.json to handle .jsx and .tsx files.

{
  "compilerOptions": {
    "module": "CommonJS",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "resolveJsonModule": true,
    "lib": ["dom", "DOM.Iterable", "esnext"],
    "target": "ESNext",
    "outDir": "dist",
    "baseUrl": ".",
    "allowJs": true,
    "sourceMap": true,
    "strict": true,
    "jsx": "react-jsx",
    "skipLibCheck": true
  },
  "exclude": ["node_modules", "dist"],
  "include": [
    "src/**/*.ts",
    "src/**/*.tsx",
    "emails/**/*.ts",
    "emails/**/*.tsx"
  ]
}

Step 3: Adding your first Email and delivering it!

3.1 Create your first email

In your project’s root folder create and emails folder. This is where we will place our [email_name].tsx files. For this guide, we will use a very simple email, however, feel free to bling it out after!

// From the Koala tempalte https://demo.react.email/preview/welcome/koala-welcome?view=desktop&lang=jsx
// Import necessary components from React Email
import {
  Body,
  Button,
  Container,
  Head,
  Hr,
  Html,
  Img,
  Preview,
  Section,
  Text,
} from "@react-email/components";

// We define some external prop our email will need to display its content
interface KoalaWelcomeEmailProps {
  userFirstname: string;
}

const baseUrl = "https://yoursite.example";

export const KoalaWelcomeEmail = ({
  userFirstname,
}: KoalaWelcomeEmailProps) => (
  <Html>
    <Head />
    <Preview>
      The sales intelligence platform that helps you uncover qualified leads.
    </Preview>
    <Body style={main}>
      <Container style={container}>
        <Img
          src={`${baseUrl}/static/koala-logo.png`}
          width="170"
          height="50"
          alt="Koala"
          style={logo}
        />
        <Text style={paragraph}>Hi {userFirstname},</Text>
        <Text style={paragraph}>
          Welcome to Koala, the sales intelligence platform that helps you
          uncover qualified leads and close deals faster.
        </Text>
        <Section style={btnContainer}>
          <Button style={button} href="https://getkoala.com">
            Get started
          </Button>
        </Section>
        <Text style={paragraph}>
          Best,
          <br />
          The Koala team
        </Text>
        <Hr style={hr} />
        <Text style={footer}>
          470 Noor Ave STE B #1148, South San Francisco, CA 94080
        </Text>
      </Container>
    </Body>
  </Html>
);

KoalaWelcomeEmail.PreviewProps = {
  userFirstname: "Alan",
} as KoalaWelcomeEmailProps;

export default KoalaWelcomeEmail;

const main = {
  backgroundColor: "#ffffff",
  fontFamily:
    '-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Oxygen-Sans,Ubuntu,Cantarell,"Helvetica Neue",sans-serif',
};

const container = {
  margin: "0 auto",
  padding: "20px 0 48px",
};

const logo = {
  margin: "0 auto",
};

const paragraph = {
  fontSize: "16px",
  lineHeight: "26px",
};

const btnContainer = {
  textAlign: "center" as const,
};

const button = {
  backgroundColor: "#5F51E8",
  borderRadius: "3px",
  color: "#fff",
  fontSize: "16px",
  textDecoration: "none",
  textAlign: "center" as const,
  display: "block",
  padding: "12px",
};

const hr = {
  borderColor: "#cccccc",
  margin: "20px 0",
};

const footer = {
  color: "#8898aa",
  fontSize: "12px",
};

3.2 Render the email

Normally, we would move our email handling into separate files so they can be nicely separated. However, for this guide’s purposes we will just put it into our function file.

Make sure to update the src/functions/httpTrigger1.ts to src/function/httpTrigger1.tsx since we will be dealing with React components.

First we will create the CreateEmailOptions constant which will contain our email’s information:

import type { CreateEmailOptions } from "resend";

...
export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
  context.log(`Http function processed request for url "${request.url}"`);  
  const createEmailOptions: CreateEmailOptions = {
      to: ['some-recipient@email.com'],
      from: 'YourFrom <your-from@address.email',
      subject: 'Some Test Subject',
      react: <KoalaWelcomeEmail userFirstname="John" />
  }
}
....

It is the react property which will let us provide a React Component with props so that we can send that as our email.

3.3 Set up Resend

In order to be able to send an email via Resend we will need to set up the RESEND_API_KEY environment variable in our local.settings.json:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "",
    "FUNCTIONS_WORKER_RUNTIME": "node",
    "RESEND_API_KEY": "YOUR_KEY_HERE"
  }
}

With this we can expand our code by instanciating the Resend client and sending our email!

...
const resendInstance = new Resend(process.env.RESEND_API_KEY);

try {
    context.log("sending_email_via_resend", {
      to: createEmailOptions.to,
    });
    const response = await resendInstance.emails.send(createEmailOptions);

    if (response.error) {
      context.error("resend_email_error", {
        error: response.error.name,
        message: response.error.message,
      });

      throw new Error(response.error.message);
    }

    if (response.data) {
      context.log("resend_email_data", {
        data: response.data,
      });

      return { body: `Email success with id: ${response.data.id}!` };
    }

    context.warn("resend_no_error_no_data");
    return { body: "No error or data received" };
  } catch (error) {
    if (error instanceof Error) {
      context.error("failed_to_send_email", {
        message: error.message,
        error,
      });
      throw error;
    }

    context.error("failed_to_send_email_unknown_reason", {
      error,
    });

    throw new Error(`Unknown error: Failed to send email, ${error}`);
  }
...

With this code we set up a safe email sending procedure so that we can handle and log all errors if any occurs but more importantly we can send our email!

All is left now is testing the function locally by running it (e.g., using tools like Postman or curl) and deploying it to Azure (e.g., using the Azure CLI or Visual Studio Code).

Conclusion

By leveraging React Email, Resend, and Azure Functions, this guide demonstrates how to efficiently offload email rendering and sending from your front-end application to a serverless architecture. This approach not only improves the scalability and performance of your web app but also simplifies the process of creating dynamic, reusable email templates using React.

The combination of React Email for building templates, Resend for email delivery, and Azure Functions for serverless execution offers several key benefits:

Scalability: Offloading email tasks to Azure Functions ensures your front-end remains responsive, even during high traffic.
Maintainability: Using React components for email templates allows for better organization, reusability, and consistency in your email designs.
Error Handling: The guide provides a robust error-handling mechanism, ensuring that issues are logged and managed effectively.
Flexibility: The serverless nature of Azure Functions allows you to trigger email workflows from various sources, such as HTTP requests, timers, or other Azure services.

To take this further, you can expand the solution by adding more email templates, integrating with other triggers (e.g., database changes or event queues), or optimizing the deployment process for production environments. Testing locally and deploying to Azure are critical steps to ensure the solution works seamlessly in real-world scenarios.

By following this guide, you can build a scalable, maintainable, and efficient email-sending workflow that enhances your application’s overall performance and user experience.