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