Add custom hostname support by MenKNas · Pull Request #359 · Sitecore/content-sdk

MenKNas · 2026-02-02T18:22:48Z

This PR follows the Contribution Guide
Changelog updated
Upgrade guide entry added

Description / Motivation

Support custom Edge hostnames

This PR adds support for custom Sitecore Edge hostnames by resolving the Edge base URL from SITECORE_EDGE_PLATFORM_HOSTNAME (and, for Next.js, NEXT_PUBLIC_SITECORE_EDGE_PLATFORM_HOSTNAME) and ensuring SDK requests and layout/editing data can use the custom hostname instead of the default Edge Platform host. It also adds opt-in media URL rewriting so that URLs in layout data (e.g. image fields, rich text) can be rewritten to the custom hostname when desired.

How it works

Edge URL resolution: The Edge base URL is resolved once at config level (e.g. in define-config): explicit config value → SITECORE_EDGE_PLATFORM_HOSTNAME / Next.js public equivalent → default Edge Platform URL. Helpers receive the already-resolved URL and only normalize it; they do not read env or resolve again.
Custom hostname in responses: When a custom hostname is configured, layout/editing/component responses can be post-processed to replace embedded default Edge hostnames with the resolved custom hostname (default rewriter in rewrite-edge-host.ts).
Opt-in media rewrite: Media URL rewriting is off by default. When rewriteMediaUrls: true is set in Sitecore config, the client applies the default Edge host rewriter to layout data before returning it (rewriting media URLs and rich text to the custom hostname). When rewriteMediaUrls is a function, that function is used to transform each string in the layout.
Static files: resolveEdgeUrlForStaticFiles() always returns the default Edge Platform URL so that static assets (e.g. stylesheets under /v1/files/...) continue to load from the platform when the custom host does not serve them.
Custom rewriter: Apps can set rewriteMediaUrls to a custom (value: string) => string to implement their own URL transformation over layout strings.

Key files

packages/core/src/tools/resolve-edge-url.ts – Edge base URL resolution (used at config time); resolveEdgeUrlForStaticFiles() for static assets.
packages/content/src/layout/rewrite-edge-host.ts – Rewrites default Edge hostnames in layout/editing responses to the resolved custom hostname; used as the default when rewriteMediaUrls: true.
packages/content/src/config/define-config.ts – Resolves edge URL at config level; default rewriteMediaUrls: false.
packages/content/src/client/sitecore-client.ts – Applies the rewriteMediaUrls rewriter when enabled.

Testing Details

Unit Test Added
Manual Test/Other =>

Tested manually in sample app using custom hostname provided in https://portal-staging.sitecore-staging.cloud/admin/custom-hostnames?organization=org_Jk9RJbQPa0m9Psul (test3-staging.envoy-test.cloud)

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)

packages/content/src/layout/rewrite-edge-host.ts

github-actions · 2026-02-02T18:31:27Z

📦 Package Size and Test Coverage Report

Package	Base Size	PR Size	Δ Change	Base Coverage	PR Coverage	Δ Change
analytics-core	122.52 KB	122.52 KB	✅ 0.00 KB	100.00%	100.00%	0.00%
cli	58.70 KB	58.70 KB	✅ 0.00 KB	69.73%	69.73%	0.00%
content	397.02 KB	416.74 KB	🔺 +19.72 KB	92.35%	92.02%	-0.34%
core	90.85 KB	101.78 KB	🔺 +10.93 KB	91.82%	92.77%	+0.95%
create-content-sdk-app	243.64 KB	244.73 KB	🔺 +1.09 KB	96.22%	96.22%	0.00%
events	76.91 KB	76.91 KB	✅ 0.00 KB	98.40%	98.40%	0.00%
nextjs	430.10 KB	431.20 KB	🔺 +1.10 KB	89.75%	89.78%	+0.03%
personalize	63.45 KB	63.45 KB	✅ 0.00 KB	99.32%	99.32%	0.00%
react	289.54 KB	289.57 KB	🔺 +0.03 KB	93.80%	93.80%	0.00%
search	7.11 KB	7.30 KB	🔺 +0.19 KB	98.57%	98.57%	0.00%
Total	—	—	🔺 +33.06 KB	—	—	—

