Forem: Paweł Panowicz

Best headless CMS for Next.js - Typescript support comparison

Paweł Panowicz — Wed, 22 Jan 2025 11:29:38 +0000

Introduction to Best Headless CMS for Next.js - TypeScript Support Comparison

As TypeScript adoption continues to grow in modern web development, developers are increasingly seeking Headless CMS platforms that integrate seamlessly with TypeScript. TypeScript enhances productivity with features like static typing, type inference, and code autocompletion, while reducing errors in development workflows.

When building with Next.js, choosing a CMS with strong TypeScript support and TypeScript resources can significantly streamline development. In this comparison, we analyzed three popular Headless CMS platforms: Strapi, Contentful, and Flotiq. We examined their strengths and limitations, focusing on developer experience, integration complexity, and maintenance concerns. For each of these solutions - we looked through the official documentation and available tutorials and examples, to find out how to make it work with Typescript.

Let’s dive into the details!

Strapi

Strapi is a popular open-source Headless CMS known for its flexibility and self-hosting capabilities. It provides a REST API and optional GraphQL support, making it a versatile choice for developers.

Content Types Setup in Strapi

First you need to create Content-Types which you plan to use:

Once you define the data model, content editors can immediately start their content management work using the generated forms (this is true only for the Strapi Cloud version). If self-hosting, additional steps are required: you must deploy Strapi to a publicly accessible server and configure appropriate access permissions for editors to interact with the system. This means you need to have devops/dbaAdmin engineers available in your organisation.

The development team gets access to the generated REST API, which reflects the data model. Specific endpoints allow access to different types of data, which is natural for developers with experience in RESTful APIs:

curl localhost:1337/api/products -H "Authorization:bearer $STRAPI\_TOKEN"

This request queries the products API for all objects and produces a response similar to this:

{
  "data": \[
    {
      "id": 1,
      "attributes": {
        "Name": "Test",
        "enabled": true,
        "createdAt": "2023-12-08T08:26:17.828Z",
        "updatedAt": "2025-01-06T18:58:33.421Z",
        "publishedAt": "2025-01-06T18:58:33.420Z",
        "locale": "en",
        "description": null,
        "price": null
      }
    }
  \],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 25,
      "pageCount": 1,
      "total": 1
    }
  }
}

Typescript support in Strapi

The standard way of accessing the Strapi API in a Typescript project, as shown in Strapi tutorials (see links [1], [2], [3], [4], [5]), requires manual setup of interfaces for the IDE to understand the data model, so you can utilize the advantages offered by Typescript:

Build a blog with Next (React.js) and Strapi
Getting Started With Next.js and Strapi 5: beginner's guide
Build a Developer Blog with Strapi 5 and Next.js
How to build a To-do App using Next.js and Strapi
Improve Your Frontend Experience With Strapi Types And TypeScript

Once you define these interfaces, the IDE will start suggesting proper attributes and Typescript will verify type correctness:

Unfortunately, hand-crafting these interfaces is error-prone, tedious, and not suited for long-term maintenance as any change in the data model will have to be manually adjusted in the interfaces.

For those with direct access to the Strapi backend project, you can access type definitions generated by Strapi. Deep down in the file, you can find interfaces for all content types. You can import these files into the client/frontend project, but there are some caveats:

The file might need tidying up as it contains many interfaces that will not be used (for internal Strapi types).
When you copy the file into the frontend, it will get out of sync with the data model once changes are made to the content type structure.
Typescript interfaces are generated in development mode, so someone working on the Strapi backend side of things has to generate them and pass them to you. While this may be a problem in larger, enterprise projects, it's likely not an issue in smaller builds.

With that, you can finally utilize Typescript in the client application:

Note how the IDE autocompletes the property names available in the Product content type.

Unfortunately, some additional concerns arise:

The Product content type definition is exported with a rather odd name - ApiProductProduct.
With the default setup, the IDE might not be able to properly interpret the types on all attributes (in the screenshot above, the description field is interpreted as any, which is a sort of failover for missing type definition in Typescript).

Conclusions

Most tutorials and code samples for Strapi do not make full use of Typescript or require manual crafting of interfaces. Creating interfaces by hand is not acceptable for professional projects built with long-term support in mind, but it may be fine for small, pet projects under full control.
If you can copy generated type definitions from the Strapi backend to client applications, it provides a simple way to get (limited) benefits of Typescript in the client app.
Manual synchronization of type definitions from the backend will be required whenever a change is made in the data model. This may require a complicated human-based process or automation that may also create problems.
Type definitions imported in a client app may not provide full support for typing on all object properties, and you have to accept that the *.d.ts files will contain definitions for Strapi internals, as well as the fact that type names may not be very friendly (the ApiProductProduct case).

One more thing: What if you do not have access to the generated type definitions files?

This can easily happen when the project is in maintenance mode and updates are needed without access to the development team. It's also common in large enterprise builds, where separate teams are responsible for maintaining the CMS backend and building client frontend applications.

The Strapi community understands this problem and has come up with solutions based on either OpenAPI or GraphQL (both carry type information), but these solutions are not exactly out-of-the-box or trivial to use.

The OpenAPI approach has been thoroughly described on the Strapi Blog and, although quite complex, it offers a good and standards-based solution to the problem.

However, the GraphQL-based setup (which should be simpler) is only referenced in a Strapi forum thread from 2021:

But since the dotansimha/graphql-code-generator library is hugely popular, this approach is likely to be successful.

Contentful

Contentful is a cloud-hosted Headless CMS, known for its intuitive content editor interface and robust API options (GraphQL and REST).

Content Type Setup in Contentful

In order to compare with Strapi and Flotiq - we start with the same content-type built in Contentful:

Once you define the model, content editors get a graphical interface to enter content:

