Pages Router

The fastest way to get started with Makeswift on a new Next.js project is to follow the quickstart guide. If you have an existing Next.js application or want to set things up yourself, continue with the rest of this guide.

System requirements

Node.js 20.19 or a later version.
macOS, Windows (including WSL), and Linux are supported.

If you don’t already have a Next.js project, head over to the Next.js documentation to get one set up. If you do have one, please verify you are using Next.js 13.4 or a later version.

This code in this guide assumes you are using a src directory and have the following path aliases configured.

tsconfig.json

1 {
2   "compilerOptions": {
3     "baseUrl": ".",
4     "paths": {
5       "@/*": ["src/*"]
6     }
7   }
8 }

If your setup varies from this, please adjust the code snippets appropriately.

Install dependencies

Install the @makeswift/runtime package. This package contains all of the necessary code to integrate Makeswift into your Next.js app.

$ npm install @makeswift/runtime

Add API key to environment variables

Requesting data through the Makeswift client requires a site API key from Makeswift. In the Makeswift builder, go to Settings > Host and copy the API key for the site.

Once the API key is in your clipboard, open your .env.local file and paste the snippet below.

1 MAKESWIFT_SITE_API_KEY=paste-your-api-key-here

Add Makeswift runtime

Create the Makeswift runtime file in src/makeswift.

src/makeswift/runtime.ts

1 import { ReactRuntime } from "@makeswift/runtime/react";
2 
3 export const runtime = new ReactRuntime();

Add Makeswift client

Create the Makeswift client file in src/makeswift.

src/makeswift/client.ts

1 import { Makeswift } from "@makeswift/runtime/next";
2 import { strict } from "assert";
3 
4 import { runtime } from "./runtime";
5 
6 strict(
7   process.env.MAKESWIFT_SITE_API_KEY,
8   "MAKESWIFT_SITE_API_KEY is required"
9 );
10 
11 export const client = new Makeswift(process.env.MAKESWIFT_SITE_API_KEY, {
12   runtime,
13 });

Add the Next.js plugin

Next.js plugins are configured in the project’s next.config.js file by wrapping nextConfig. The Makeswift Next.js plugin whitelists Makeswift image domains and sets up rewrites to enable preview mode in the Makeswift builder.

1 import createWithMakeswift from "@makeswift/runtime/next/plugin";
2 
3 const withMakeswift = createWithMakeswift();
4 
5 /** @type {import('next').NextConfig} */
6 const nextConfig = {
7   // your existing next config
8 };
9 
10 export default withMakeswift(nextConfig);

Set up a custom Document

The Makeswift custom Document handles styles during server-side rendering and using Preview Mode when opening your pages in the Makeswift builder.

Create the file src/pages/_document.ts and export Document from @makeswift/runtime/next/document:

src/pages/_document.tsx

1 export { Document as default } from "@makeswift/runtime/next/document";

If you already have a _document.ts, you can extend the Document from @makeswift/runtime/next/document instead.

Example of extending an existing document

src/pages/_document.tsx

1 import { Html, Head, Main, NextScript } from "next/document";
2 import { Document } from "@makeswift/runtime/next/document";
3 
4 export default class MyDocument extends Document {
5   render() {
6     return (
7       <Html>
8         <Head />
9         <body>
10           <Main />
11           {/* Your custom code here */}
12           <NextScript />
13         </body>
14       </Html>
15     );
16   }
17 }

Register components with Makeswift

Create a file for registered components called src/makeswift/components.tsx. In this example, only one component is registered. However, as you register more components, we recommend creating separate files for each component and rolling up the imports in the src/makeswift/components.ts file. Learn more about registering components.

src/makeswift/components.tsx

1 import { Style } from "@makeswift/runtime/controls";
2 
3 import { runtime } from "./runtime";
4 
5 function HelloWorld({ className }: { className: string }) {
6   return <p className={className}>Hello, world!</p>;
7 }
8 
9 runtime.registerComponent(HelloWorld, {
10   type: "hello-world",
11   label: "Custom / Hello, world!",
12   props: {
13     className: Style(),
14   },
15 });

To ensure these your components become available in Makeswift, this components.tsx file must be imported in three different places:

You’ll do this in the next few steps.

Provide the runtime to Custom App

If you don’t have a Custom App you’ll need to create one. Then wrap your Custom App with the Makeswift ReactRuntimeProvider component.

src/pages/_app.tsx

