Getting started

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

AnchorClone the starter project

First, we'll clone the Makeswift example from Next.js

Copy and paste the commands below to make a local copy and change to the new directory. Feel free to change the name from makeswift-app to something else.

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

AnchorInstall project dependencies

Dependencies should have been installed automatically, but if not be sure to run this command.

npm install


yarn install

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.


AnchorRun the local dev script

Run the local development script. This will start the Next.js app at http://localhost:3000. If port 3000 is already in use, your app might be assigned a different port. Take note of this port for the next step.

npm run dev


yarn dev

AnchorAdd your app's preview URL to Makeswift

Finally, you'll just need to add your app's preview 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/makeswift.

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 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.