Changelog


The release of Multi-Step forms for Makerkit opens up a world of possibilities for creating delightful onboarding experiences. In this post, we'll show you how to create a delightful onboarding experience using the Multi-Step Form Component for Makerkit.

While Makerkit Turbo does not include an Onboarding (customers in v1 were not interested in this feature), some customers are still needing this feature. In this post, I'll show you how easy it is with Makerkit.

The final result will be a multi-step form that guides users through the onboarding process, collecting information along the way:

<Video src="/assets/videos/onboarding-flow.mp4" />

## Differentiating between Onboarded and Non-Onboarded Users

First - we must be able to differentiate between onboarded and non-onboarded users. This can be done by checking if the user has completed the onboarding process. If they have, we can redirect them to the dashboard. If they haven't, we can show them the onboarding form.

To store this data, we can use the Supabase Auth `app_metadata` field. This field is a JSON object that can store any data you want (with limitations). In this case, we'll store a boolean value that indicates whether the user has completed the onboarding process.

### Checking if the User is Onboarded in the Middleware

To check if the user is onboarded, we add a check in the middleware. If the user is not onboarded, we redirect them to the onboarding page.

In your middleware, you can add the following code after the user has been fetched:

```tsx title="apps/web/app/middleware.ts" {19-23}
{
  pattern: new URLPattern({ pathname: '/home/*?' }),
  handler: async (req: NextRequest, res: NextResponse) => {
    const {
      data: { user },
    } = await getUser(req, res);

    const origin = req.nextUrl.origin;
    const next = req.nextUrl.pathname;

    // If user is not logged in, redirect to sign in page.
    if (!user) {
      const signIn = pathsConfig.auth.signIn;
      const redirectPath = `${signIn}?next=${next}`;

      return NextResponse.redirect(new URL(redirectPath, origin).href);
    }

    const isOnboarded = user?.app_metadata.onboarded;

    if (!isOnboarded) {
      return NextResponse.redirect(new URL('/onboarding', origin).href);
    }

    const supabase = createMiddlewareClient(req, res);

    const requiresMultiFactorAuthentication =
      await checkRequiresMultiFactorAuthentication(supabase);

    // If user requires multi-factor authentication, redirect to MFA page.
    if (requiresMultiFactorAuthentication) {
      return NextResponse.redirect(
        new URL(pathsConfig.auth.verifyMfa, origin).href,
      );
    }
  },
}
```

### Creating the Onboarding Page

With the middleware in place, we can now create the onboarding page. The onboarding page is where the user will complete the onboarding process. This page will contain the multi-step form that the user will fill out.

Let's create a page for the onboarding at `apps/web/app/onboarding/page.tsx`:

```tsx title="apps/web/app/onboarding/page.tsx"
import { AppLogo } from '~/components/app-logo';
import { OnboardingForm } from '~/onboarding/_components/onboarding-form';

export default function OnboardingPage() {
  return (
    <div className={'flex flex-1 flex-col h-screen items-center justify-center space-y-16'}>
      <AppLogo />

      <OnboardingForm />
    </div>
  );
}
```

NB: we don't have the `OnboardingForm` component yet, but we'll create it in the next section. Please leave it empty for now and then import it back.

#### Installing the package react-confetti

To make the onboarding experience more delightful, we can add some confetti animation when the user completes the onboarding process. We'll use the `react-confetti` package for this.

To install the package, run:

```bash
pnpm --filter web add react-confetti
```

### Creating the Multi-Step Form

Now that we have the onboarding page, we can create the multi-step form. The multi-step form will guide the user through the onboarding process, collecting the necessary information along the way.

To create the multi-step form, we'll use the Multi-Step Form Component for Makerkit. This component provides a simple API to create multi-step forms with ease.

In the onboarding form, we ask the user the following information:

1. Their full name
2. The name of the Team they want to create

We split the form into two steps, with each step collecting one piece of information - which is a good practice for onboarding forms and helps to reduce friction.

Now let's dive deep into the multi-step form implementation. We'll break down each part of the `OnboardingForm` component and explain its purpose and functionality.

### 1. Defining the Form Schema

First, we define the schema for our form using Zod:

```typescript
const FormSchema = createStepSchema({
  profile: z.object({
    name: z.string().min(1).max(255),
  }),
  team: z.object({
    name: z.string().min(1).max(255),
  }),
});
```

This schema defines two steps: 'profile' and 'team', each with a 'name' field. The `createStepSchema` function is a helper that ensures our schema is compatible with the Multi-Step Form component.

### 2. The OnboardingForm Component

The `OnboardingForm` component is the main container for our multi-step form:

```tsx
export function OnboardingForm() {
  const form = useForm({
    resolver: zodResolver(FormSchema),
    defaultValues: {
      profile: { name: '' },
      team: { name: '' },
    },
    mode: 'onBlur',
  });

  const onSubmit = useCallback((data: z.infer<typeof FormSchema>) => {
    console.log(data);
  }, []);

  return (
    <div>
      <MultiStepForm
        className={/* ... */}
        schema={FormSchema}
        form={form}
        onSubmit={onSubmit}
      >
        {/* Form content */}
      </MultiStepForm>
    </div>
  );
}
```

Here, we:
- Use `useForm` from react-hook-form to manage our form state
- Set up form validation using the Zod schema we defined
- Define an `onSubmit` callback (currently just logging the data)
- Render the `MultiStepForm` component, passing in our schema, form, and onSubmit handler

### 3. Form Header with Stepper

Inside the `MultiStepForm`, we first render a header with a stepper:

```tsx
<MultiStepFormHeader>
  <MultiStepFormContextProvider>
    {({ currentStepIndex }) => (
      <Stepper
        variant={'numbers'}
        steps={['Profile', 'Team', 'Complete']}
        currentStep={currentStepIndex}
      />
    )}
  </MultiStepFormContextProvider>
</MultiStepFormHeader>
```

This creates a visual indicator of progress through the form steps. The `MultiStepFormContextProvider` gives us access to the current step index, which we use to highlight the active step.

### 4. Form Steps

Next, we define each step of our form:

```tsx
<MultiStepFormStep name={'profile'}>
  <ProfileStep />
</MultiStepFormStep>

<MultiStepFormStep name={'team'}>
  <TeamStep />
</MultiStepFormStep>

<MultiStepFormStep name={'complete'}>
  <CompleteStep />
</MultiStepFormStep>
```

Each `MultiStepFormStep` corresponds to a step in our form schema. The `name` prop should match the keys in our schema.

### 5. The Profile Step

The `ProfileStep` component renders the first step of our form:

```tsx
function ProfileStep() {
  const { nextStep, form } = useMultiStepFormContext();

  return (
    <Form {...form}>
      <div className={'flex flex-col space-y-6'}>
        {/* Welcome text */}
        <FormField
          render={({ field }) => (
            <FormItem>
              <FormLabel>Your Name</FormLabel>
              <FormControl>
                <Input {...field} placeholder={'Name'} />
              </FormControl>
              <FormDescription>Enter your full name here</FormDescription>
            </FormItem>
          )}
          name={'profile.name'}
        />
        <div className={'flex justify-end'}>
          <Button onClick={nextStep}>Continue</Button>
        </div>
      </div>
    </Form>
  );
}
```

This step:
- Uses the `useMultiStepFormContext` hook to access form utilities
- Renders a form field for the user's name
- Provides a 'Continue' button to move to the next step

### 6. The Team Step

The `TeamStep` component is similar to the `ProfileStep`, but adds team creation functionality:

```tsx
function TeamStep() {
  const { nextStep, prevStep, form, mutation } = useMultiStepFormContext();

  return (
    <Form {...form}>
      {/* Similar structure to ProfileStep */}
      <div className={'flex justify-end space-x-2'}>
        <Button variant={'ghost'} onClick={prevStep}>
          Go Back
        </Button>
        <Button
          onClick={async (e) => {
            await mutation.mutateAsync();
            nextStep(e);
          }}
        >
          {mutation.isPending ? 'Processing...' : 'Create Team'}
        </Button>
      </div>
    </Form>
  );
}
```

This step adds:
- A 'Go Back' button to return to the previous step
- A 'Create Team' button that triggers a mutation (e.g., to create the team in your backend) before moving to the next step

The `mutation` object uses `useMutation` from React Query and provides utilities for handling asynchronous operations, which is very useful when you need additional control over form submission.

### 7. The Complete Step

The `CompleteStep` component renders the final step of our form:

```tsx
function CompleteStep() {
  const { form } = useMultiStepFormContext();

  return (
    <div className={'flex flex-col space-y-6'}>
      {/* Completion message */}
      <Button asChild>
        <Link href={'/home'}>Finish</Link>
      </Button>
    </div>
  );
}
```

This step:
- Displays a completion message, including the user's name from the form data
- Provides a 'Finish' button that links to the home page

### Handling Form Submission

Finally, we handle form submission in the `onSubmit` callback. In this function, we will execute a Server Action to update the user profile, create the team, and mark the user as onboarded.