1 import type { AppProps } from "next/app";
2 import { ReactRuntimeProvider } from "@makeswift/runtime/next";
3 
4 import { runtime } from "../../../../makeswift/runtime";
5 import "../../../../makeswift/components";
6 
7 export default function App({
8   Component,
9   pageProps: { siteVersion, ...pageProps },
10 }: AppProps) {
11   return (
12     <ReactRuntimeProvider runtime={runtime} siteVersion={siteVersion}>
13       <Component {...pageProps} />
14     </ReactRuntimeProvider>
15   );
16 }

Add a route for Makeswift pages

Create an optional catch-all route named [[...path]].tsx. You will use this route to fetch page snapshots from the Makeswift client and render them using the Page component.

src/pages/[[...path]].tsx

1 import {
2   GetStaticPathsResult,
3   GetStaticPropsContext,
4   GetStaticPropsResult,
5 } from "next";
6 
7 import {
8   Page as MakeswiftPage,
9   PageProps as MakeswiftPageProps,
10   Makeswift,
11   type SiteVersion
12 } from "@makeswift/runtime/next";
13 
14 import { client } from "../../../../makeswift/client";
15 import "../../../../makeswift/components";
16 
17 type ParsedUrlQuery = { path?: string[] };
18 
19 export async function getStaticPaths(): Promise<
20   GetStaticPathsResult<ParsedUrlQuery>
21 > {
22   const pages = await client.getPages().toArray();
23 
24   return {
25     paths: pages.map((page) => ({
26       params: {
27         path: page.path.split("/").filter((segment) => segment !== ""),
28       },
29     })),
30     fallback: "blocking",
31   };
32 }
33 
34 export type PageProps = MakeswiftPageProps & {
35   siteVersion: SiteVersion | null;
36 };
37 
38 export async function getStaticProps({
39   params,
40   previewData,
41 }: GetStaticPropsContext<ParsedUrlQuery>): Promise<
42   GetStaticPropsResult<PageProps>
43 > {
44   const path = "/" + (params?.path ?? []).join("/");
45   const siteVersion = Makeswift.getSiteVersion(previewData);
46   const snapshot = await client.getPageSnapshot(path, {
47     siteVersion,
48   });
49 
50   if (snapshot == null) return { notFound: true };
51 
52   return {
53     props: {
54       snapshot,
55       siteVersion,
56     },
57   };
58 }
59 
60 export default function Page({ snapshot }: MakeswiftPageProps) {
61   return <MakeswiftPage snapshot={snapshot} />;
62 }

Important notes:

If you already have a root index.tsx file inside of the pages directory and you’d like to manage that page in code (not in Makeswift), you will need to name the file [...path].tsx instead of [[...path]].tsx. Otherwise, you’ll need to delete it to let the root page be managed in Makeswift. For more information about the differences between catch-all and optional catch-all segments, refer to the Next.js Catch-all segments documentation.
The filename defines the path param. For example, if the filename is [[...slug]].tsx instead of [[...path]].tsx, then the param name is slug. Because this is an optional catch-all route, there are no params when visiting the index (i.e., /) path. The path param defaults to an empty array.
fallback: 'blocking' is used here so that your Next.js app doesn’t need to be re-deployed whenever a new Makeswift page is created.

With this setup, your pages will be rendered using incremental static regeneration. A revalidate field isn’t added to the returned value of getStaticProps because Makeswift pages are automatically revalidated using on-demand revalidation by leveraging the Makeswift API handler.

Add the Makeswift API handler

Similar to NextAuth.js, Makeswift uses an API handler to communicate with your Next.js app. Create the file src/pages/api/makeswift/[...makeswift].ts.

It is important this file has that exact name and path. The extension can be .js or .ts.

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

1 import { MakeswiftApiHandler } from "@makeswift/runtime/next/server";
2 import { strict } from "assert";
3 
4 import { runtime } from "../../../../makeswift/runtime";
5 
6 // make custom components' data available for introspection
7 import "../../../../makeswift/components";
8 
9 strict(
10   process.env.MAKESWIFT_SITE_API_KEY,
11   "MAKESWIFT_SITE_API_KEY is required"
12 );
13 
14 export default MakeswiftApiHandler(process.env.MAKESWIFT_SITE_API_KEY, {
15   runtime,
16 });

This API route adds support for preview mode, on-demand revalidation, and other features that make Makeswift work seamlessly with your Next.js app.

Start the local dev server

Run the local development script. This will start the Next.js app at http://localhost:3000.

$ npm run dev

If port 3000 is already in use, Next.js will try port 3001, then 3002, and so forth until it finds an unused port.

Take note of this port for the next step.

Add your app’s URL to Makeswift

Finally, open the Makeswift builder, navigate to Settings > Host, and add your app’s URL. If you haven’t changed anything in the example and the server is running on port 3000, the app’s URL should be http://localhost:3000.

