> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.makeswift.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.makeswift.com/_mcp/server.

# MakeswiftApiHandler

> An API route for Makeswift that adds support for [preview mode](https://nextjs.org/docs/pages/building-your-application/configuring/preview-mode), [on-demand revalidation](https://nextjs.org/docs/pages/building-your-application/data-fetching/incremental-static-regeneration#on-demand-revalidation), and other features that make Makeswift work seamlessly with your Next.js app.

An API route for Makeswift that adds support for [preview mode](https://nextjs.org/docs/pages/building-your-application/configuring/preview-mode), [on-demand revalidation](https://nextjs.org/docs/pages/building-your-application/data-fetching/incremental-static-regeneration#on-demand-revalidation), and other features that make Makeswift work seamlessly with your Next.js app.

## Arguments

**`apiKey`** `string` — required

The API key for the Makeswift site.

---

**`options`** `object` — required

Options for site version and locale.

#### properties

**`runtime`** `ReactRuntime` — required

An instance of [ReactRuntime](/developer/docs/reference/reactruntime/constructor)

---

**`getFonts`** `() => FontFamily[]`

This function is called when the builder requests the list of fonts available for the site. The function should return an array of `FontFamily` objects.

```ts
type FontFamily {
  family: string
  variants: {
    weight: string
    style: "normal" | "italic"
    src?: string
  }[]
}
```

The `src` field is used to preview the font in the builder. The `src` field can be either a relative or absolute URL. If the `src` field is omitted, the font is still selectable but uses a fallback font in the builder.

---

**`events`** `object`

> **Note**
>
> New in [v0.23.12](https://github.com/makeswift/makeswift/releases/tag/%40makeswift%2Fruntime%400.23.12)

An object containing event handlers for the Makeswift site.

### Available events

**`events.onPublish`** `() => void | Promise<void>`

If defined, this function is called when the site is published.

#### Error handling

Any errors thrown in the event handler will be logged and ignored.

#### Local development

Since onPublish is powered by Makeswift webhooks, it's not possible to test them locally (e.g., localhost:3000) at this time. We have plans to enable this via tunneling by leveraging the Makeswift CLI but don't have that ready just yet.

---

---

---

## Examples

### App Router

**`src/app/api/makeswift/[...makeswift]/route.ts`**

```tsx src/app/api/makeswift/[...makeswift]/route.ts
import { MakeswiftApiHandler } from "@makeswift/runtime/next/server";
import { strict } from "assert";

import { runtime } from "@/makeswift/runtime";

// make custom components' data available for introspection
import "@/makeswift/components";

strict(
  process.env.MAKESWIFT_SITE_API_KEY,
  "MAKESWIFT_SITE_API_KEY is required"
);

const handler = MakeswiftApiHandler(process.env.MAKESWIFT_SITE_API_KEY, {
  runtime,
});

export { handler as GET, handler as POST, handler as OPTIONS };
```

### Pages router

**`src/pages/api/makeswift/[...makeswift].ts`**

```ts src/pages/api/makeswift/[...makeswift].ts
import { MakeswiftApiHandler } from "@makeswift/runtime/next/server";
import { strict } from "assert";

import { runtime } from "@/makeswift/runtime";

// make custom components' data available for introspection
import "@/makeswift/components";

strict(
  process.env.MAKESWIFT_SITE_API_KEY,
  "MAKESWIFT_SITE_API_KEY is required"
);

export default MakeswiftApiHandler(process.env.MAKESWIFT_SITE_API_KEY, {
  runtime,
});
```

### Adding fonts

The following example adds *Spline Sans* and *Spline Sans Mono* Google Fonts to the site using `next/font` and adds them to the `MakeswiftApiHandler`.

For more information on adding fonts to your Next.js app, see our [Adding Fonts](/developer/docs/guides/how-to/add-custom-fonts) guide.

> **Note**
>
> We recommend using variable fonts as they reduce the number of font files requested.

**`pages/api/[...makeswift].ts`**

```ts pages/api/[...makeswift].ts
import { MakeswiftApiHandler } from "@makeswift/runtime/next/server";
import { strict } from "assert";

import { runtime } from "@/makeswift/runtime";

strict(
  process.env.MAKESWIFT_SITE_API_KEY,
  "MAKESWIFT_SITE_API_KEY is required"
);

export default MakeswiftApiHandler(process.env.MAKESWIFT_SITE_API_KEY, {
  runtime,
  getFonts() {
    return [
      {
        family: "Spline Sans",
        variants: [
          {
            weight: "300",
            style: "normal",
          },
          {
            weight: "400",
            style: "normal",
          },
          {
            weight: "500",
            style: "normal",
          },
        ],
      },
      {
        family: "Spline Sans Mono",
        variants: [
          {
            weight: "500",
            style: "normal",
          },
        ],
      },
    ];
  },
});
```

**`_app.tsx`**

```tsx _app.tsx
import { AppProps } from "next/app";
import { Spline_Sans, Spline_Sans_Mono } from "next/font/google";

import clsx from "clsx";

import "../styles/globals.css";

const splineSans = Spline_Sans({
  subsets: ["latin"],
  variable: "--font-sans",
  fallback: [
    "system-ui",
    "-apple-system",
    "BlinkMacSystemFont",
    "Helvetica",
    "Arial",
    "sans-serif",
  ],
});
const splineSansMono = Spline_Sans_Mono({
  subsets: ["latin"],
  variable: "--font-mono",
  fallback: ["Courier New"],
});

function MyApp({ Component, pageProps }: AppProps) {
  return (
    <main className={clsx(splineSans.variable, splineSansMono.variable)}>
      <Component {...pageProps} />
    </main>
  );
}

export default MyApp;
```

### Using `onPublish` event

**`src/app/api/makeswift/[...makeswift]/route.ts`**

```ts src/app/api/makeswift/[...makeswift]/route.ts
import { MakeswiftApiHandler } from "@makeswift/runtime/next/server";
import { strict } from "assert";

import { runtime } from "@/makeswift/runtime";

strict(
  process.env.MAKESWIFT_SITE_API_KEY,
  "MAKESWIFT_SITE_API_KEY is required"
);

const handler = MakeswiftApiHandler(process.env.MAKESWIFT_SITE_API_KEY, {
  runtime,
  events: {
    onPublish() {
      console.log(`Published content`);
    },
  },
});

export { handler as GET, handler as POST, handler as OPTIONS };
```