Getting Started

Contributing

Plugin development

CMS + Next.js: CMS Migration

This section provides a comprehensive guide for migrating from an existing web-builder setup to the Erxes CMS when working with Next.js applications.

Overview

Migrating from a web-builder setup to Erxes CMS involves updating your configuration and queries to work with the Erxes GraphQL API. This guide will help you transition your existing Next.js application to use Erxes CMS for content management.

Prerequisites

Before starting the migration process, ensure you have:

An active Erxes SaaS instance with CMS plugin installed
A Client Portal created in Erxes
A valid Client Portal Token (not a system token)
Your current Next.js project with Apollo Client
Access to your existing web-builder configuration

1. Environment Configuration (next-config.js)

Update your environment variables to point to the erxes CMS domain and use the Client Portal token.

/** @type {import('next').NextConfig} */
const nextConfig = {
  env: {
    ERXES_API_URL: "https://[your-domain].next.erxes.io",
    ERXES_APP_TOKEN: "YOUR_CLIENT_PORTAL_TOKEN",
  },
};

module.exports = nextConfig;

Notes

ERXES_API_URL must be your erxes CMS domain
ERXES_APP_TOKEN must be a Client Portal token, not a system token

2. Apollo Client Configuration

When working with CMS APIs, erxes requires the token to be sent using the x-app-token header.

import { ApolloClient, InMemoryCache, createHttpLink } from "@apollo/client";
import { setContext } from "@apollo/client/link/context";

const httpLink = createHttpLink({
  uri: `${process.env.ERXES_API_URL}/gateway/graphql`,
});

const authLink = setContext((_, { headers }) => ({
  headers: {
    ...headers,
    "x-app-token": process.env.ERXES_APP_TOKEN,
  },
}));

export const apolloClient = new ApolloClient({
  link: authLink.concat(httpLink),
  cache: new InMemoryCache(),
});

Key Change

erxes-app-token ➜ x-app-token

3. CMS GraphQL Queries

Post List Query

Use cpPostList to fetch CMS posts.

import { gql } from "@apollo/client";

export const cmsPostList = gql`
  query PostList(
    $type: String
    $featured: Boolean
    $categoryIds: [String]
    $searchValue: String
    $status: PostStatus
    $tagIds: [String]
    $sortField: String
    $sortDirection: String
  ) {
    cpPostList(
      featured: $featured
      type: $type
      categoryIds: $categoryIds
      searchValue: $searchValue
      status: $status
      tagIds: $tagIds
      sortField: $sortField
      sortDirection: $sortDirection
    ) {
      totalCount
      posts {
        _id
        title
        content
        excerpt
        featured
        status
        createdAt
        updatedAt
        thumbnail {
          url
        }
        categories {
          _id
          name
        }
        images {
          url
          type
          name
        }
      }
    }
  }
`;

Single Post Query

Use cpPostDetail to fetch a specific post by slug or ID.

export const cmsPostDetail = gql`
  query PostDetail($slug: String, $id: String) {
    cpPostDetail(slug: $slug, _id: $id) {
      _id
      title
      content
      excerpt
      featured
      status
      createdAt
      updatedAt
      thumbnail {
        url
      }
      categories {
        _id
        name
      }
      images {
        url
        type
        name
      }
      author {
        ... on User {
          _id
          email
        }
        ... on ClientPortalUser {
          fullName
          firstName
          lastName
        }
      }
    }
  }
`;

4. Fetching Data in Components

Example: Fetching Posts with SSR

import { useQuery } from "@apollo/client";
import { cmsPostList } from "@/graphql/queries";

export default function BlogPage() {
  const { data, loading, error } = useQuery(cmsPostList, {
    variables: {
      categoryIds: ["c-exNoBpJp4WUd1fgUB9m"],
      status: "published",
    },
  });

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error loading posts</div>;

  const posts = data?.cpPostList?.posts || [];
  
  return (
    <div>
      <h1>Blog Posts</h1>
      {posts.map(post => (
        <article key={post._id}>
          <h2>{post.title}</h2>
          <p>{post.excerpt}</p>
          <span>Published: {new Date(post.createdAt).toLocaleDateString()}</span>
        </article>
      ))}
    </div>
  );
}

Example: Fetching Single Post with CSR

"use client";

import { useQuery } from "@apollo/client";
import { cmsPostDetail } from "@/graphql/queries";

export default function PostPage({ params }) {
  const { data, loading, error } = useQuery(cmsPostDetail, {
    variables: {
      slug: params.slug,
    },
  });

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error loading post</div>;

  const post = data?.cpPostDetail;
  
  return (
    <article>
      <h1>{post.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: post.content }} />
      <div>By: {post.author.fullName || post.author.email}</div>
    </article>
  );
}

Important Notes

categoryIds must be an array of strings
Always handle loading and error states
Use SSR for pages that need SEO optimization
Use CSR for interactive components

5. Common Issues

CORS Errors

The domain is not whitelisted in Client Portal settings
Incorrect API URL

Unauthorized Errors

Invalid or missing Client Portal token
Wrong header name (x-app-token required)

5. Migrating Existing Queries

From cmsPosts to cpPostList

If you're migrating from the existing cmsPosts query, update your queries:

Before:

import { gql } from "@apollo/client";

export const cmsPosts = gql`
  query CmsPosts($clientPortalId: String, $featured: Boolean, $type: String, $categoryId: String, $searchValue: String, $status: PostStatus, $page: Int, $perPage: Int, $tagIds: [String], $sortField: String, $sortDirection: String, $language: String) {
    cmsPosts(clientPortalId: $clientPortalId, featured: $featured, type: $type, categoryId: $categoryId, searchValue: $searchValue, status: $status, page: $page, perPage: $perPage, tagIds: $tagIds, sortField: $sortField, sortDirection: $sortDirection, language: $language) {
      _id
      title
      content
      // ... other fields
    }
  }
`;

After:

import { gql } from "@apollo/client";

export const cmsPostList = gql`
  query PostList(
    $type: String
    $featured: Boolean
    $categoryIds: [String]
    $searchValue: String
    $status: PostStatus
    $tagIds: [String]
    $sortField: String
    $sortDirection: String
  ) {
    cpPostList(
      featured: $featured
      type: $type
      categoryIds: $categoryIds
      searchValue: $searchValue
      status: $status
      tagIds: $tagIds
      sortField: $sortField
      sortDirection: $sortDirection
    ) {
      totalCount
      posts {
        _id
        title
        content
        // ... other fields
      }
    }
  }
`;