```tsx title="apps/web/app/onboarding/_lib/server/server-actions.ts"
'use server';

import { z } from 'zod';

import { enhanceAction } from '@kit/next/actions';
import { getSupabaseServerActionClient } from '@kit/supabase/server-actions-client';
import { getSupabaseServerComponentClient } from '@kit/supabase/server-component-client';

export const submitOnboardingFormAction = enhanceAction(
  async (data, user) => {
    const client = getSupabaseServerComponentClient();

    const createTeamResponse = await client.rpc('create_team_account', {
      account_name: data.team.name,
    });

    if (createTeamResponse.error) {
      throw new Error(
        `Failed to create team: ${createTeamResponse.error.message}`,
      );
    }

    const profileResponse = await client
      .from('accounts')
      .update({
        name: data.profile.name,
      })
      .eq('id', user.id);

    if (profileResponse.error) {
      throw new Error(
        `Failed to update profile: ${profileResponse.error.message}`,
      );
    }

    const adminClient = getSupabaseServerActionClient({ admin: true });

    await adminClient.auth.admin.updateUserById(user.id, {
      app_metadata: {
        onboarded: true,
      },
    });

    return {
      success: true,
    };
  },
  {
    auth: true,
    schema: z.object({
      profile: z.object({
        name: z.string().min(1).max(255),
      }),
      team: z.object({
        name: z.string().min(1).max(255),
      }),
    }),
  },
);
```

This action updates the user's profile, creates the team, and marks the user as onboarded. It uses the `enhanceAction` helper to handle authentication and validation.

This is just an example - your onboarding process may involve different steps or actions. You can customize the `submitOnboardingFormAction` to suit your specific requirements.

### Integrating the Server Action

Let's now integrate the `submitOnboardingFormAction` with our form submission:

```tsx title="apps/web/app/onboarding/onboarding-form.tsx"
import { submitOnboardingFormAction } from './_lib/server/server-actions';
```

```tsx title="apps/web/app/onboarding/onboarding-form.tsx"
const onSubmit = useCallback(async (data: z.infer<typeof FormSchema>) => {
  try {
    await submitOnboardingFormAction(data);
  } catch (error) {
    console.error('Failed to submit form:', error);
  }
}, []);
```

### Putting It All Together

With all the pieces in place, our `OnboardingForm` component looks like this:

```tsx title="apps/web/app/onboarding/onboarding-form.tsx"
'use client';

import { useCallback } from 'react';

import { createPortal } from 'react-dom';

import dynamic from 'next/dynamic';
import Link from 'next/link';

import { zodResolver } from '@hookform/resolvers/zod';
import { useForm } from 'react-hook-form';
import { z } from 'zod';

import { Button } from '@kit/ui/button';
import {
  Form,
  FormControl,
  FormDescription,
  FormField,
  FormItem,
  FormLabel,
} from '@kit/ui/form';
import { Input } from '@kit/ui/input';
import {
  MultiStepForm,
  MultiStepFormContextProvider,
  MultiStepFormHeader,
  MultiStepFormStep,
  createStepSchema,
  useMultiStepFormContext,
} from '@kit/ui/multi-step-form';
import { Stepper } from '@kit/ui/stepper';

import { submitOnboardingFormAction } from '~/onboarding/_lib/server/server-actions';

const Confetti = dynamic(
  () => {
    return import('react-confetti');
  },
  {
    ssr: false,
  },
);

const FormSchema = createStepSchema({
  profile: z.object({
    name: z.string().min(1).max(255),
  }),
  team: z.object({
    name: z.string().min(1).max(255),
  }),
});

export function OnboardingForm() {
  const form = useForm({
    resolver: zodResolver(FormSchema),
    defaultValues: {
      profile: {
        name: '',
      },
      team: {
        name: '',
      },
    },
    mode: 'onBlur',
  });

  const onSubmit = useCallback(async (data: z.infer<typeof FormSchema>) => {
    try {
      await submitOnboardingFormAction(data);
    } catch (error) {
      console.error('Failed to submit form:', error);
    }
  }, []);

  return (
    <div>
      <MultiStepForm
        className={
          'w-full max-w-md space-y-8 rounded-lg border p-8 shadow-sm duration-500 animate-in fade-in-90 zoom-in-95 slide-in-from-bottom-12'
        }
        schema={FormSchema}
        form={form}
        onSubmit={onSubmit}
      >
        <MultiStepFormHeader>
          <MultiStepFormContextProvider>
            {({ currentStepIndex }) => (
              <Stepper
                variant={'numbers'}
                steps={['Profile', 'Team', 'Complete']}
                currentStep={currentStepIndex}
              />
            )}
          </MultiStepFormContextProvider>
        </MultiStepFormHeader>

        <MultiStepFormStep name={'profile'}>
          <ProfileStep />
        </MultiStepFormStep>

        <MultiStepFormStep name={'team'}>
          <TeamStep />
        </MultiStepFormStep>

        <MultiStepFormStep name={'complete'}>
          <CompleteStep />
        </MultiStepFormStep>
      </MultiStepForm>
    </div>
  );
}

function ProfileStep() {
  const { nextStep, form } = useMultiStepFormContext();

  return (
    <Form {...form}>
      <div className={'flex flex-col space-y-6'}>
        <div className={'flex flex-col space-y-2'}>
          <h1 className={'text-xl font-semibold'}>Welcome to Makerkit</h1>

          <p className={'text-sm text-muted-foreground'}>
            Welcome to the onboarding process! Let&apos;s get started by
            entering your name.
          </p>
        </div>

        <FormField
          render={({ field }) => {
            return (
              <FormItem>
                <FormLabel>Your Name</FormLabel>

                <FormControl>
                  <Input {...field} placeholder={'Name'} />
                </FormControl>

                <FormDescription>Enter your full name here</FormDescription>
              </FormItem>
            );
          }}
          name={'profile.name'}
        />

        <div className={'flex justify-end'}>
          <Button onClick={nextStep}>Continue</Button>
        </div>
      </div>
    </Form>
  );
}

function TeamStep() {
  const { nextStep, prevStep, form, mutation } = useMultiStepFormContext();

  return (
    <Form {...form}>
      <div className={'flex flex-col space-y-6'}>
        <div className={'flex flex-col space-y-2'}>
          <h1 className={'text-xl font-semibold'}>Create Your Team</h1>

          <p className={'text-sm text-muted-foreground'}>
            Let&apos;s create your team. Enter your team name below.
          </p>
        </div>

        <FormField
          render={({ field }) => {
            return (
              <FormItem>
                <FormLabel>Your Team Name</FormLabel>

                <FormControl>
                  <Input {...field} placeholder={'Name'} />
                </FormControl>

                <FormDescription>
                  This is the name of your team.
                </FormDescription>
              </FormItem>
            );
          }}
          name={'team.name'}
        />

        <div className={'flex justify-end space-x-2'}>
          <Button
            disabled={mutation.isPending}
            variant={'ghost'}
            onClick={prevStep}
          >
            Go Back
          </Button>

          <Button
            onClick={async (e) => {
              await mutation.mutateAsync();

              nextStep(e);
            }}
          >
            {mutation.isPending ? 'Processing...' : 'Create Team'}
          </Button>
        </div>
      </div>
    </Form>
  );
}

function CompleteStep() {
  const { form } = useMultiStepFormContext();

  return (
    <div className={'flex flex-col space-y-6'}>
      {createPortal(<Confetti numberOfPieces={500} recycle={false} />, document.body)}

      <div className={'flex flex-col space-y-2'}>
        <h1 className={'text-xl font-semibold'}>
          Hello, {form.getValues('profile').name}!
        </h1>

        <p className={'text-sm text-muted-foreground'}>
          You&apos;re almost done! Click the button below to finish the
          onboarding process.
        </p>
      </div>

      <Button asChild>
        <Link href={'/home'}>Finish</Link>
      </Button>
    </div>
  );
}
```

## Conclusion

By leveraging Makerkit's Multi-Step Form component, we've created a smooth, intuitive onboarding process. This approach:

1. Breaks down the onboarding into manageable steps
2. Provides clear visual feedback on progress
3. Allows for easy validation and error handling
4. Creates a flexible structure that can be easily extended or modified

With this onboarding flow in place, you're well on your way to creating a delightful first-time user experience that sets the tone for your entire application. Happy onboarding!

Creating a Delightful Onboarding Experience with Multi-Step Forms


I am super excited to announce the release of the Multi-Step Form Component for Makerkit. This component allows you to create multi-step forms with ease.

If you want to know how it's implemented, check out the [blog post that explains how to use the Multi-Step Form Component](multi-step-forms-reactjs) in your projects.

## Usage of the Multi-Step Form Component

The component is a wrapper around React Hook Form, Zod and Shadcn UI - it provides a simple API to create multi-step forms with ease.

<Video src="/assets/videos/multi-step-demo.mp4" />

Here's a simple example of how you can use the Multi-Step Form Component, which we use in conjunction with our built-in `Stepper` component:

```tsx
'use client';

import { zodResolver } from '@hookform/resolvers/zod';
import { useForm } from 'react-hook-form';
import { z } from 'zod';

import { Button } from '@kit/ui/button';
import {
  Form,
  FormControl,
  FormField,
  FormItem,
  FormLabel,
  FormMessage,
} from '@kit/ui/form';
import { Input } from '@kit/ui/input';
import {
  MultiStepForm,
  MultiStepFormContextProvider,
  MultiStepFormHeader,
  MultiStepFormStep,
  createStepSchema,
  useMultiStepFormContext,
} from '@kit/ui/multi-step-form';
import { Stepper } from '@kit/ui/stepper';

const FormSchema = createStepSchema({
  account: z.object({
    username: z.string().min(3),
    email: z.string().email(),
  }),
  profile: z.object({
    password: z.string().min(8),
    age: z.coerce.number().min(18),
  }),
});

type FormValues = z.infer<typeof FormSchema>;

export function MultiStepFormDemo() {
  const form = useForm<FormValues>({
    resolver: zodResolver(FormSchema),
    defaultValues: {
      account: {
        username: '',
        email: '',
      },
      profile: {
        password: '',
      },
    },
    reValidateMode: 'onBlur',
    mode: 'onBlur',
  });

  const onSubmit = (data: FormValues) => {
    console.log('Form submitted:', data);
  };

  return (
    <MultiStepForm
      className={'space-y-10 p-8 rounded-xl border'}
      schema={FormSchema}
      form={form}
      onSubmit={onSubmit}
    >
      <MultiStepFormHeader
        className={'flex w-full flex-col justify-center space-y-6'}
      >
        <h2 className={'text-xl font-bold'}>Create your account</h2>

        <MultiStepFormContextProvider>
          {({ currentStepIndex }) => (
            <Stepper
              variant={'numbers'}
              steps={['Account', 'Profile', 'Review']}
              currentStep={currentStepIndex}
            />
          )}
        </MultiStepFormContextProvider>
      </MultiStepFormHeader>

      <MultiStepFormStep name="account">
        <AccountStep />
      </MultiStepFormStep>

      <MultiStepFormStep name="profile">
        <ProfileStep />
      </MultiStepFormStep>

      <MultiStepFormStep name="review">
        <ReviewStep />
      </MultiStepFormStep>
    </MultiStepForm>
  );
}

function AccountStep() {
  const { form, nextStep, isStepValid } = useMultiStepFormContext();

  return (
    <Form {...form}>
      <div className={'flex flex-col gap-4'}>
        <FormField
          name="account.username"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Username</FormLabel>
              <FormControl>
                <Input {...field} />
              </FormControl>
              <FormMessage />
            </FormItem>
          )}
        />

        <FormField
          name="account.email"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Email</FormLabel>
              <FormControl>
                <Input type="email" {...field} />
              </FormControl>
              <FormMessage />
            </FormItem>
          )}
        />

        <div className="flex justify-end">
          <Button onClick={nextStep} disabled={!isStepValid()}>
            Next
          </Button>
        </div>
      </div>
    </Form>
  );
}

function ProfileStep() {
  const { form, nextStep, prevStep } = useMultiStepFormContext();

  return (
    <Form {...form}>
      <div className={'flex flex-col gap-4'}>
        <FormField
          name="profile.password"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Password</FormLabel>
              <FormControl>
                <Input type="password" {...field} />
              </FormControl>
              <FormMessage />
            </FormItem>
          )}
        />

        <FormField
          name="profile.age"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Age</FormLabel>
              <FormControl>
                <Input type="number" {...field} />
              </FormControl>
              <FormMessage />
            </FormItem>
          )}
        />

        <div className="flex justify-end space-x-2">
          <Button type={'button'} variant={'outline'} onClick={prevStep}>
            Previous
          </Button>

          <Button onClick={nextStep}>Next</Button>
        </div>
      </div>
    </Form>
  );
}

function ReviewStep() {
  const { prevStep, form } = useMultiStepFormContext<typeof FormSchema>();
  const values = form.getValues();

  return (
    <div className={'flex flex-col space-y-4'}>
      <div className={'flex flex-col space-y-4'}>
        <div>Great! Please review the values.</div>

        <div className={'flex flex-col space-y-2 text-sm'}>
          <div>
            <span>Username</span>: <span>{values.account.username}</span>
          </div>
          <div>
            <span>Email</span>: <span>{values.account.email}</span>
          </div>
          <div>
            <span>Age</span>: <span>{values.profile.age}</span>
          </div>
        </div>
      </div>

      <div className="flex justify-end space-x-2">
        <Button type={'button'} variant={'outline'} onClick={prevStep}>
          Back
        </Button>

        <Button type={'submit'}>Create Account</Button>
      </div>
    </div>
  );
}
```

In the example above we have a simple multi-step form with three steps: `account`, `profile` and `review`. Each step is a separate component that renders the form fields for that step.

The `MultiStepForm` component takes care of managing the form state and transitions between steps. It also provides a simple API to access the form state and navigate between steps.