When you’re ready to deploy, set up a separate site and use your deployment URL instead of http://localhost:3000. You can keep this site for local development.

Start building

Great job! You should be able to create a page in Makeswift and start dropping in registered components from the left toolbar.

Next Steps

Here are a couple of ideas for what you might want to do next.

Concepts

Learn the core concepts behind how Makeswift works.

Custom components

Build custom components for use in the Visual Builder.

Localization

Translate your content into multiple languages.

System requirements

Node.js 20.19 or a later version.
macOS, Windows (including WSL), and Linux are supported.

If you don’t already have a Next.js project, head over to the Next.js documentation to get one set up. If you do have one, please verify you are using Next.js 13.4 or a later version.

This code in this guide assumes you are using a src directory and have the following path aliases configured.

tsconfig.json

1 {
2   "compilerOptions": {
3     "baseUrl": ".",
4     "paths": {
5       "@/*": ["src/*"]
6     }
7   }
8 }

If your setup varies from this, please adjust the code snippets appropriately.

Install dependencies

Install the @makeswift/runtime package. This package contains all of the necessary code to integrate Makeswift into your Next.js app.

$ npm install @makeswift/runtime

Add API key to environment variables

Requesting data through the Makeswift client requires a site API key from Makeswift. In the Makeswift builder, go to Settings > Host and copy the API key for the site.

Once the API key is in your clipboard, open your .env.local file and paste the snippet below.

1 MAKESWIFT_SITE_API_KEY=paste-your-api-key-here

Add Makeswift runtime

Create the Makeswift runtime file in src/makeswift.

src/makeswift/runtime.ts

1 import { ReactRuntime } from "@makeswift/runtime/react";
2 
3 export const runtime = new ReactRuntime();

Add Makeswift client

Create the Makeswift client file in src/makeswift.

src/makeswift/client.ts

1 import { Makeswift } from "@makeswift/runtime/next";
2 import { strict } from "assert";
3 
4 import { runtime } from "./runtime";
5 
6 strict(
7   process.env.MAKESWIFT_SITE_API_KEY,
8   "MAKESWIFT_SITE_API_KEY is required"
9 );
10 
11 export const client = new Makeswift(process.env.MAKESWIFT_SITE_API_KEY, {
12   runtime,
13 });

Add the Next.js plugin

1 import createWithMakeswift from "@makeswift/runtime/next/plugin";
2 
3 const withMakeswift = createWithMakeswift();
4 
5 /** @type {import('next').NextConfig} */
6 const nextConfig = {
7   // your existing next config
8 };
9 
10 export default withMakeswift(nextConfig);

Set up a custom Document

The Makeswift custom Document handles styles during server-side rendering and using Preview Mode when opening your pages in the Makeswift builder.

Create the file src/pages/_document.ts and export Document from @makeswift/runtime/next/document:

src/pages/_document.tsx

1 export { Document as default } from "@makeswift/runtime/next/document";

If you already have a _document.ts, you can extend the Document from @makeswift/runtime/next/document instead.

Example of extending an existing document

src/pages/_document.tsx

1 import { Html, Head, Main, NextScript } from "next/document";
2 import { Document } from "@makeswift/runtime/next/document";
3 
4 export default class MyDocument extends Document {
5   render() {
6     return (
7       <Html>
8         <Head />
9         <body>
10           <Main />
11           {/* Your custom code here */}
12           <NextScript />
13         </body>
14       </Html>
15     );
16   }
17 }

Register components with Makeswift

src/makeswift/components.tsx

1 import { Style } from "@makeswift/runtime/controls";
2 
3 import { runtime } from "./runtime";
4 
5 function HelloWorld({ className }: { className: string }) {
6   return <p className={className}>Hello, world!</p>;
7 }
8 
9 runtime.registerComponent(HelloWorld, {
10   type: "hello-world",
11   label: "Custom / Hello, world!",
12   props: {
13     className: Style(),
14   },
15 });

To ensure these your components become available in Makeswift, this components.tsx file must be imported in three different places:

You’ll do this in the next few steps.

Provide the runtime to Custom App

If you don’t have a Custom App you’ll need to create one. Then wrap your Custom App with the Makeswift ReactRuntimeProvider component.

src/pages/_app.tsx

1 import type { AppProps } from "next/app";
2 import { ReactRuntimeProvider } from "@makeswift/runtime/next";
3 
4 import { runtime } from "../../../../makeswift/runtime";
5 import "../../../../makeswift/components";
6 
7 export default function App({
8   Component,
9   pageProps: { siteVersion, ...pageProps },
10 }: AppProps) {
11   return (
12     <ReactRuntimeProvider runtime={runtime} siteVersion={siteVersion}>
13       <Component {...pageProps} />
14     </ReactRuntimeProvider>
15   );
16 }

