Getting started

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

AnchorClone the starter project

First, we'll clone the Makeswift basic-typescript example.

Copy and paste the snippet of code below to make a local copy and change to the new directory. Feel free to change the name from my-project to something else.

npx degit makeswift/makeswift/examples/basic-typescript my-project
cd my-project

AnchorInstall project dependencies

Next, let's install our project's dependencies.

yarn install
# or
npm 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.

yarn dev
# or
npm run dev

Take note of the URL provided by Next.js when running this command. We'll use it in the next step.

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.