Developers have access to generic Contentful GraphQL and REST APIs, like this:

It's easy to see that the API described in Contentful docs is not very friendly to use. Strapi and Flotiq have an easier way of accessing content, where API endpoints reflect the content types which are created in your account.

Typescript support in Contentful

Contentful publishes an interesting blog post, highest ranking for "contentful nextjs typescript", How to use TypeScript in your Next.js project. Unfortunately, the post seems mainly SEO-oriented and only briefly mentions how Typescript, Contentful, and Next.js can improve developer experience:

Not very useful.

The official Contentful + next.js starter does not seem to provide any support for Typescript on the content management side of things, either. Furthermore, it uses hardcoded GraphQL queries and content models to fetch the data:

As indicated by the wide use of the any TS type, it does not support any integration with the IDE:

A blog post by Max Schmitt is an improvement, as it shows how adding hand-crafted Typescript interfaces to the code can provide TS support:

The contentful.js v10 announcement promised improved Typescript support, but manually created interfaces can still be seen in the demo code.

Fortunately, when digging deeper into the contentful.js SDK, the Typescript readme file provides a list of 3rd party open-source packages that can help with type generation.

Out of 4 packages, only 2 seem noteworthy.

intercom/contentful-typescript-codegen

Using the intercom/contentful-typescript-codegen package (most starred among the 4 packages listed by Contentful) actually yields promising results, including type information on individual fields:

However, you still need to manually edit the GraphQL query.

To get around this, you can use the contentful.sdk, which should be able to understand the data model in the Contentful account. Unfortunately, it turns out that types generated from the Intercom package do not support the Skeleton types used by the official Contentful SDK.

contentful-userland/cf-content-types-generator

Although the contentful-userland/cf-content-types-generator package seems to be less popular than the Intercom one, it seems to provide better compatibility with the Contentful Typescript SDK.

After running

yarn add cf-content-types-generator

the package is installed and ready to generate types compatible with the current Contentful SDK

yarn run cf-content-types-generator -s $CONTENTFUL_SPACE_ID -t $CONTENTFUL_MANAGEMENT_ACCESS_TOKEN --out @types --response -X

This produces a clean set of type definitions, like this one:

… so much better than what was obtained with Strapi.

With this in place, the IDE is finally ready to work with Typescript and Contentful:

Conclusion for Contentful

Contentful offers partial TypeScript support through third-party tools, but the integration process is cumbersome. The basic setup relies on manually crafted GraphQL queries and and hardcoded interfaces, which limits its appeal for TypeScript-driven workflows. On the other hand, when fully setup with the 3rd party tools - Contentful offers a better experience than Strapi, it also allows content editors to start working immediately after the content types are setup.

Flotiq

Flotiq stands out for its simplicity, developer-first design, and comprehensive tools for content editors and developers.

Content Type Setup in Flotiq

Adding a content type definition in Flotiq is very similar to the process seen in Contentful or Strapi.

When you define the model, as with any other headless CMS, content editors working with Flotiq can start creating content using an easy-to-use form:

Similar to other cloud-hosted systems, like Contentful or Strapi Cloud, Flotiq provides the editors with immediate access to data. Self-hosted systems, in contrast, require a significant (sometimes) effort to deploy and host the system in a way that it’s available to the entire team.

What makes Flotiq stand out, compared to Contentful and Strapi, is the amount of options and easy-to-use tools it gives to the development team:

API documentation - generated and always up-to-date with your content model
SDKs - downloadable for several popular languages
OpenAPI support - for easy integration with other systems
Scoped APIs - to easily generate subsets of the content API for different purposes
Hosted webhooks - for quickly adding extensions without worrying about hosting code
Lifecycle webhooks - synchronous webhooks which let developers modify content before it’s persisted in the CMS
UI plugins - for extending the look and function of the GUI.

You can find more about these features in the Flotiq developer documentation.

Typescript integration in Flotiq

Flotiq’s native support for OpenAPI makes it easy to generate client code for different languages - Java, Python, Dart (for Flutter), Typescript and several more. The Typescript SDK has received much love in the recent months and provides the easiest and most comprehensive method of accessing CMS content among all compared systems.

Install the flotiq/flotiq-codegen-ts sdk

npx flotiq-codegen-ts generate

During the installation you will be asked to provide your Flotiq API key and a few seconds later - the types will be generated. The resulting integration is, by far, the easiest to use and provides full support for types on all attributes in your content model:

This level of integration provides developers with the best most convenient access to the data stored in their CMS.

Conclusions for Flotiq

Flotiq’s SDK for Typescript is easier to configure and install than what Contentful or Strapi has to offer
Flotiq-codegen-ts supports information about types of attributes, return types on API methods as well as field descriptions (same that content editors see in their forms)
Flotiq API is reflecting the content types defined in the system (like Strapi) and does not force developers to learn any system-specific content API (which is what Contentful does)
Ease of use and Typescript support make Flotiq a great choice for Next.js projects.
Flotiq TypeScript resources and integration information is available here: https://flotiq.com/docs/Deep-Dives/nextjs-react-typescript-openapi/#flotiq-codegen-ts

Final Thoughts

Choosing the right Headless CMS for your Next.js project depends on your priorities. Here’s a quick summary of TypeScript CMS support with our ranging, from most compatible to lowest compatible:

1. Flotiq

Provides native TypeScript SDK generation with flotiq-codegen-ts.
Fully typed models ensure complete type safety and IDE autocompletion.
Automatically synchronizes with content model changes, requiring no additional configuration.
Offers the most streamlined and developer-friendly experience, especially for large or dynamic projects.
Is a fully managed product, with a generous free tier.

2. Contentful