I hope you enjoy using the Multi-Step Form Component as much as I enjoyed building it. If you have any feedback or suggestions, feel free to reach out to on our Discord!

Introducing the Multi-Step Form Component for Makerkit

Tutorials

Building Multi-Step forms with React.js


Next.js offers powerful middleware capabilities for handling requests before they complete - allowing you to execute custom logic, modify responses, and more.

One particularly useful technique in Next.js middleware is leveraging URL patterns to execute specific logic based on the requested route.

This guide will walk you through implementing and optimizing URL pattern matching in your Next.js application, helping you create more efficient and maintainable server-side logic.

## Introduction to URL Pattern API

The URL Pattern API provides a powerful way to match URLs or parts of URLs against a template. It's based on the syntax from the path-to-regexp library, which is similar to routing systems in popular frameworks like Express or Ruby on Rails.

### Key Features of URL Pattern API:

1. Literal Matching: Match exact strings in URLs.
2. Wildcards: Use * to match any character.
3. Named Groups: Extract parts of the URL with :name syntax.
4. Regular Expressions: Use custom regex for more complex matching.
5. Modifiers: Make parts optional (?), repeatable (+), or both (*).

### Basic Syntax Overview

Here's a quick look at some common URL Pattern syntax:

```
/books: Matches this exact path
/books/*: Matches any path starting with /books/
/books/:id: Matches paths like /books/123 and captures 123 as id
/books/:id(\\d+): Matches paths where id is one or more digits
/books/:title?: Makes the title parameter optional
/authors/:name+: Matches one or more path segments for name
```

Now, let's dive into implementing URL patterns in Next.js middleware.

## Implementing URL Pattern Matching in Next.js Middleware

Let's dive into a step-by-step implementation of URL pattern matching in your Next.js middleware:

```typescript
import { NextResponse, URLPattern } from 'next/server';
import type { NextRequest } from 'next/server';

// Define patterns and corresponding handlers
function getNextJsPatterns() {
  return [
    {
      pattern: new URLPattern({ pathname: '/admin/*?' }),
      handler: handleNextJsAdminRoutes,
    },
    {
      pattern: new URLPattern({ pathname: '/auth/*?' }),
      handler: handleNextJsAuthRoutes,
    },
    // Add more Next.js-specific patterns as needed
  ];
}

// Match URL to a defined pattern
function matchNextJsUrlPattern(url: string) {
  const patterns = getNextJsPatterns();
  const input = url.split('?')[0]; // Strip query parameters

  for (const pattern of patterns) {
    if (pattern.pattern.exec(input) !== null) {
      return pattern.handler;
    }
  }
}

// Next.js middleware function
export async function middleware(request: NextRequest) {
  const response = NextResponse.next();

  const handlePattern = matchNextJsUrlPattern(request.url);

  if (handlePattern) {
    const patternHandlerResponse = await handlePattern(request, response);

    if (patternHandlerResponse) {
      return patternHandlerResponse;
    }
  }

  return response;
}
```

## Dissecting the Next.js Middleware Implementation

1. **Pattern Definition**: The `getNextJsPatterns` function returns an array of pattern objects. Each object contains a `URLPattern` and its corresponding handler function, allowing for easy management of different Next.js routes.
2. **Pattern Matching**: The `matchNextJsUrlPattern` function takes a URL, removes query parameters, and checks it against the defined patterns. When a match is found, it returns the appropriate handler for that Next.js route.
3. **Middleware Execution**: In the main `middleware` function, we call `matchNextJsUrlPattern`. If a handler is returned, we execute it and return its response, allowing for route-specific logic in our Next.js application.

This setup leverages the web standard URL Pattern API to define different patterns and their corresponding handlers. The middleware function checks each request against these standardized patterns and executes the appropriate handler when a match is found.

By using this web standard approach in your Next.js middleware, you gain several advantages:

1. **Standardized Matching**: The URL Pattern API provides a consistent, well-defined way to match URLs.
Future-Proof: As a web standard, it's likely to be supported and improved over time.
2. **Performance**: Being a native web API, it can offer better performance than custom regex solutions.
3. **Readability**: The syntax is clear and expressive, making your routing logic easy to understand.

## Example Next.js Route Handlers

Let's explore some example handlers for common Next.js scenarios:

```typescript
async function handleNextJsAdminRoutes(
  request: NextRequest,
  response: NextResponse
) {
  // Verify admin status
  const user = await getNextJsUser(request);

  if (!user || user.role !== 'admin') {
    return NextResponse.redirect(new URL('/404', request.url));
  }

  return response;
}

async function handleNextJsAuthRoutes(
  request: NextRequest,
  response: NextResponse
) {
  const user = await getNextJsUser(request);

  if (user && !request.nextUrl.pathname.includes('/verify-mfa')) {
    return NextResponse.redirect(new URL('/dashboard', request.url));
  }

  return response;
}
```

