installation.mdx

title
Installation

import CatchAllExample from "/snippets/app-router/catch-all.mdx" import ProvidersExample from "/snippets/app-router/providers.mdx" import LayoutExample from "/snippets/app-router/layout.mdx" import ApiHandlerExample from "/snippets/app-router/api-handler.mdx" import RuntimeExample from "/snippets/reference/runtime.mdx" import ClientExample from "/snippets/reference/client.mdx" import NextConfigExample from "/snippets/reference/next-config.mdx"

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

System requirements

• Node.js 18.17 or a later version.
• macOS, Windows (including WSL), and Linux are supported.

Geting started

First, open your Next.js project. If you don't already have one, head over to the [Next.js](https://nextjs.org/docs/getting-started/installation) documentation to get one set up. If you do have one, please verify you are using [Next.js 13.4](https://nextjs.org/blog/next-13-4) or a later version that is using [App Router](https://nextjs.org/docs/getting-started/installation).

<Info>
  If you are not using App Router, here's how to [incrementally adopt](https://nextjs.org/docs/app/building-your-application/upgrading/app-router-migration) it.
</Info>

Install the `@makeswift/runtime` package. This package contains all of the necessary code to integrate Makeswift into your Next.js app.

npm install @makeswift/runtime

Requesting data through the Makeswift client requires a site API key from Makeswift. In the Makeswift builder, go to Settings > Host and copy the API key for the site.

Once the API key is in your clipboard, open your .env.local file and paste the snippet below.

MAKESWIFT_SITE_API_KEY=paste-your-api-key-here

Create files for the Makeswift runtime and client.

Similar to NextAuth.js, Makeswift uses an API handler to communicate with your Next.js app. Create the file app/api/makeswift/[...makeswift]/route.ts.

It is important this file has that exact name and path. The extension can be `.js` or `.ts`.

This API route adds support for Draft Mode, on-demand revalidation, and other features that make Makeswift work seamlessly with your Next.js app.

Next.js plugins are configured in the project's next.config.js file by wrapping nextConfig. The Makeswift Next.js plugin whitelists Makeswift image domains and sets up rewrites to enable draft mode in the Makeswift builder.

Create a file for registered components called makeswift/components.tsx. In this example, only one component is registered. However, as you register more components, we recommend creating separate files for each component and rolling up the imports in the makeswift/components.ts file. Learn more about registering components.

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(),
  },
})

Create a client component for the Makeswift providers.

<ProvidersExample />

An important Note with this file is that you need to import the components registered in `makeswift/components.tsx`.

In your root layout, wrap your app with the `MakeswiftProvider` component created in the last step, import the registered components, and add the `DraftModeScript` to the `head`. This script enables [Draft Mode](https://nextjs.org/docs/app/building-your-application/configuring/draft-mode) when inside the Makeswift builder.

<LayoutExample />

Create an optional catch-all route named [[...path]]. This catch-all route will fetch page data from Makeswift and pass it to be rendered in the Page component.

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

npm run dev

If port 3000 is already in use, Next.js will try port 3001, then 3002, and so forth until it finds an unused port.

Take note of this port for the next step.

Finally, open the Makeswift builder, navigate to Settings > Host, and add your app's URL. If you haven't changed anything in the example and the server is running on port 3000, the app's URL should be http://localhost:3000.

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

Great job! You should be able to create a page in Makeswift and start dropping in registered components from the left toolbar.