refactor(core): split client into base config and extended client

core/client/base.ts

@@ -0,0 +1,31 @@
+/**
+ * Base client configuration and instance for BigCommerce API access.
+ *
+ * This module intentionally avoids importing any Next.js runtime APIs
+ * (`next/headers`, `next/navigation`) or `next-intl/server`. In Next.js 16,
+ * importing those modules during config resolution (i.e., from `next.config.ts`)
+ * poisons the process-wide AsyncLocalStorage context and causes
+ * "workUnitAsyncStorage" invariant errors at runtime.
+ *
+ * - `baseClientConfig` — shared configuration object (env vars + logger).
+ *   Re-used by `./index.ts` to build the full client with request hooks.
+ * - `baseClient` — a ready-to-use client instance without hooks.
+ *   Safe to import from `next.config.ts` and other non-request contexts.
+ */
+import { createClient } from '@bigcommerce/catalyst-client';
+
+import { backendUserAgent } from '../user-agent';
+
+type ClientConfig = Parameters<typeof createClient>[0];
+
+export const baseClientConfig = {
+  storefrontToken: process.env.BIGCOMMERCE_STOREFRONT_TOKEN ?? '',
+  storeHash: process.env.BIGCOMMERCE_STORE_HASH ?? '',
+  channelId: process.env.BIGCOMMERCE_CHANNEL_ID,
+  backendUserAgentExtensions: backendUserAgent,
+  logger:
+    (process.env.NODE_ENV !== 'production' && process.env.CLIENT_LOGGER !== 'false') ||
+    process.env.CLIENT_LOGGER === 'true',
+} satisfies Partial<ClientConfig>;
+
+export const baseClient = createClient(baseClientConfig);

core/client/index.ts

@@ -5,7 +5,8 @@ import { redirect } from 'next/navigation';
 import { getLocale as getServerLocale } from 'next-intl/server';
 
 import { getChannelIdFromLocale } from '../channels.config';
-import { backendUserAgent } from '../user-agent';
+
+import { baseClientConfig } from './base';
 
 const getLocale = async () => {
   try {
@@ -26,13 +27,7 @@ const getLocale = async () => {
 };
 
 export const client = createClient({
-  storefrontToken: process.env.BIGCOMMERCE_STOREFRONT_TOKEN ?? '',
-  storeHash: process.env.BIGCOMMERCE_STORE_HASH ?? '',
-  channelId: process.env.BIGCOMMERCE_CHANNEL_ID,
-  backendUserAgentExtensions: backendUserAgent,
-  logger:
-    (process.env.NODE_ENV !== 'production' && process.env.CLIENT_LOGGER !== 'false') ||
-    process.env.CLIENT_LOGGER === 'true',
+  ...baseClientConfig,
   getChannelId: async (defaultChannelId: string) => {
     const locale = await getLocale();
 

core/next.config.ts

@@ -3,7 +3,7 @@ import type { NextConfig } from 'next';
 import createNextIntlPlugin from 'next-intl/plugin';
 
 import { writeBuildConfig } from './build-config/writer';
-import { client } from './client';
+import { baseClient } from './client/base';
 import { graphql } from './client/graphql';
 import { cspHeader } from './lib/content-security-policy';
 
@@ -32,7 +32,7 @@ const SettingsQuery = graphql(`
 `);
 
 async function writeSettingsToBuildConfig() {
-  const { data } = await client.fetch({ document: SettingsQuery });
+  const { data } = await baseClient.fetch({ document: SettingsQuery });
 
   const cdnEnvHostnames = process.env.NEXT_PUBLIC_BIGCOMMERCE_CDN_HOSTNAME;