These handlers demonstrate how to perform specific checks and redirects based on user status and requested paths in a Next.js application.

## Advantages of URL Pattern Matching in Next.js

Implementing URL pattern matching in Next.js middleware offers several key advantages:

1. **Enhanced Modularity**: Easily add or modify patterns without altering core Next.js middleware logic.
2. **Improved Code Organization**: Keep your Next.js middleware clean and easy to understand.
3. **Increased Flexibility**: Handle complex Next.js routing scenarios without cluttering your middleware.
4. **Better Performance**: By executing only relevant code for each route, you can potentially improve your Next.js application's performance.

## Best Practices for Next.js Middleware

When working with URL patterns in Next.js middleware, consider the following best practices:

1. **Keep it Light**: Middleware runs on every request, so keep processing minimal to maintain Next.js performance.
2. **Error Handling**: Implement robust error handling in your middleware to prevent crashes in your Next.js application.
3. **Caching**: Where appropriate, implement caching strategies to improve the performance of your Next.js middleware.
4. **Split Logic**: If your middleware grows too complex, consider splitting it into multiple functions or files for better maintainability.

## Conclusion

Mastering URL patterns in Next.js middleware opens up a world of possibilities for creating more organized, flexible, and powerful request handling in your applications. By implementing these techniques, you can significantly improve the structure and maintainability of your Next.js projects.

Remember, while this approach offers great benefits, it's crucial to keep your Next.js middleware efficient. Heavy processing in middleware can impact your application's performance, so use these techniques judiciously and always profile your Next.js application to ensure optimal performance.

By following these guidelines and best practices, you'll be well on your way to creating robust, efficient, and scalable Next.js applications. Happy Next.js coding! 🚀


Mastering URL Patterns in Next.js Middleware: A Comprehensive Guide