Add a route for Makeswift pages

Create an optional catch-all route named [[...path]].tsx. You will use this route to fetch page snapshots from the Makeswift client and render them using the Page component.

src/pages/[[...path]].tsx

1 import {
2   GetStaticPathsResult,
3   GetStaticPropsContext,
4   GetStaticPropsResult,
5 } from "next";
6 
7 import {
8   Page as MakeswiftPage,
9   PageProps as MakeswiftPageProps,
10   Makeswift,
11   type SiteVersion
12 } from "@makeswift/runtime/next";
13 
14 import { client } from "../../../../makeswift/client";
15 import "../../../../makeswift/components";
16 
17 type ParsedUrlQuery = { path?: string[] };
18 
19 export async function getStaticPaths(): Promise<
20   GetStaticPathsResult<ParsedUrlQuery>
21 > {
22   const pages = await client.getPages().toArray();
23 
24   return {
25     paths: pages.map((page) => ({
26       params: {
27         path: page.path.split("/").filter((segment) => segment !== ""),
28       },
29     })),
30     fallback: "blocking",
31   };
32 }
33 
34 export type PageProps = MakeswiftPageProps & {
35   siteVersion: SiteVersion | null;
36 };
37 
38 export async function getStaticProps({
39   params,
40   previewData,
41 }: GetStaticPropsContext<ParsedUrlQuery>): Promise<
42   GetStaticPropsResult<PageProps>
43 > {
44   const path = "/" + (params?.path ?? []).join("/");
45   const siteVersion = Makeswift.getSiteVersion(previewData);
46   const snapshot = await client.getPageSnapshot(path, {
47     siteVersion,
48   });
49 
50   if (snapshot == null) return { notFound: true };
51 
52   return {
53     props: {
54       snapshot,
55       siteVersion,
56     },
57   };
58 }
59 
60 export default function Page({ snapshot }: MakeswiftPageProps) {
61   return <MakeswiftPage snapshot={snapshot} />;
62 }

Important notes:

If you already have a root index.tsx file inside of the pages directory and you’d like to manage that page in code (not in Makeswift), you will need to name the file [...path].tsx instead of [[...path]].tsx. Otherwise, you’ll need to delete it to let the root page be managed in Makeswift. For more information about the differences between catch-all and optional catch-all segments, refer to the Next.js Catch-all segments documentation.
The filename defines the path param. For example, if the filename is [[...slug]].tsx instead of [[...path]].tsx, then the param name is slug. Because this is an optional catch-all route, there are no params when visiting the index (i.e., /) path. The path param defaults to an empty array.
fallback: 'blocking' is used here so that your Next.js app doesn’t need to be re-deployed whenever a new Makeswift page is created.

Add the Makeswift API handler

Similar to NextAuth.js, Makeswift uses an API handler to communicate with your Next.js app. Create the file src/pages/api/makeswift/[...makeswift].ts.

It is important this file has that exact name and path. The extension can be .js or .ts.

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

1 import { MakeswiftApiHandler } from "@makeswift/runtime/next/server";
2 import { strict } from "assert";
3 
4 import { runtime } from "../../../../makeswift/runtime";
5 
6 // make custom components' data available for introspection
7 import "../../../../makeswift/components";
8 
9 strict(
10   process.env.MAKESWIFT_SITE_API_KEY,
11   "MAKESWIFT_SITE_API_KEY is required"
12 );
13 
14 export default MakeswiftApiHandler(process.env.MAKESWIFT_SITE_API_KEY, {
15   runtime,
16 });

This API route adds support for preview mode, on-demand revalidation, and other features that make Makeswift work seamlessly with your Next.js app.

Start the local dev server

Run the local development script. This will start the Next.js app at http://localhost:3000.

$ npm run dev

If port 3000 is already in use, Next.js will try port 3001, then 3002, and so forth until it finds an unused port.

Take note of this port for the next step.

Add your app’s URL to Makeswift

When you’re ready to deploy, set up a separate site and use your deployment URL instead of http://localhost:3000. You can keep this site for local development.

Start building

Great job! You should be able to create a page in Makeswift and start dropping in registered components from the left toolbar.

Next Steps

Here are a couple of ideas for what you might want to do next.

Concepts

Learn the core concepts behind how Makeswift works.

Custom components

Build custom components for use in the Visual Builder.

Localization

Translate your content into multiple languages.