packages/content/src/layout/content-rewrite.test.ts

…ession for hostnames Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

illiakovalenko

Please see my feedback and suggestions for improvement

packages/content/src/config/define-config.ts

packages/content/src/layout/content-rewrite.ts

packages/content/src/client/edge-proxy.ts

packages/content/src/client/sitecore-client.ts

packages/content/src/layout/rewrite-edge-host.ts

illiakovalenko · 2026-02-12T12:03:48Z

packages/content/src/layout/rewrite-edge-host.ts

+ */
+const DEFAULT_EDGE_HOSTNAMES = [
+  'edge-platform.sitecorecloud.io',
+  'edge.sitecorecloud.io', // Legacy hostname included for safety replacement


This is not a legacy URL - it is an Experience Edge URL.

We can leave default production url, but we cannot hardcode or enumerate custom environments here (staging, dev etc.). Customers and some internal teams may use additional environments, and with the current implementation they would not be able to configure custom hostnames.

To address this properly, we should introduce an internal environment variable: SITECORE_EXPERIENCE_EDGE_HOSTNAME. This variable would need to be populated by the Deploy team, allowing custom environment hostnames to be specified without constraining the implementation.

@MenKNas This comment is not resolved, as no changes have been applied, except of moving to "core"

packages/content/src/layout/rewrite-edge-host.ts

packages/nextjs/src/config/define-config.ts

packages/create-content-sdk-app/src/templates/nextjs/sitecore.config.ts

packages/create-content-sdk-app/src/templates/nextjs/.env.remote.example

illiakovalenko · 2026-02-12T12:45:43Z

packages/create-content-sdk-app/src/templates/nextjs/.env.container.example

I'm not sure this is applicable to local development with containers

packages/content/src/layout/rewrite-edge-host.test.ts

packages/content/src/client/sitecore-client.ts

packages/core/src/tools/resolve-edge-url.ts

packages/content/src/client/edge-proxy.ts

packages/content/src/config/define-config.ts

packages/content/src/editing/editing-service.ts

packages/content/src/layout/rewrite-edge-host.ts

illiakovalenko · 2026-02-17T08:20:49Z

packages/core/src/tools/resolve-edge-url.ts

+ * Available on both server and client (e.g. NEXT_PUBLIC_* in Next.js).
+ * @public
+ */
+export const SITECORE_EDGE_HOSTNAME_PUBLIC_ENV = 'NEXT_PUBLIC_SITECORE_EDGE_HOSTNAME';


Please refer to my previous comment where I pointed out that the core package should not reference Next.js–specific environment variables. This should instead be handled at the nextjs package level, for example via a defineConfig override. Also it's not renamed to "SITECORE_EDGE_PLATFORM_HOSTNAME"

illiakovalenko · 2026-02-17T08:29:17Z

packages/content/src/editing/design-library.ts

-export function getDesignLibraryScriptLink(sitecoreEdgeUrl = SITECORE_EDGE_URL_DEFAULT): string {
-  return `${normalizeUrl(sitecoreEdgeUrl)}/v1/files/designlibrary/lib/rh-lib-script.js`;
+export function getDesignLibraryScriptLink(sitecoreEdgeUrl?: string): string {
+  return `${(sitecoreEdgeUrl ? normalizeUrl(sitecoreEdgeUrl) : resolveEdgeUrl())}/v1/files/designlibrary/lib/rh-lib-script.js`;


Please refer to my earlier comment. The current approach still introduces unnecessary complexity without a clear justification.

As mentioned before, the edge URL should be resolved and normalized in a single place - at the configuration level. There is no need to repeat this logic every time the edge URL is passed as a parameter.

This applies to ALL occurrences

illiakovalenko · 2026-02-17T08:38:18Z

packages/content/src/layout/rewrite-edge-host.ts

+ */
+const DEFAULT_EDGE_HOSTNAMES = [
+  'edge-platform.sitecorecloud.io',
+  'edge.sitecorecloud.io', // Legacy hostname included for safety replacement


@MenKNas This comment is not resolved, as no changes have been applied, except of moving to "core"

illiakovalenko · 2026-02-17T08:39:12Z

packages/core/src/constants.ts

@@ -4,6 +4,23 @@
 */
 export const SITECORE_EDGE_URL_DEFAULT = 'https://edge-platform.sitecorecloud.io';


Suggested change

export const SITECORE_EDGE_URL_DEFAULT = 'https://edge-platform.sitecorecloud.io';

export const SITECORE_EDGE_PLATFORM_URL_DEFAULT = 'https://edge-platform.sitecorecloud.io';

packages/core/src/constants.ts

illiakovalenko · 2026-02-17T08:45:27Z

packages/create-content-sdk-app/src/templates/nextjs/.env.remote.example


+# Optional: custom Experience Edge hostname override (XM Cloud/Edge; hostname or full URL).
+# Available on both server and client.
+NEXT_PUBLIC_SITECORE_EDGE_HOSTNAME=


Suggested change

NEXT_PUBLIC_SITECORE_EDGE_HOSTNAME=

NEXT_PUBLIC_SITECORE_EDGE_PLATFORM_HOSTNAME=

illiakovalenko · 2026-02-17T08:45:49Z

packages/create-content-sdk-app/src/templates/nextjs/.env.remote.example

 # Will be used as a fallback if separate SITECORE_EDGE_CONTEXT_ID value is not provided
 NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID=

+# Optional: custom Experience Edge hostname override (XM Cloud/Edge; hostname or full URL).


Suggested change

# Optional: custom Experience Edge hostname override (XM Cloud/Edge; hostname or full URL).

# Optional: custom Sitecore Edge Platform hostname (hostname or full URL).

illiakovalenko · 2026-02-17T08:46:28Z

packages/create-content-sdk-app/src/templates/nextjs/.env.remote.example

 NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID=

+# Optional: custom Experience Edge hostname override (XM Cloud/Edge; hostname or full URL).
+# Available on both server and client.


This can be removed, as it is already expected behavior for Next.js developers when using NEXT_PUBLIC environment variables.

Suggested change

# Available on both server and client.

illiakovalenko · 2026-02-17T08:46:53Z

packages/create-content-sdk-app/src/templates/nextjs-app-router/.env.remote.example


+# Optional: custom Experience Edge hostname override (XM Cloud/Edge; hostname or full URL).
+# Available on both server and client.
+NEXT_PUBLIC_SITECORE_EDGE_HOSTNAME=


Please, see my comments for "nextjs" template as a references

illiakovalenko · 2026-02-17T08:47:45Z

packages/core/src/tools/normalize-env-value.ts

Please, add unit tests

illiakovalenko · 2026-02-17T09:13:34Z

CHANGELOG.md

-  - Available in both Pages Router and App Router templates
+
+* `[core]` `[content]` `[nextjs]` Support custom Edge hostnames via `NEXT_PUBLIC_SITECORE_EDGE_HOSTNAME` ([#359](https://github.com/Sitecore/content-sdk/pull/359))
+  - Consolidated `rewriteContentUrls` and `contentRewrite` into `rewriteMediaUrls: boolean | ((value: string) => string)`. When `true`, uses default Edge host rewriter; when a function, transforms each string (SDK traverses layout). Migration: `rewriteContentUrls: true` → `rewriteMediaUrls: true`; custom rewriter → `rewriteMediaUrls: (value: string) => string`


Could we make sure to double check the AI-generated notes? It should be removed as it was renamed and consolidated during the PR review, initially we didn't have this feature.
We can simply mention the new property that was introduced

Co-authored-by: Illia Kovalenko <23364749+illiakovalenko@users.noreply.github.com>

illiakovalenko · 2026-02-17T13:55:22Z

packages/content/src/client/edge-proxy.ts

-  `${normalizeUrl(sitecoreEdgeUrl)}/v1/content/api/graphql/v1`;
+export const getEdgeProxyContentUrl = (
+  sitecoreEdgeUrl: string = constants.SITECORE_EXPERIENCE_EDGE_URL_DEFAULT
+) => `${getBaseEdgeUrl(sitecoreEdgeUrl)}/v1/content/api/graphql/v1`;


Let me clarify again the difference between Experience Edge and Edge Platform URLs, as there appears to be a misunderstanding.

Experience Edge (https://edge.sitecorecloud.io)
– Used for media URLs.

Edge Platform (https://edge-platform.sitecorecloud.io)
– Used by our services to resolve endpoints.

Based on the changes you introduced, Experience Edge is now being referenced when resolving service endpoints. This is not correct. We should continue using the default Edge Platform URL for service-related requests.

The Experience Edge URL should be referenced only when replacing media URLs.
This is the only place where the Experience Edge URL environment variable should be used, in order to allow overriding it when necessary.

illiakovalenko · 2026-02-17T13:59:30Z

packages/content/src/client/sitecore-client.ts


    const contextId = serverContextId || clientContextId;
+    // Use default Edge URL for styles (ignore custom hostname) so stylesheets load from platform
+    const edgeUrlForStyles = resolveEdgeUrlForStaticFiles();


Are stylesheets not supported with a custom hostname? Is this an existing limitation?

When using a custom hostname and attempting to serve styles, it resulted in a 404 error, and the styles on the page appeared broken. So I kept it this way to make sure styles don't break in this case.

illiakovalenko · 2026-02-17T14:02:49Z

packages/create-content-sdk-app/src/templates/nextjs-app-router/.env.remote.example

 NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID=

+# Optional: custom Sitecore Edge Platform hostname (hostname or full URL).
+# Next.js: use NEXT_PUBLIC_SITECORE_EDGE_PLATFORM_HOSTNAME for client; SITECORE_EDGE_PLATFORM_HOSTNAME for server-only.


Suggested change

# Next.js: use NEXT_PUBLIC_SITECORE_EDGE_PLATFORM_HOSTNAME for client; SITECORE_EDGE_PLATFORM_HOSTNAME for server-only.

illiakovalenko · 2026-02-17T14:03:03Z

packages/create-content-sdk-app/src/templates/nextjs/.env.remote.example

 NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID=

+# Optional: custom Sitecore Edge Platform hostname (hostname or full URL).
+# Next.js: use NEXT_PUBLIC_SITECORE_EDGE_PLATFORM_HOSTNAME for client; SITECORE_EDGE_PLATFORM_HOSTNAME for server-only.


Suggested change

# Next.js: use NEXT_PUBLIC_SITECORE_EDGE_PLATFORM_HOSTNAME for client; SITECORE_EDGE_PLATFORM_HOSTNAME for server-only.

illiakovalenko · 2026-02-17T16:04:40Z

packages/content/src/layout/rewrite-edge-host.ts

+const DEFAULT_EDGE_HOSTNAMES = [
+  'edge-platform.sitecorecloud.io',
+  'edge.sitecorecloud.io',
+  'edge-staging.sitecore-staging.cloud',
+  'edge-platform-staging.sitecore-staging.cloud',
+] as const;


Please refer to my previous comment - the issue has not been resolved yet

MenKNas added 5 commits January 30, 2026 19:21

Route Edge requests and returned URLs through SITECORE_EDGE_HOSTNAME

4e866f8

Fix failing test

a580791

Fix error pages null handling + document custom Edge hostname env vars

a72243c

Fix failing api verification issue

52709e2

Minor comment adjustments

90871de

github-advanced-security bot found potential problems Feb 2, 2026

View reviewed changes

packages/content/src/layout/rewrite-edge-host.ts Fixed Show fixed Hide fixed

packages/content/src/layout/rewrite-edge-host.ts Fixed Show fixed Hide fixed

packages/content/src/layout/rewrite-edge-host.ts Fixed Show fixed Hide fixed

Adjust CHANGELOG.md

6fb96ae

MenKNas added 3 commits February 2, 2026 20:33

Fix regex analysis issue

6224c9c

Fix verify api extractor issue

45d9344

Fix api verification issue

64062b0

MenKNas marked this pull request as ready for review February 4, 2026 07:01

Add opt-in layout URL rewrite for media content

49ba70e

github-advanced-security bot found potential problems Feb 10, 2026

View reviewed changes

packages/content/src/layout/content-rewrite.test.ts Fixed Show fixed Hide fixed

packages/content/src/layout/content-rewrite.test.ts Fixed Show fixed Hide fixed

MenKNas and others added 4 commits February 10, 2026 18:36

Merge branch 'dev' into feature/JSS-7383-add-custom-hostname-support

6f04630

Potential fix for code scanning alert no. 50: Incomplete regular expr…

c1b72b4

…ession for hostnames Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

Potential fix for code scanning alert no. 49: Incomplete regular expr…

c8b9073

…ession for hostnames Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

Fix api extractor issue

25f5c7c

illiakovalenko requested changes Feb 12, 2026

View reviewed changes

illiakovalenko reviewed Feb 12, 2026

View reviewed changes

packages/create-content-sdk-app/src/templates/nextjs/sitecore.config.ts Outdated Show resolved Hide resolved

illiakovalenko reviewed Feb 12, 2026

View reviewed changes

packages/create-content-sdk-app/src/templates/nextjs/.env.remote.example Outdated Show resolved Hide resolved

illiakovalenko reviewed Feb 12, 2026

View reviewed changes

Address PR comments 1

eaeb11c

github-advanced-security bot found potential problems Feb 13, 2026

View reviewed changes

packages/content/src/layout/rewrite-edge-host.test.ts Fixed Show fixed Hide fixed

packages/content/src/layout/rewrite-edge-host.test.ts Fixed Show fixed Hide fixed

MenKNas added 2 commits February 13, 2026 10:22

Fix test related issue

7ed5bb4

Fix api-extractor issues and html related false warning

1191572

sc-nikolaoslazaridis reviewed Feb 16, 2026

View reviewed changes

packages/content/src/client/sitecore-client.ts Show resolved Hide resolved

sc-nikolaoslazaridis reviewed Feb 16, 2026

View reviewed changes

packages/core/src/tools/resolve-edge-url.ts Outdated Show resolved Hide resolved

packages/core/src/tools/resolve-edge-url.ts Outdated Show resolved Hide resolved

packages/core/src/tools/resolve-edge-url.ts Outdated Show resolved Hide resolved

sc-nikolaoslazaridis reviewed Feb 16, 2026

View reviewed changes

packages/content/src/editing/editing-service.ts Show resolved Hide resolved

sc-nikolaoslazaridis reviewed Feb 16, 2026

View reviewed changes

packages/content/src/layout/rewrite-edge-host.ts Outdated Show resolved Hide resolved

MenKNas added 2 commits February 16, 2026 17:51

Address PR comments 2

7b92bc5

Fix API extractor issue

cadf3fc

illiakovalenko requested changes Feb 17, 2026

View reviewed changes

illiakovalenko reviewed Feb 17, 2026

View reviewed changes

MenKNas and others added 4 commits February 17, 2026 13:02

Address PR comments 3

f34cd5f

Update packages/core/src/constants.ts

243bcf9

Co-authored-by: Illia Kovalenko <23364749+illiakovalenko@users.noreply.github.com>

Adjustments

f7a82fc

Adjustments

8fce771

illiakovalenko requested changes Feb 17, 2026

View reviewed changes

Address PR comments 4

f22711f

		@@ -4,6 +4,23 @@
		*/
		export const SITECORE_EDGE_URL_DEFAULT = 'https://edge-platform.sitecorecloud.io';

	export const SITECORE_EDGE_URL_DEFAULT = 'https://edge-platform.sitecorecloud.io';
	export const SITECORE_EDGE_PLATFORM_URL_DEFAULT = 'https://edge-platform.sitecorecloud.io';

	NEXT_PUBLIC_SITECORE_EDGE_HOSTNAME=
	NEXT_PUBLIC_SITECORE_EDGE_PLATFORM_HOSTNAME=

	# Optional: custom Experience Edge hostname override (XM Cloud/Edge; hostname or full URL).
	# Optional: custom Sitecore Edge Platform hostname (hostname or full URL).

Conversation

MenKNas commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description / Motivation

Support custom Edge hostnames

How it works

Key files

Testing Details

Types of changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📦 Package Size and Test Coverage Report

Uh oh!

Uh oh!

Uh oh!

illiakovalenko left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

illiakovalenko Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

illiakovalenko Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

illiakovalenko Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

MenKNas commented Feb 2, 2026 •

edited

Loading

github-actions bot commented Feb 2, 2026 •

edited

Loading

illiakovalenko Feb 17, 2026 •

edited

Loading

illiakovalenko Feb 17, 2026 •

edited

Loading

illiakovalenko Feb 17, 2026 •

edited

Loading