Paginating data is a common task in web development. In this article, we learn how to paginate data with [Supabase](https://supabase.com) and React.js, and then render the data in a table using [React Table](https://tanstack.com/table/v8), likely the best table library for React.js.

## Prerequisites

We assume you have a basic understanding of React.js and Supabase, and a bare-bones codebase to work with. We also assume you have a Supabase project set up and a table with some data in it.

In our example, we will be fetching data from a PostgreSQL table called `organizations`, then proceed to paginate the data and render it in a table. 

The pagination is driven a `page` query parameter, set using the utilities provided by React Table. Fetching the data can be done in various ways depending on which framework you will be using, such as Remix or Next.js. For simplicity, we will fetch the data simply using the `supabase-js` library.

## Fetching the data

We will be using the `supabase-js` library to fetch the data from the `organizations` table.

Our `getOrganizations` function will take two parameters, the `client` and the `params` object. The `client` is the Supabase client, and the `params` object contains the `from` and `to` index of the data to fetch:

```tsx
export async function getOrganizations(
  client: Client,
  params: {
    from: number;
    to: number;
  }
) {
  return await client
    .from('organizations')
    .select('*')
    .range(params.from, params.to);
}
```

Assuming we're fetching this data in a React component, we can then call the `getOrganizations` function:

```tsx
const ITEMS_PER_PAGE = 10;

function OrganizationsDataProvider(
  props: React.PropsWithChildren<{
    page: number;
  }>
) {
  const [state, setState] = useState({
    loading: true,
    error: undefined,
    data: undefined,
  });

  // Get the Supabase client
  const client = useSupabase();

  useEffect(() => {
    async function fetchOrganizations() {
      try {
        setState({
          loading: true,
          error: undefined,
          data: undefined,
        });

        const from = props.page * ITEMS_PER_PAGE;
        const to = from + ITEMS_PER_PAGE;

        const { data, error } = await getOrganizations(client, {
          from,
          to,
        });

        if (error) {
          throw error;
        }

        setState({
          loading: false,
          error: undefined,
          data,
        });
      } catch (error) {
        setState({
          loading: false,
          error,
          data: undefined,
        });
      }
    }

    fetchOrganizations();
  }, [client, page]);

  return (
    <OrganizationsTable organizations={organizations} />
  );
```

As you can see in the code above, we receive the `page` parameter from the parent component, and then use it to calculate the `from` and `to` index of the data to fetch. We then call the `getOrganizations` function, and pass the `client` and the `from` and `to` index as parameters.

The `page` parameter will ideally be passed from the URL, so we can simply update the page by changing the URL.

For example, if we're using Next.js, we can use the `useRouter` hook to get the `page` parameter from the URL:

```tsx
import { useRouter } from 'next/router';  

function OrganizationsPage() {
  const router = useRouter();
  const page = router.query.page || 0;

  return (
    <OrganizationsDataProvider page={page} />
  );
}
```

## Paginating the data

Now that we have the data, we define the component `OrganizationsTable` to render the table to paginate the data.

```tsx
function OrganizationsTable(
  props: React.PropsWithChildren<{
    organizations: Organization[];
  }>
) {
  const columns = useMemo(() => {
    return [
      {
        id: 'id',
        header: 'Id',
        accessorKey: 'id',
        cell: (ctx) => ctx.getValue(),
      },
      {
        id: 'name',
        header: 'Name',
        accessorKey: 'name',
        cell: (ctx) => ctx.getValue(),
      },
    ];
  }, []);

  return (
    <Table 
      data={organizations} 
      columns={columns} 
      onPaginationChange={({ pageIndex }) => {
        // update the search params with page=pageIndex
        // this will trigger a re-render of the component
        // and fetch the data for the new page
      }}
   />
  );
}
```

As you can see, the `onPaginationChange` callback is called when the user changes the page. We can then update the `page` query parameter in the URL, which will trigger a re-render of the component and fetch the data for the new page. 

Depending on the router you're using, you can use the `useRouter` hook from `next/router` or `useLocation` hook from `react-router-dom`, or `setSearchParams` from `remix`.

## Building the Table component

We've built the Table component using React Table, which is a great library for building tables in React.js. 

If you're looking for the full source code, here is where you can read it: [Reusable Table component with React Table](/snippets/reusable-table-component-reactjs).

## Alternative approaches with SSR

The alternative approach, which is likely the best one, is to load the data from the server, and then pass it to the client. This also makes it easier to restrict the maximum amount of items to fetch.

## Example: fetching data with Next.js

For example, if we're using Next.js, we can use the `getServerSideProps` 
function to fetch the data from the server, and then pass it to the client:

```tsx
const ITEMS_PER_PAGE = 20;

export async function getServerSideProps(ctx) {
  const page = ctx.query.page || 0;
  const client = getSupabaseServerClient(); // you will have to implement this

  const from = page * ITEMS_PER_PAGE;
  const to = from + ITEMS_PER_PAGE;

  const { data: organizations, error } = await getOrganizations(client, {
    from,
    to,
  });

  if (error) {
    return ctx.res.status(500).end();
  }

  return {
    props: {
      organizations
    },
  };
}
```

Then, you could fully skip the `OrganizationsDataProvider` component, and simply pass the `organizations` prop to the `OrganizationsTable` component:

```tsx
function OrganizationsPage(props) {
  return (
    <OrganizationsTable organizations={props.organizations} />
  );
}
```

## Example: fetching data with Remix

If you're using Remix, you can use the `useLoaderData` hook to fetch the data from the `loader` function, and then pass it to the client:

```tsx
const ITEMS_PER_PAGE = 20;  

export async function loader({ request }: LoaderArgs) {
  const page = new URL(request.url).searchParams.get('page') || 0;
  const client = getSupabaseServerClient(); // you will have to implement this

  const from = page * ITEMS_PER_PAGE;
  const to = from + ITEMS_PER_PAGE;

  const { data: organizations, error } = await getOrganizations(client, {
    from,
    to,
  });

  if (error) {
    return new Response(`Could not load data`, { status: 500 });
  }

  return json({ organizations });
}

export default function OrganizationsPage() {
  const data = useLoaderData<typeof loader>();

  return (
    <OrganizationsTable organizations={data.organizations} />
  );
}
```

## Example: fetching data with Next.js 13 Server Components

If you're using Next.js 13 with Server Components, you can use the `use` hook to fetch the data from the Server Component and pass it down to the client components:

```tsx
function OrganizationsPage() {
  const { data, error } = use(
    getOrganizations(client, {
      from,
      to,
    })
  );

  if (error) {
    return <div>Could not load data</div>;
  }

  return (
    <OrganizationsTable organizations={data} />
  );
}
```

## Conclusion

In this article, we've seen how to fetch paginated data from a Supabase database, and then paginate the data using React Table. 

We've also seen how to fetch the data from the server, and then pass it to the client using Next.js, Remix, and Next.js 13 Server Components.

If you have any questions, feel free to contact me in our Discord Server!

React

Tutorials and Guides about React

Creating a Delightful Onboarding Experience with Multi-Step Forms

Introducing the Multi-Step Form Component for Makerkit

Building Multi-Step forms with React.js

Mastering URL Patterns in Next.js Middleware: A Comprehensive Guide

Pagination with React.js and Supabase

How to use MeiliSearch with React