Makeswift Home
Makeswift on GitHub

Manual setup

Manually integrate Makeswift with your Next.js app.

AnchorBefore you start

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

AnchorCreate a project

First, we need a Next.js project. If you don't already have one, the easiest way to get one set up is with Create Next App. Feel free to change the name from makeswift-app to something else.

yarn create next-app makeswift-app
cd makeswift-app

You can also use NPM, if that's your preference.

npx create-next-app makeswift-app
cd makeswift-app

AnchorInstall Makeswift dependencies

Then, let's install the @makeswift/runtime package. This package contains all of the necessary code to ingegrate Makeswift into your Next.js app.

yarn install @makeswift/runtime
# or
npm install @makeswift/runtime

AnchorAdd preview route

Let's create a new page named makeswift.js which will be used by the Makeswift builder to show a preview of all your pages.

This file can have a different name and be anywhere under your app's pages directory. Keep in mind that this will affect the URL that you use in the last step, though.

From this file, export getServerSideProps and the Page component from @makeswift/runtime/next.

This is how your app will fetch page data from Makeswift and then render it on your page.

// pages/makeswift.js

export { getServerSideProps, Page as default } from '@makeswift/runtime/next'

AnchorAdd live route

Let's create a new optional catch-all route named [[...path]].js. This dynamic route will render all your Makeswift live pages—it's what your users will see when they visit your Next.js app.

From this file, export getStaticProps, getStaticPaths, and the Page component from @makeswift/runtime/next.

With this set-up, your pages will be rendered using Incremental Static Regenerations.

// pages/[[...path]].js

export { getStaticProps, getStaticPaths, Page as default } from '@makeswift/runtime/next'

It's important that the catch-all route is named [[...path]].js since the name is what determines the parameter received by getStaticProps.

AnchorSet up custom Document

Next we'll add a custom Document to handle styles properly during server-side rendering.

Create the _document.js page and export Document from @makeswift/runtime/next.

// pages/_document.js

export { Document as default } from '@makeswift/runtime/next'

AnchorConfigure Next.js images domain

Add the Makeswift images domain to next.config.js. This is necessary to be able to use images hosted in Makeswift together with next/image.

// next.config.js

module.exports = {
  images: {
    domains: ['s.mkswft.com'],
  },
}

AnchorAdd environment variables

We'll also need to add a couple of environment variables. You'll need your site API key for this step, which you can find in your Makeswift site settings.

Site API key

Add the MAKESWIFT_API_HOST environment variable to your .env file.

# .env
MAKESWIFT_API_HOST=https://api.makeswift.com

And add the MAKESWIFT_SITE_API_KEY environment variable to your .env.local file. Replace <your_site_api_key> with your site API key.

# .env.local
MAKESWIFT_SITE_API_KEY=<your_site_api_key>

AnchorRegister components with Makeswift

We'll need a central file where we'll register components with Makeswift. This file should be imported by the preview and live routes. You can place this file wherever you want and give it any name you want. For this guide, we'll be using lib/makeswift/register-components.js.

// lib/makeswift/register-components/js

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

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

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

Don't forget to import this file in your preview and live routes.

  // pages/makeswift.js

+ import '../lib/makeswift/register-components'

  export { getServerSideProps, Page as default } from '@makeswift/runtime/next'

  // pages/[[...path]].js

+ import '../lib/makeswift/register-components'

  export { getStaticProps, getStaticPaths, Page as default } from '@makeswift/runtime/next'

You can learn more about registering components here.

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

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've been following the instructions in this guide and your app's running on port 3000, the value should be http://localhost:3000/makeswift.

If you have a different preview route, make sure to use that path instead.

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