Setup

Step 1: Get Access to Erxes SaaS

You need access to an Erxes SaaS instance and an admin user account.

• Your Erxes domain should follow this format:
  https://[your-domain].app.erxes.io
• If you don’t have a SaaS instance yet, ask your manager to create one for you.
• Make sure the CMS and Client Portal plugins are installed on that SaaS instance.

Step 2: Generate an API Token

You’ll need an API token to fetch data from Erxes.

1. Visit your Erxes SaaS domain:
   https://[your-domain].app.erxes.io
2. Go to:
   Settings → Apps (Legacy)
3. Click “Add New App”
4. Fill out the form:
   • Name: Use your website’s name
   • User Group: Select admin
   • Expiration Date: Set a reasonable expiration
   • Permissions: Check “Allow all permissions”
5. After creating the app, copy the generated token — you’ll use this to connect to the CMS via GraphQL.
6. Create Client Portal:
   • Go to:
     Settings → Business portal → Client Portal
   • Click Add new Client Portal”
   • Fill out the form and submit it.
   • Find Authentication menu in the Client Portal settings. and in Erxes App Token field, paste the token you copied earlier.

✅ Store this token in your environment file as ERXES_APP_TOKEN.

Step 3: Create CMS Content

Before connecting your frontend, make sure your CMS has the necessary content created. Go to your Erxes SaaS domain and create the following:

• Pages – Static content for routes like /about, /contact, etc.
• Posts – Blog articles or news content
• Categories – Used to group posts or pages
• Menus – Used for your site's navigation

⚠️ These entries are required to successfully fetch and display content. If they’re missing, GraphQL queries may return null or empty arrays.

---

Step 4: Install Required Packages

You’ll need to install Apollo Client and GraphQL to communicate with the CMS.

Using npm:

npm install @apollo/client graphql

Using yarn

yarn add @apollo/client graphql

Step 5: Update your next.config.ts(mjs)

Before using Apollo Client, make sure your environment variables are properly set and exposed to the frontend.

1. Here is your next config file should be

// next.config.ts

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  env: {
    ERXES_API_URL: "https://[your-domain].app.erxes.io/gateway/graphql",
    ERXES_URL: "https://[your-domain].app.erxes.io/gateway",
    ERXES_FILE_URL: "https://[your-domain].app.erxes.io/gateway/read-file?key=", // updated to match the domain
    ERXES_APP_TOKEN: "", // your copied token earlier
  },
  images: {
    unoptimized: true,
    remotePatterns: [
      {
        protocol: "http",
        hostname: "localhost",
        port: "4000", // your local development server port
      },
      {
        protocol: "https",
        hostname: "[your-domain].app.erxes.io", // updated to match the domain
      },
    ],
  },
};

export default nextConfig;

Step 6: Set Up Apollo Client

Create a shared Apollo Client instance so your app can communicate with the CMS. These 2 files will help you set up the Apollo Client for both server-side and client-side rendering in Next.js.

1. Create lib/client.ts

Inside your lib/ folder, create a file named client.ts with the following code:

// lib/client.ts

import { ApolloClient, HttpLink, InMemoryCache } from "@apollo/client";
import { registerApolloClient } from "@apollo/experimental-nextjs-app-support";

export const { getClient } = registerApolloClient(() => {
  return new ApolloClient({
    cache: new InMemoryCache(),
    link: new HttpLink({
      uri: process.env.ERXES_API_URL,
      credentials: "include",
      headers: {
        "erxes-app-token": process.env.ERXES_APP_TOKEN || "",
      },
    }),
  });
});

2. Create lib/apollo-wrapper.ts

Create a file named apollo-wrapper.ts in the same lib/ folder with the following code:

// lib/apollo-wrapper.ts

"use client";

import { ApolloLink, HttpLink } from "@apollo/client";
import { NextSSRInMemoryCache, NextSSRApolloClient } from "@apollo/experimental-nextjs-app-support/ssr";
import { ApolloNextAppProvider, SSRMultipartLink } from "@apollo/experimental-nextjs-app-support";

function makeClient() {
  const httpLink = new HttpLink({
    uri: process.env.ERXES_API_URL,
    credentials: "include", // Include cookies
    headers: {
      // Remove the CORS header - it's not needed here
      "erxes-app-token": process.env.ERXES_APP_TOKEN || "",
    },
    fetchOptions: { cache: "no-store" },
  });

  // For SSR, you typically want to chain the SSRMultipartLink
  const link =
    typeof window === "undefined"
      ? ApolloLink.from([
          new SSRMultipartLink({
            stripDefer: true,
          }),
          httpLink,
        ])
      : httpLink;

  return new NextSSRApolloClient({
    cache: new NextSSRInMemoryCache(),
    link,
  });
}

export function ApolloWrapper({ children }: React.PropsWithChildren) {
  return <ApolloNextAppProvider makeClient={makeClient}>{children}</ApolloNextAppProvider>;
}

Step 3. Wrap your application with the ApolloProvider

In your app/layout.tsx file, wrap your application with the ApolloWrapper:

// app/layout.tsx
import { ApolloWrapper } from "@/lib/apollo-wrapper";
import "./globals.css";
export const metadata = {
  title: "Your App Title",
  description: "Your App Description",
};

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <ApolloWrapper>
          <Header />
          {children}
          <Footer />
        </ApolloWrapper>
      </body>
    </html>
  );
}

Now your Next.js application is set up to communicate with the Erxes CMS using Apollo Client. You can start querying and mutating data from the CMS in your components.

Go to next section to learn available queries and mutations.