The Runtime and Client
Introduction
In the following sections, you’ll see an overview of the key architectural components that integrate your frontend application with Makeswift.
When you install Catalyst with the Makeswift integration, or initialize a starter codebase with the Makeswift installer, these pieces are already in place; the topics covered will simply give you a better understanding of how the integration with Makeswift works.
If you are integrating Makeswift into an existing Next.js app, then these major pillars are notable as the most important integration points you’ll need to implement.
We won’t be covering all required setup, so make sure to refer to the Makeswift documentation for full integration guides for the App Router or Pages Router.
The Makeswift Runtime
The Makeswift Runtime is the critical connective layer between your application and Makeswift. It is utilized at several key entry points in the Next.js code.
The runtime is provided by the package @makeswift/runtime.
Key elements are imported directly from this package in several areas, as in the case of the Page component that is crucial for the rendering of a Makeswift-enabled page route.
It is also important that an instance of the runtime itself be initialized and made available throughout the application. You can observe this in lib/makeswift/runtime.ts:
This runtime instance is utilized in several places, such as in the React provider component and API handler, both of which you’ll explore shortly.
Note that initializing the runtime includes specifying information about the screen breakpoints that should be available in Makeswift.
If you follow along with these examples in your own Makeswift codebase, you may see differences, as your installation may be based on a more recent version of the example code.
Component Registration
A key use of the runtime instance is for registering the visual components that will be available in the editor interface.
You’ll explore the architecture and schema of components in detail later, but simply note that in order for Makeswift to be aware of a component, it must be registered, as in this example in lib/makeswift/components/accordion/register.ts:
You must make sure that all such registrations are performed when a page is rendered. By default, this is handled by centralizing imports of all custom components in lib/makeswift/components.ts.
With this convention in place, when creating a new component, you simply need to add an import for it to the manifest in lib/makeswift/components.ts:
The API Handler
Another key use of the runtime instance is in the initialization of the Makeswift API handler.
By default, you can see this setup in the API route found at app/api/makeswift/[…makeswift]/route.ts.
With this API route in place, Makeswift has an endpoint for making requests to your application, which is necessary to support features like preview mode.
Learn more about the details of the API handler in the Makeswift documentation.
The Makeswift Client
A critical element in the frontend application is the Makeswift Client. Like the runtime itself, the client must be instantiated, which by default is done in lib/makeswift/client.ts.
While the API handler makes it possible for Makeswift to make requests to your frontend application, the client object does the reverse, enabling your application to fetch data from the Makeswift API. The key example is the fetching of a “snapshot” - that is, the component configuration or tree of components that have been built in the editor.
We’ll explore more details of the use of the client when examining routing fundamentals.
The Site API Key
As seen in the API handler and client initialization code, both require the unique API key of your site in order to facilitate the connections between your app and Makeswift. (In the default codebase, this is stored in an environment var in .env.local.)
Remember that in the Makeswift editor interface, the site API key can be found in the Settings menu, in the Host tab.
In order to ensure your frontend application provides runtime data correctly to Makeswift and fetches page snapshots correctly from Makeswift, make sure both that the Host URL is configured correctly in your site settings and that the appropriate site API key is configured in Next.js!
