Multi-Subdomain Configuration

This document outlines the steps required to implement and support multi-subdomain setups in a commerce architecture. It includes frontend configurations, authentication adjustments, domain mappings in the Omnitron, and subdomain-specific email template management.

Implementation Checklist

• Set locale URL strategy to Subdomain

• Update Auth handler for dynamic hostname and cookie domain

• Configure Domain Name per Sales Channel

• Assign Email Templates to Specific Subdomains

FRONTEND CONFIGURATION

1. Setting the Locale URL Strategy to Subdomain

In order to enable locale handling via subdomains (e.g., en.example.com, fr.example.com), update the locale URL strategy in the frontend project settings.

File: src/settings.js

Configuration:

localeUrlStrategy: LocaleUrlStrategy.Subdomain

2. Configuring Dynamic Hostname and Cookie Handling for Auth

To properly handle authentication cookies across multiple subdomains, you need to configure the authentication handler ([...nextauth].ts) to dynamically compute the hostname and apply the correct cookie domain.

File: src/pages/api/auth/[...nextauth].ts

import Auth from '@akinon/next/api/auth';
import getRootHostname from '@akinon/next/utils/get-root-hostname';
import type { NextApiRequest, NextApiResponse } from 'next';

const customOptions = (req: NextApiRequest) => {
  const fallbackHost = req.headers['x-forwarded-host'] || req.headers.host || '';
  const baseUrl = process.env.NEXT_PUBLIC_URL || `https://${fallbackHost}`;
  const hostname = getRootHostname(baseUrl);
  const isHttps = baseUrl.startsWith('https://') || process.env.NODE_ENV === 'production';

  if (!isHttps || !hostname) {
    return {};
  }

  process.env.NEXTAUTH_URL = `https://${fallbackHost}`;

  return {
    cookies: {
      sessionToken: {
        name: `${isHttps ? '__Secure-' : ''}next-auth.session-token`,
        options: {
          domain: hostname,
          httpOnly: true,
          sameSite: 'lax',
          path: '/',
          secure: isHttps,
        },
      },
    },
  };
};

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  return Auth(req, res, customOptions);
}

This setup ensures that the session cookie is properly scoped to the root domain (e.g., .example.com) and works across all subdomains securely.

OMNITRON CONFIGURATION

1. Domain Name Configuration per Sales Channel

In the Omnitron, navigate to: Settings → Sales Channel Settings

Under the corresponding sales channel, configure the Domain Name Settings to include all required subdomains (e.g., ar-ae.example.com, ar-bh.example.com, ar-kw.example.com, etc.).

This ensures that all subdomains are recognized and correctly handled in routing, content delivery, and environment-based logic.

2. Subdomain-Specific Email Template Assignment

To send different email templates based on subdomain (e.g., locale or region-specific content), follow these steps:

Navigation: Sales Channels → Content Management → Mailing Templates

• Select the email template you wish to customize.

• Within the template configuration screen, locate the Sites field.

• Select the appropriate subdomains (sites) where this template should be active.

This allows for targeted transactional or marketing emails tailored by region, locale, or brand variation via subdomain separation.