1	{
2	"compilerOptions": {
3	"baseUrl": ".",
4	"paths": {
5	"@/": ["src/"]
6	}
7	}
8	}

1	import { ReactRuntime } from "@makeswift/runtime/react";
2
3	export const runtime = new ReactRuntime();

1	import { Makeswift } from "@makeswift/runtime/next";
2	import { strict } from "assert";
3
4	import { runtime } from "./runtime";
5
6	strict(
7	process.env.MAKESWIFT_SITE_API_KEY,
8	"MAKESWIFT_SITE_API_KEY is required"
9	);
10
11	export const client = new Makeswift(process.env.MAKESWIFT_SITE_API_KEY, {
12	runtime,
13	});

1	import createWithMakeswift from "@makeswift/runtime/next/plugin";
2
3	const withMakeswift = createWithMakeswift();
4
5	/** @type {import('next').NextConfig} */
6	const nextConfig = {
7	// your existing next config
8	};
9
10	export default withMakeswift(nextConfig);

1	import { Html, Head, Main, NextScript } from "next/document";
2	import { Document } from "@makeswift/runtime/next/document";
3
4	export default class MyDocument extends Document {
5	render() {
6	return (
7	<Html>
8	<Head />
9	<body>
10	<Main />
11	{/* Your custom code here */}
12	<NextScript />
13	</body>
14	</Html>
15	);
16	}
17	}

1	import { Style } from "@makeswift/runtime/controls";
2
3	import { runtime } from "./runtime";
4
5	function HelloWorld({ className }: { className: string }) {
6	return <p className={className}>Hello, world!</p>;
7	}
8
9	runtime.registerComponent(HelloWorld, {
10	type: "hello-world",
11	label: "Custom / Hello, world!",
12	props: {
13	className: Style(),
14	},
15	});

1	import type { AppProps } from "next/app";
2	import { ReactRuntimeProvider } from "@makeswift/runtime/next";
3
4	import { runtime } from "../../../../makeswift/runtime";
5	import "../../../../makeswift/components";
6
7	export default function App({
8	Component,
9	pageProps: { siteVersion, ...pageProps },
10	}: AppProps) {
11	return (
12	<ReactRuntimeProvider runtime={runtime} siteVersion={siteVersion}>
13	<Component {...pageProps} />
14	</ReactRuntimeProvider>
15	);
16	}

1	import {
2	GetStaticPathsResult,
3	GetStaticPropsContext,
4	GetStaticPropsResult,
5	} from "next";
6
7	import {
8	Page as MakeswiftPage,
9	PageProps as MakeswiftPageProps,
10	Makeswift,
11	type SiteVersion
12	} from "@makeswift/runtime/next";
13
14	import { client } from "../../../../makeswift/client";
15	import "../../../../makeswift/components";
16
17	type ParsedUrlQuery = { path?: string[] };
18
19	export async function getStaticPaths(): Promise<
20	GetStaticPathsResult<ParsedUrlQuery>
21	> {
22	const pages = await client.getPages().toArray();
23
24	return {
25	paths: pages.map((page) => ({
26	params: {
27	path: page.path.split("/").filter((segment) => segment !== ""),
28	},
29	})),
30	fallback: "blocking",
31	};
32	}
33
34	export type PageProps = MakeswiftPageProps & {
35	siteVersion: SiteVersion \| null;
36	};
37
38	export async function getStaticProps({
39	params,
40	previewData,
41	}: GetStaticPropsContext<ParsedUrlQuery>): Promise<
42	GetStaticPropsResult<PageProps>
43	> {
44	const path = "/" + (params?.path ?? []).join("/");
45	const siteVersion = Makeswift.getSiteVersion(previewData);
46	const snapshot = await client.getPageSnapshot(path, {
47	siteVersion,
48	});
49
50	if (snapshot == null) return { notFound: true };
51
52	return {
53	props: {
54	snapshot,
55	siteVersion,
56	},
57	};
58	}
59
60	export default function Page({ snapshot }: MakeswiftPageProps) {
61	return <MakeswiftPage snapshot={snapshot} />;
62	}

1	import { MakeswiftApiHandler } from "@makeswift/runtime/next/server";
2	import { strict } from "assert";
3
4	import { runtime } from "../../../../makeswift/runtime";
5
6	// make custom components' data available for introspection
7	import "../../../../makeswift/components";
8
9	strict(
10	process.env.MAKESWIFT_SITE_API_KEY,
11	"MAKESWIFT_SITE_API_KEY is required"
12	);
13
14	export default MakeswiftApiHandler(process.env.MAKESWIFT_SITE_API_KEY, {
15	runtime,
16	});