Getting started

Setup a new Next.js app with Makeswift in less than 5 minutes.

AnchorClone the starter project

First, we'll use create-next-app with the Makeswift Next.js example.

Copy and paste the commands below to clone the example and change to the newly created directory. Feel free to change makeswift-app to something else.

npx create-next-app -e=cms-makeswift makeswift-app
cd makeswift-app

AnchorConfigure the Makeswift site API key

Go to your Makeswift site and get a hold of your site's API key.

Site API key

Then, create a .env.local file with the contents below. Replace <your_site_api_key> with your site's API key.


AnchorStart your local dev server

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

npm run dev


yarn dev

If port 3000 is already in use, Next.js will try port 3001, then 3002, and so forth until an unused port is found. Take note of this port for the next step.

AnchorAdd your app's URL to Makeswift

Finally, you'll just need to add your app's URL to your Makeswift site settings. If you haven't changed anything in the example and it's running on port 3000, the value should be http://localhost:3000.

Preview URL

When you're ready to deploy, you'll probably set up a separate site and use your deployment URL instead of localhost. You can keep this site for local development.

AnchorStart building!

That's it! You should be able to create a page in Makeswift and start dropping in registered components.

You can register new components in the lib/makeswift/register-components.tsx file.

// lib/makeswift/register-components.tsx

import { Style } from '@makeswift/runtime/controls'
import { ReactRuntime } from '@makeswift/runtime/react'

// Register your components here!

function HelloWorld(props: { className?: string }) {
  return <p {...props}>Hello, world!</p>

ReactRuntime.registerComponent(HelloWorld, {
  type: 'hello-world',
  label: 'Hello, world!',
  props: {
    className: Style({ properties: Style.All }),

You will find your registered components in the toolbar of the Makeswift builder. Drag and drop your components into your page and start building!

Registered components

You can learn more about registering components here.