Lacks native TypeScript integration; relies on third-party tools like contentful-typescript-codegen or cf-content-types-generator.
Generated types often require manual adjustments to work seamlessly with the SDK.
If opting for GraphQL-based approach - it may require hardcoding of queries, reducing flexibility.
Has a fully managed free tier (very limited), but the paid tiers have a steep price point.

3. Strapi

Requires manual creation of TypeScript interfaces or syncing generated definitions from the backend.
Limited type coverage; some attributes default to any.
Synchronization issues arise when content models change, increasing maintenance overhead.
Best suited for small projects or setups where developers have full backend access.
Managed offering does not include a free tier, but it can be self-hosted, if you have the expertise.

Next.js and Flotiq: Fetching, cache, and draft mode

Paweł Panowicz — Mon, 20 Jan 2025 09:33:17 +0000

In this article, you will learn how to create a Next.js application integrated with Flotiq. We will describe how to conveniently fetch data using a personalized SDK, configure caching, and utilize draft mode for previewing changes. Finally, we will publish the application on the Vercel platform.

The example application code can be found on GitHub.

Prerequisites

Before diving into the article, make sure that:

You have a Flotiq account.
You have a Vercel account.
You have basic knowledge of React.js, TypeScript, and Next.js.

Action Plan

In a few simple steps, we will create a real-world News page listing current news.

Setup content types and data in Flotiq
Setup the Next.js application
Connect Flotiq with Next.js using a personalized SDK
Display a list of articles and a single article
Build a statically generated application
Implement the On-demand revalidation mechanism
Implement Next.js Draft Mode
Go live! Deployment to Vercel

1. Setup Content Types in Flotiq

First, we need to create Content Type Definitions for our project. In the proposed example, this will be the Project data type.

1. Log in to the Flotiq panel.

2. Create a Content Type Definition corresponding to our project.

Label: Project
API Name: project
Properties:

3. Use the Slug plugin, to simplify content entry. This will automatically generate a slug from a specified field.

Go to Plugins.
Click “+” next to the Slug plugin.
Complete the configuration.

4. Enter sample data into Flotiq. A few sample entries will suffice:

The first important step is behind us. We now know what we will store in the system and can start adding content. Now it's time to prepare the application based on your model and data.

2. Next.js application setup

Navigate to the desired directory and run the following command to create a new Next.js application:

npx create-next-app@latest

We will create a project using the App Router, based on TypeScript, and utilizing Tailwind CSS as the CSS framework. Here is the complete configuration:

Navigate to the application directory and run the application

npm run dev

At http://localhost:3000, you will see the default Next.js homepage.

Now, it's time to add content from Flotiq.

3. Connecting Flotiq with Next.js using a personalized SDK

Data from Flotiq can be fetched in various ways - using REST API or GraphQL. Regardless of the approach taken, to communicate with Flotiq, we need to save the API Key in the application, which gives access to your data in Flotiq.

The API Key is available in the Flotiq panel, under the "API Keys" tab. Copy the "Read and write API KEY".

You can generate a key that includes only the necessary elements, e.g., the "Project" Content Type for reading. If the application in the future allows writing, such as comments, you can generate a key with the appropriate permissions.

—

Setting up environment variables

Create a .env.local file and paste the value copied from Flotiq into it.

FLOTIQ_API_KEY=___YOUR_READ_ONLY_API_KEY___

Setting up Flotiq SDK

In projects built with TypeScript, we recommend using the personalized Flotiq SDK. It wraps the REST API, providing convenient access to data tailored to your data model, including data types and intelligent code completion.

Download the Flotiq SDK for your project:

npx flotiq-codegen-ts@latest

Executing the command will download the SDK based on your Content Type Definitions. Note that the script used the previously pasted key from the .env.local file. A directory named flotiqApi has been created in your application directory.

Remember, when you change the Content Type Definition settings in Flotiq (e.g., add a new type or change a field in an existing one), you need to run the command again: npx flotiq-codegen-ts.

—

Fetch content from Flotiq using Flotiq SDK

Now let's dive into how to use the downloaded SDK. For the sake of organization, we will save the communication logic with Flotiq in a separate file /src/lib/api.ts.

Create a file /src/lib/api.ts where we will place the basic requests needed to complete the project:

import { FlotiqApi, Project, ProjectList } from "../../flotiqApi/src";

type ProjectFilter = {
  slug?: {
    type: string,
    filter: string
  }
}

export async function fetchAllProjects(): Promise<ProjectList> {
  const flotiq = new FlotiqApi(process.env.FLOTIQ_API_KEY);
  const filters: ProjectFilter = {};

  return flotiq.ProjectAPI.list({
    limit: 100,
    filters: JSON.stringify(filters)
  });
}

export async function fetchProjectBySlug(slug: string): Promise<Project | undefined> {
  const flotiq = new FlotiqApi(process.env.FLOTIQ_API_KEY);
  const filters: ProjectFilter = {
    slug: {
      type: 'equals',
      filter: slug,
    }
  };
  const projects = await flotiq.ProjectAPI.list({
    limit: 1,
    filters: JSON.stringify(filters)
  });
  return projects.data?.[0];
}

Note the following:

Line 10: The fetchAllProjects method retrieves all objects of the Project type.
Line 20: The fetchProjectBySlug method retrieves a Project object that has a specific value in the slug field.

Notice that in the code, we can use types such as ProjectList or Project, making it more convenient to work with data stored in Flotiq.

Now we are ready to display content from Flotiq.

4. Displaying the list of articles and a single article

We have the data model, test entries, the application skeleton, and a convenient way to connect to Flotiq. Now let's move on to displaying content. In the example application, we will list Projects and allow displaying the details of a single Project.

Listing projects on the application's homepage

1. Prepare app configuration to display images from Flotiq host. Thanks to that, we can utilize the next/image component.

Update the file nextjs.config.ts to containg the following configuration in the images key:

/** @type {import('next').NextConfig} */
const nextConfig = {
    images: {
        remotePatterns: [
            {
                protocol: 'https',
                hostname: 'api.flotiq.com',
                port: '',
                pathname: '/**',
            },
        ],
    },
};

export default nextConfig;

Note: the change may require rerunning the command yarn dev.

2. Replace the example homepage code defined in _/app/page.ts_x.

import { fetchAllProjects} from "@/lib/api";
import { Project } from "../../flotiqApi/src";
import Image from "next/image";
import Link from "next/link";

export default async function Home() {
  const projects = await fetchAllProjects();

  return (
    <main className="max-w-6xl mx-auto px-4 py-10">
      <h1 className="text-2xl font-bold mb-8 border-b-2 border-gray-600">Our Projects</h1>
      <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
        {
          projects.data?.map((project: Project) => (
            <article key={project.id}>
              <Link href={`/projects/${project.slug}`}>
                <h2 className="text-xl font-semibold mb-2">{project.name}</h2>
                <Image
                  src={`https://api.flotiq.com${project.photos?.[0].url}`}
                  alt={project.name}
                  className="w-full h-auto rounded"
                  width={400}
                  height={300}
                />
              </Link>
            </article>
          ))
        }
      </div>
    </main>
  );
}

Note the following:

Line 7: const projects = await fetchAllProjects(); - fetching Projects to display, using the previously prepared API.
Line 10: className="max-w-6xl mx-auto px-4 py-10" - using TailwindCSS classes for basic component styling.
Line 14: projects.data.map((project: Project) => ( - listing Projects, note that we can use the Project type, which provides attribute suggestions for this object.
Line 20: {project.name} - displaying an object's attribute, e.g., the name.

Check how your application looks. Go to http://localhost:3000 and see the results. The homepage should look like this:

Displaying a single Project

As you have probably noticed, the homepage contains a list of projects and a Link component that will lead to the page of a single Project. In this step, we will define routing and display the description of a single Project at the /projects/[slug] address.

1. Add the Tailwind @tailwindcss/typography plugin

The content of one of the fields we want to display - the description field - will be in HTML format, generated by a Rich Text Editor. To correctly handle the HTML tags (e.g., h1, h2, ), we need to extend Tailwind with the @tailwindcss/typography plugin. Otherwise, they will not be styled, as Tailwind relies solely on classes, not HTML tags.

Add the plugin:

yarn add @tailwindcss/typography

Enable the plugin in the tailwind.config.ts file:

// ...other tailwind config

plugins: [
  require('@tailwindcss/typography'),
]

2. Create a single project page /app/projects/[slug]/page.tsx.

According to the Dynamic Route convention in NextJS, the page.tsx file placed in the [slug] directory will be responsible for displaying the content of pages where [slug] will be replaced by possible values from the browser address.

Here is the source code for a single project page:

import { fetchAllProjects, fetchProjectBySlug } from "@/lib/api";
import type { Project, ProjectList } from "../../../../flotiqApi/src";
import Image from "next/image";
import { notFound } from "next/navigation";
import Link from "next/link";

export async function generateStaticParams() {
  const allProjects: ProjectList = await fetchAllProjects();
  return allProjects.data?.map((project: Project) => ({
    slug: project.slug,
  })) || [];
}

interface ProjectProps {
  params: {
    slug: string
  };
}

export default async function Project(props: ProjectProps) {
  const project = await fetchProjectBySlug(props.params.slug);

  if (!project) {
    notFound();
  }

  return (
    <main className="max-w-6xl mx-auto px-4 py-10">
      <h1 className="text-2xl font-bold mb-8 border-b-2 border-gray-600">{project.name}</h1>
      <div className="grid grid-cols-2 gap-6">
        <div>
          <Image
            src={`https://api.flotiq.com${project.photos?.[0].url}`}
            alt={project.name}
            className="w-full h-auto rounded"
            width={400}
            height={300}
          />
        </div>
        <div>
          <div
            dangerouslySetInnerHTML={{__html: project.description ?? ''}}
            className="prose prose-invert"
          />
        </div>
        <Link href="/">Back</Link>
      </div>
    </main>
  );
}

Note the following:

Line 7: The generateStaticParams function is responsible for generating all possible paths based on the slug field.
Line 21: Using the previously prepared fetchProjectBySlug function to fetch projects from Flotiq.
Line 43: Using the classes “prose prose-invert”, i.e., className="prose prose-invert", so that the code returned by Flotiq in the description field (Rich Text type) will be correctly styled.

You just need to navigate to the specific project page, in our case http://localhost:3000/projects/smart-home-automation-system to display the finished page:

5. Building a statically generated application

Currently, we have a page with a list of projects and a detailed project page, both optimized for using React Server Components and static rendering. This provides exceptional application speed; however, its content is updated only during the build process.

Create a production-optimized application by running the command:

yarn build

Next, run the application:

yarn start

Go to http://localhost:3000/ and see how fast the application runs. What happens, however, when we change the content in Flotiq? With this approach, the page will not update - we must rebuild the project each time using yarn build.

To make our page respond to changes in Flotiq, we will prepare an On-demand Revalidation mechanism.

6. Implementing the on-demand revalidation mechanism

To make our page behave dynamically, responding to events from Flotiq, we will prepare an On-demand Revalidation strategy in two steps:

Create an API endpoint that, when queried, will clear the cache for specific addresses.
Create Webhooks in Flotiq that, upon content edit actions, will trigger the cache revalidation API.

Creating the revalidate API in Next.js

Our application will include an additional endpoint, for example, /api/revalidate, which, when queried, will clear the cache within the specified range - for given paths. We will prepare a route handler for this purpose, using the revalidatePath method.

Add a key to the .env.local file that we will use to secure the cache endpoint:

REVALIDATE_KEY=secret_key

Create file /src/app/api/revalidate/route.ts, in which we will handle /api/revalidate

import { revalidatePath } from 'next/cache'
import { NextRequest } from 'next/server'

export async function POST(request: NextRequest) {
  const providedKey = request.headers.get('x-revalidate-key');
  const path = request.nextUrl.searchParams.get('path') ?? '/'

  if (providedKey !== process.env.REVALIDATE_KEY) {
    return Response.json({ message: 'Invalid revalidate key'}, { status: 401 })
  }

  revalidatePath(path, 'page');

  return Response.json({ path: path, now: Date.now() });
}

Note the following:

Line 8: Checking whether the correct x-revalidate-key endpoint was entered - it shouldn’t be accessible without security.
Line 12: Using the function revalidatePath(path, 'page') informing Next.js that the path should be re-fetched the next time it is loaded. The second parameter of the function is used to tell Next.js whether to refresh a specific path, a dynamic path, or a layout. You can read more about using this function in the documentation.

Let's see in practice how the revalidate function works:

Build the application using the yarn build command
Start the server using the yarn start command
Go to https://localhost:3000
Change the data of a project in Flotiq, eg. change the title.
Refresh the site https://localhost:3000 - no changes visible.
Execute the revalidate request for the path "/" (for the homepage): curl --location --request POST 'http://localhost:3000/api/revalidate?path=/' \ --header 'x-revalidate-key: secret_key'
Refresh the site https//localhost:3000 - changes should be visible now.
Execute the revalidate request, for the path “/projects/[slug]” curl --location --request POST 'http://localhost:3000/api/revalidate?path=/projects/\[slug\]' \ --header 'x-revalidate-key: secret_key'
Changes should also be visible on the project subpages.

We have just used the On-demand revalidation mechanism. Thanks to this, updating the content does not require rebuilding the page, only an additional request to the API.

In the next section, we will automate the process using Flotiq Webhooks.

Creating webhooks in Flotiq

To automate the revalidation process, simply add the appropriate webhooks to Flotiq that will behave like the example CURL requests mentioned in the section above.

To use webhooks, the service must be in a publicly accessible environment. In the examples below, replace the values [APP_PUBLIC_URL] once you publish the service, e.g., on Vercel, as described in the final step of the article.

To use webhooks with a local application (running on localhost), you can also use ngrok to make your local application accessible from the outside.

—

We need to add two webhooks that will execute after the change in Content Type Definition Project.

http://[APP_PUBLIC_URL]/api/revalidate?path=/
http://[APP_PUBLIC_URL]/api/revalidate?path=/projects/[slug]

Create the first webhook 'Revalidate homepage cache', providing the following values:

Type: Content Object Changes Asynchronous
URL: http://http://\[APP\_PUBLIC\_URL\]/api/revalidate?path=/
Enabled: true
Actions: Create, Update, Delete
Content Type Definitions: Projects
Headers: x-revalidate-key, secret_key (remember that the value of secret_key should match the REVALIDATE_KEY value that we’ve defined in the .env.local file)

Create another webhook ‘Revalidate project pages cache’, providing the following values:

Type: Content Object Changes Asynchronous
URL: http://[APP_PUBLIC_URL]/api/revalidate?path=/projects/[slug]
Enabled: true
Actions: Create, Update, Delete
Content Type Definitions: Projects
Headers: x-revalidate-key, secret_key (remember that the value of secret_key should match the REVALIDATE_KEY value that we’ve defined in the .env.local file)

Summing up, our webhook list should look like this:

To make sure that a given webhook works, you can check its execution log available in the webhook’s edit view.

Remember, for the webhook to execute, your application must be accessible from the outside. This requires either publishing the application or using services like ngrok.

—

Our Next.js application reacts to changes in objects within Flotiq. This ensures that the content fetched from Flotiq, despite using static generation for performance optimization, will always be up-to-date.

In the next stage, we will use another important feature of Next.js - draft mode.

7. Implementing Next.js Draft Mode

You probably noticed that our Content Type Definition "Project" has a "Status" field, which can be set to "Draft" or "Public". However, we haven't used this field anywhere before.

Our intention is to allow Content Editors to work on content without publishing it. Hence the need to mark some content as "Draft".

The result of this step will be the extension of Flotiq with a "Preview page" button, allowing the preview of pages with draft status. The application in this mode will be generated dynamically, enabling real-time tracking of changes.

Updating the project for Draft Mode

We will extend our templates to support Draft Mode, and requests to Flotiq will include the appropriate filters indicating the status in which to display the data.

1. Add an environment variable to the .env.local file, which will be used to secure the preview mode endpoint:

DRAFT_MODE_KEY=secret_key

2. Add Draft Mode information to the homepage template. Thanks to this, the application will know in which mode it is operating.

// src/app/page.tsx

import { draftMode } from "next/headers";
// ...

export default async function Home()
  const { isEnabled } = draftMode();
  const projects = await fetchAllProjects(isEnabled);
  // the rest of current file

Note that we pass the isEnabled information to our function fetchAllProjects.

3. Similarly, add Draft Mode information to the project page template.

// src/app/projects/[slug]/page.tsx

import { draftMode } from "next/headers";
// ...

export default async function Project(props: ProjectProps) {
  const { isEnabled } = draftMode();
  const project = await fetchProjectBySlug(props.params.slug, isEnabled);
  // the rest of current file

4. Let's extend the methods in our src/lib/api.ts file responsible for communicating with Flotiq. Replace the file with the one containing the handling of the draftMode parameter.

// src/lib/api.ts

import { FlotiqApi, Project, ProjectList } from "../../flotiqApi/src";

type ProjectFilter = {
  slug?: {
    type: string,
    filter: string
  },
  // Added status filter type
  status?: {
    type: string,
    filter: "draft"|"public"
  }
}

export async function fetchAllProjects(draftMode?: boolean): Promise<ProjectList> {
  const flotiq = new FlotiqApi(process.env.FLOTIQ_API_KEY)
  const filters: ProjectFilter = {};

  // Added filter status = public, if not in draft mode
  if(!draftMode) {
    filters.status = {
      type: 'equals',
      filter: 'public'
    }
  }

  return flotiq.ProjectAPI.list({
    limit: 100,
    filters: JSON.stringify(filters)
  })
}

export async function fetchProjectBySlug(slug: string, draftMode?: boolean): Promise<Project | undefined> {
  const flotiq = new FlotiqApi(process.env.FLOTIQ_API_KEY);
  const filters: ProjectFilter = {
    slug: {
      type: 'equals',
      filter: slug,
    }
  }

  // Added filter status = public, if not in draft mode
  if (!draftMode) {
    filters.status = {
      type: 'equals',
      filter: 'public'
    }
  }

  const projects = await flotiq.ProjectAPI.list({
    limit: 1,
    filters: JSON.stringify(filters)
  });
  return projects.data?.[0];
}

Note the following:

Line 22: Extending the ProjectFilter type with a new attribute: status.
Lines 22 and 45: Conditionally adding the filters.status filter when we are outside of Draft Mode. This means that when we are not using Draft Mode, we only display content with the status “public”.

Note that on the project’s homepage, at http://localhost:3000, only projects marked with the "public" flag in Flotiq are visible.

Now, we will add an API endpoint to instruct the application to also show content with draft status.

Creating Draft Mode API in Next.js

Add a handler to process the path /api/draft?slug=/&key=secret_key. In accordance with the Next.js convention, place it in the /app/api/draft/route.ts file:

import { draftMode } from 'next/headers';
import { redirect } from 'next/navigation';

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url)
  const secret = searchParams.get('secret');
  const disable = searchParams.get('disable');
  const slug = searchParams.get('slug') ?? '/';

  // Turn on draft mode
  if (!disable) {
    if (!secret || secret !== process.env.DRAFT_MODE_KEY) {
      return new Response("Missing or invalid secret", { status: 401 });
    }
    draftMode().enable();
    redirect(slug);
  }

  // Turn off draft mode
  draftMode().disable();
  redirect(slug);
}

Note the following:

Line 11: We handle enabling and disabling draft mode. When enabling Draft Mode, for security reasons, we require the use of the DRAFT_MODE_KEY token.
Line 15: Enabling draft mode using the built-in Next.js function.
Linia 20: Disabling draft mode using the built-in Next.js function.

Draft Mode handling is ready! By navigating to http://localhost:3000/api/draft?secret=secret_key, you should see all posts on the homepage, including those with the draft status.

In the next step, we will propose a minor improvement to make using Draft Mode easier.

Creating a component to indicate if the page is in Draft Mode

To improve Draft Mode on the application side, we can add a component informing you that you are in draft mode. Additionally, we will add a link to conveniently exit preview mode.

To add the DraftModeToolbar component, add the src/app/ui/DraftModeToolbar.tsx file.

'use client'

import { usePathname } from "next/navigation";

export default function DraftModeToolbar() {
  const pathName = usePathname();

  return (
    <div className="fixed top-0 right-0 py-2 px-4 bg-red-500">
      <p>Draft mode enabled</p>
      <a href={`/api/draft/?disable=true&slug=${pathName}`}>Disable</a>
    </div>
  )
}

Note the following:

Line 1: Add the "use client" directive, informing Next.js that the following code will execute on the client side. We need this to use the usePathname() hook, which returns the current URL.
Line 11:Link to exit Draft Mode, referring to the previously defined API.

We will use this component in the project layout, in the src/app/layout.tsx file.

// src/app/layout.tsx
// ...
import { draftMode } from "next/headers";
import DraftModeToolbar from "@/app/ui/DraftModeToolbar";
// ...

export default function RootLayout({children}: Readonly<{children: React.ReactNode;}>) {
  const { isEnabled } = draftMode();
  return (
    <html lang="en">
      <body className={inter.className}>
        { isEnabled && <DraftModeToolbar/> }
        { children }
      </body>
    </html>
  );
}

Note the following:

Line 8: Fetching information on whether Draft Mode in enabled.
Line 12: When Draft Mode is enabled, display DraftModeToolbar.

After these changes, when you are in Draft Mode, you will see a convenient notification with a link to exit Draft Mode in the top right corner of the application.

The final step is to integrate the Flotiq interface with Draft Mode.

Creating a preview link in Flotiq

To make working in Flotiq even more convenient, we will extend Flotiq with additional buttons to open the project preview. Here is what your project editing form will look like:

1. In your Flotiq account, add the “Custom Links” plugin.

2. Configure the plugin to display the “Preview page” and “Open published page” buttons. Click “Manage” on the plugin list and fill it out with the following values.

Preview page:

URL Template: http://localhost:3000/api/draft?slug=/projects/{slug}&secret=secret\_key
Link name template: Preview page
Content types: Project

Open published page:

URL Template http://localhost:3000/api/draft?slug=/projects/{slug}&secret=secret\_key&disable=true
Link name template: Open published page
Content types: Project

Here’s what the configuration should look like:

This way, we’ve extended the Flotiq interface. Check how the buttons behave in the project editing view. Remember, if you change the application's address, add new buttons or update the button URLs.

Congratulations! We’ve created a complete application - from the template, through fetching content from Flotiq, using cache, and up to Draft Mode. Now it's time to share it with the world. In the final step, we will describe deployment to the Vercel platform.

8. Go live! Deployment to Vercel

Vercel is an excellent choice for deploying a Next.js application for several reasons: native integration with Next.js, simple configuration, a global CDN network ensuring fast page loading, support for serverless functions, automatic SSL, and easy domain management.

The deployment process is intuitive: connect your repository from GitHub, GitLab, or Bitbucket, and Vercel will automatically build the application after each push.

Publishing repository to GitHub

To start working with Vercel, it is most convenient to create a repository on GitHub, Bitbucket, or GitLab. In our article, we will use the first one (GitHub).

Create a GitHub repository and upload the project files:

git add .
git commit -m "Next.js with Flotiq - example app"
git remote add origin https://github.com/[user]/[repository].git
git push origin main

Importing git repository to a Vercel project

Next, create a Vercel account or log in to an existing account. Select importing the repository from GitHub, choosing your account and the repository with the Next.js project.

After entering the configuration view, don’t forget to enter the environment variables corresponding to those in your .env.local file.

Deploy

Click the “Deploy” button. The operation may take a few minutes.

Once the build process is complete, the site will be available, and you can find its address on the Vercel dashboard.

From now on, the site is available to the public.

Update webhooks and custom links in Flotiq

The final step will be to update the addresses of webhooks and links in Flotiq. They should include the domain set on Vercel. For webhooks, replace the previous placeholders APP_PUBLIC_URL with the actual values.

For plugins, replace the previous http://localhost:3000 with the domain set on Vercel.

Summary

In this article, we discussed the steps needed to create a Next.js application connected to Flotiq. We presented how to fetch data using a personalized SDK, configure caching, and use draft mode to preview changes. Finally, we deployed the application on the Vercel platform.

The components used—SDKs, webhooks, and plugins—demonstrate how to conveniently utilize Flotiq and adapt it to various types of projects.

The code for the application prepared for the article is available in a public GitHub repository.

From Gatsby to Next.js: Why We Migrated Our Blog and How You Can Too

Paweł Panowicz — Thu, 09 Jan 2025 10:05:53 +0000

Why We Migrated Our Blog From Gatsby to Next.js and How You Can Too

When we first launched the Flotiq Blog, Gatsby seemed like the perfect choice. Its static site generation and focus on performance aligned with our vision for a fast, reliable platform. But as Gatsby’s limitations became more apparent—particularly its declining relevance as a technology and the challenges we faced with content updates—we realized it was time to reevaluate our approach. This is the story of how we transitioned from Gatsby to Next.js, the issues that prompted the move, and why this migration transformed our blog for the better.

The Road to Migration: Why migrate from Gatsby to Next.js

At Flotiq, we’re always looking for ways to improve - whether it’s enhancing our product, refining processes, or adopting better technology. Initially, Gatsby worked well for our blog. It was fast, simple, and had a vibrant ecosystem of plugins. But over time, cracks started to show.

The Decline of Gatsby

Gatsby, once a favorite among developers for building static sites, has been losing traction in 2024. On below visual from StateOfJs, you can observe change of sentiment among dev community for Gatsby and Next.js. While Gatsby sentiment goes down year to year, Next.js grows, not only with positive sentiment but also with amount of people using it. Also community shifts towards Next.js, which is visible in growing resources and toolkits around Next.js.

Source: https://2024.stateofjs.com/en-US/libraries/

Here’s more detailed breakdown:

1. Evolving Priorities:

After Netlify’s acquisition of Gatsby, the framework’s development trajectory shifted. With a focus on integrating with Netlify’s ecosystem, Gatsby’s innovation appears to be gone. Throughout the entire 2024 we’ve seen only 1 minor update in the 5.x branch and even that consists mainly of bumped dependencies and small fixes:

This raises serious concerns about Gatsby’s long-term viability and relevance for projects like ours. Many developers have already moved on to frameworks like Next.js, which offer greater flexibility and performance for modern web applications.

2. Dynamic Content Limitations and unreliable Preview mode

As we expanded, we needed a way to handle dynamic routes and real-time content updates. Gatsby’s reliance on static generation made this cumbersome. Each post change/publication required build on production, it added 5 min to see each change.

Gatsby’s Preview mode required deploying a separate Gatsby site in development mode, which often proved unstable and cumbersome to manage. This lack of a reliable and straightforward preview solution made content updates and collaboration with our team more challenging, ultimately pushing us to seek a more robust alternative. The time needed to regenerate static pages after each content update was just too long for an effective editorial workflow.

3. Plugin Overload

Gatsby’s plugin ecosystem is both a strength and a weakness. Managing and updating Gatsby plugins became a noticable overhead, in several cases plugin versions were not compatible with each other, similar to the situation hapenning in the Wordpress plugin ecosystem. Of course - overall the plugin system offered by Gatsby is far more stable than Wordpress.

Why Next.js Stood Out

Next.js emerged as the clear winner for our needs. It’s backed by Vercel, has a robust community, and offers the hybrid rendering approach we needed - SSG, SSR (server-side rendering), and even ISR (incremental static regeneration), all in one package. With Next.js, we saw the opportunity to create a blog that was more flexible, easier to maintain, and better aligned with the evolving needs of modern web development.

The Migration: Step-by-Step Guide to Migrate from Gatsby to Next.js

At first - our dev team approached this with reservations, as every migration - the project had some risks and there was some internal pressure from our Growth team to deliver the new Blog before Christmas. However, after breaking down the migration and realizing that most of the content remains untouched - developers grew more confident that this can actually work. After all - having the ability to easily change frontends is one of the selling points of headless CMS!

Here’s how we tackled this project:

1. Assessing the Existing Site

The first step was understanding what we had. We analyzed the structure of our Gatsby blog, noting critical components like:

Routes: Static and dynamic pages.
Content: Pulled from Flotiq, our headless CMS.
SEO Elements: Titles, meta descriptions, and Open Graph tags.

2. Setting Up a New Next.js Project

We created a fresh Next.js project and configured it to work seamlessly with Flotiq. Thanks to Next.js’s flexibility, this was straightforward. We used npx create-next-app to get started and integrated Flotiq using its API.

3. Migrating Routes and Page Creation

Routes in Gatsby can be created both programmatically, as well as using static files. Because of that - it’s not necessarily obvious how to identify all existing routes in your project. To have 100% certainty that we didn’t loose any page we ran Gatsby’s local development server and connected to the GraphQL API interface to fetch the results of this query:

{
  allSitePage {
    nodes {
      path
      component
    }
  }
}

This returns a list of all pages in a Gatsby project, along with the path of JS file that was used as the template to generate each page, like this:

{
  "data": {
    "allSitePage": {
      "nodes": [
        {
          "path": "/",
          "component": "/Users/MyUser/Desktop/flotiq/flotiq-blog/src/templates/index.js"
        },
…

We took this output and ran it through a simple piece of Javascript, to obtain a list of pages organized by template name:

const getRoutes = (pages) => {
  const uniqueRoutes = [];
  const basePath = 'flotiq-blog';
  pages.forEach((page) => {
    
    const relPath = page.component.substring(page.component.indexOf(basePath) + basePath.length+1);
    const arrayKey = relPath === "//" ? "/" : relPath;
    if(typeof (uniqueRoutes[arrayKey]) === 'undefined' ){
        uniqueRoutes[arrayKey] = [];
    }
    uniqueRoutes[arrayKey].push(page.path);
  });
  return uniqueRoutes;
};

console.log(getRoutes(allSitePage.data.allSitePage.nodes));

which returns the following hierarchy:

That helped us tremendously when creating routes and template files. For each template - we had to analyze the React components used and adapt them to match Next.js conventions and requirements.

4. Transferring SEO Metadata

Preserving our SEO was a top priority. We ensured all meta tags, titles, and descriptions were correctly migrated to Next.js using generateMetadata function. By maintaining the same URLs, we avoided breaking backlinks or losing traffic.

5. Data Fetching with Flotiq

Gatsby’s approach to data fetching is a 2-step process:

Data has to be fetched from the source (in our case - Flotiq, using our source plugin gatsby-source-flotiq) into Gatsby’s internal GraphQL server
GraphQL queries are made from templates to fetch the data so it can be displayed

It’s nice for people who prefer GraphQL, but also a bit complicated at times.

In our Next.js setup we decided to simplify this, so our developers have more control over the data fetching process, and also - to easily get a fully typed API.

Using Flotiq codegen SDK for Typescript we were able to develop quickly, with intuitive code completion and syntax highlighting in our IDE. This is a major step forward in terms of developer experience.

6. Testing and Optimization

Before deploying, we rigorously tested the new blog. We checked:

Page load times and performance using Lighthouse and https://pagespeed.web.dev/ .
SEO elements using tools like Google Search Console.
Compatibility across devices and browsers.

7. Deployment

Finally, we deployed the new blog to Vercel, taking advantage of its automatic builds, previews, and fast global CDN.

The Benefits of Migrating Gatsby to Next.js

Switching from Gatsby to Next.js brought immediate and long-term advantages:

1. Faster Build Times and scalability

With Server-side Rendering (SSR)and selective cache revalidating, we no longer rebuild the entire site for each update. This made updating of the content frictionless. As our content grows, we can confidently scale without worrying about build bottlenecks or performance drops.

2. Dynamic Content Made Easy

Next.js’s hybrid rendering lets us combine static pages with server-side rendering for dynamic content. This made it easier to keep our blog fresh and responsive.

With Gatsby, publishing or updating a single blog post was a tedious process. Each change required a full deployment to production, which could take around 5 minutes or more depending on the content. This meant delays and interruptions, especially for quick updates or time-sensitive posts.

With Next.js, the process is seamless - updates are triggered by a simple webhook that refreshes the cache almost instantly. This efficiency has not only saved us time but also made our workflow far more dynamic and responsive.

Here’s how we configured it in Flotiq

3. Improved SEO

In our previous setup we used Gatsby with Cloudflare Pages, to squeeze the best performance possible for our readers. We still recommend Cloudflare Pages, but we’ve seen many error reports, when the pages were not rendered properly (and based on these Github discussions - we’re not alone ) in this setup. Specifically, it seemed to impact the indexing of our blog by Google, especially combined with the fact that we were hosting the blog in a sub-path (flotiq.com/blog/). At some point we even migrated the blog to a separate domain (blog.flotiq.com) to help solve these issues, without much improvement.

4. Simplified Maintenance

Without the plugin dependencies of Gatsby, updates and troubleshooting are now simpler and quicker.

Key Considerations to keep in mind when migrating from Gatsby to Next.js

If you’re planning a similar migration, keep these points in mind:

Preserve Your URLs: Maintaining your existing URL structure is essential for SEO and avoiding broken links.
Focus on Metadata: Ensure all titles, descriptions, and Open Graph tags are correctly migrated.
Test, Test, Test: Validate every page and feature to avoid surprises post-deployment.
Leverage Your CMS: Having a headless CMS backend makes it easy to replace the frontend technology without changes to the data.

Next.js and Flotiq: A Perfect Match

The combination of Next.js and Flotiq proved to be a winning formula. Next.js’s modern features, combined with Flotiq’s flexible headless CMS capabilities, allowed us to create a blog that’s fast, scalable, and easy to manage. Whether you’re starting a new project or considering a migration, this duo is ideal for building robust, future-proof websites.

Ready to make the switch? Explore Flotiq and unlock the full potential of Next.js for your next project!

Any questions? Write to me at pawel@flotiq.com