<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Rahul Nair</title>
    <description>The latest articles on DEV Community by Rahul Nair (@rahulnair-labs).</description>
    <link>https://dev.to/rahulnair-labs</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4249502%2Faf45a283-4414-4af0-92fd-49ad7d3adeb6.png</url>
      <title>DEV Community: Rahul Nair</title>
      <link>https://dev.to/rahulnair-labs</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/rahulnair-labs"/>
    <language>en</language>
    <item>
      <title>Sitecore JSS to Content SDK: What Actually Changes (Next.js App Router + XM Cloud)</title>
      <dc:creator>Rahul Nair</dc:creator>
      <pubDate>Wed, 18 Nov 2026 15:53:13 +0000</pubDate>
      <link>https://dev.to/rahulnair-labs/sitecore-jss-to-content-sdk-what-actually-changes-nextjs-app-router-xm-cloud-7mm</link>
      <guid>https://dev.to/rahulnair-labs/sitecore-jss-to-content-sdk-what-actually-changes-nextjs-app-router-xm-cloud-7mm</guid>
      <description>&lt;h2&gt;
  
  
  The problem
&lt;/h2&gt;

&lt;p&gt;If you run a headless Sitecore site on Next.js, you probably built it on JSS. JSS was centered on the Pages Router: &lt;code&gt;getStaticProps&lt;/code&gt; and &lt;code&gt;getStaticPaths&lt;/code&gt;, a generated &lt;code&gt;temp/config&lt;/code&gt;, and a component builder that registered your renderings.&lt;/p&gt;

&lt;p&gt;The Content SDK is the supported path for XM Cloud headless apps on the Next.js App Router. (Sitecore now brands XM Cloud as SitecoreAI, and you will see both names in the docs.) It changes the plumbing, and that is where the migration effort goes. The good news is that most of your CMS-facing code does not need rewriting.&lt;/p&gt;

&lt;p&gt;One note on versions: the code in this post reflects a migration to Content SDK 1.x with the App Router. Content SDK 2.x changes a few names, and I call those out where they apply. Sitecore also publishes step-by-step upgrade guides for each JSS version, which I link at the end. This post is the conceptual map to read alongside them.&lt;/p&gt;

&lt;p&gt;I recently moved a production app across, so this post is the map I wish I had at the start. It stays general and only covers patterns that apply to any JSS app.&lt;/p&gt;

&lt;h2&gt;
  
  
  What stays the same
&lt;/h2&gt;

&lt;p&gt;Before the changes, here is what you keep:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;The layout JSON shape&lt;/li&gt;
&lt;li&gt;Placeholders and rendering UIDs&lt;/li&gt;
&lt;li&gt;Field types (&lt;code&gt;Field&lt;/code&gt;, &lt;code&gt;ImageField&lt;/code&gt;, and so on)&lt;/li&gt;
&lt;li&gt;Component names matching renderings&lt;/li&gt;
&lt;li&gt;Integrated GraphQL on renderings&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Your Sitecore item structure and most presentation components stay as they are. What you replace is the adapter layer and the imports.&lt;/p&gt;

&lt;h2&gt;
  
  
  What changes at a glance
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Area&lt;/th&gt;
&lt;th&gt;JSS&lt;/th&gt;
&lt;th&gt;Content SDK&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Runtime package&lt;/td&gt;
&lt;td&gt;&lt;code&gt;@sitecore-jss/sitecore-jss-nextjs&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;@sitecore-content-sdk/nextjs&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;CLI&lt;/td&gt;
&lt;td&gt;Bootstrap and component builder scripts&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;@sitecore-content-sdk/cli&lt;/code&gt; (&lt;code&gt;sitecore-tools&lt;/code&gt;)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Config&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;scjssconfig.json&lt;/code&gt; and &lt;code&gt;temp/config&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;&lt;code&gt;sitecore.config.ts&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Generated output&lt;/td&gt;
&lt;td&gt;&lt;code&gt;temp/componentBuilder&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;.sitecore/&lt;/code&gt; (component map, import map, sites, metadata)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Routing&lt;/td&gt;
&lt;td&gt;&lt;code&gt;pages/[[...path]].tsx&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;app/[...path]/page.tsx&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Data fetching&lt;/td&gt;
&lt;td&gt;Layout service factories and page-props plugins&lt;/td&gt;
&lt;td&gt;&lt;code&gt;SitecoreClient&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;React context&lt;/td&gt;
&lt;td&gt;&lt;code&gt;SitecoreContext&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;SitecoreProvider&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Context hook&lt;/td&gt;
&lt;td&gt;&lt;code&gt;useSitecoreContext()&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;useSitecore()&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Editing&lt;/td&gt;
&lt;td&gt;Pages API routes&lt;/td&gt;
&lt;td&gt;App Router route handlers&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h2&gt;
  
  
  1. Dependencies and build toolchain
&lt;/h2&gt;

&lt;p&gt;Swap the runtime package and add the CLI. Your scripts typically become:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;sitecore-tools project build&lt;/code&gt;, which generates metadata, sites and imports&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;sitecore-tools project component generate-map&lt;/code&gt;, which generates the component map (often with &lt;code&gt;--watch&lt;/code&gt; in dev)&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The important rule is that the Sitecore tools must run &lt;strong&gt;before&lt;/strong&gt; &lt;code&gt;next build&lt;/code&gt;. In my setup, &lt;code&gt;sitecore.cli.config.ts&lt;/code&gt; wires up &lt;code&gt;generateMetadata&lt;/code&gt;, &lt;code&gt;generateSites&lt;/code&gt;, &lt;code&gt;extractFiles&lt;/code&gt; and &lt;code&gt;writeImportMap&lt;/code&gt; over the Sitecore component folder, with excludes for tests and non-component files.&lt;/p&gt;

&lt;h2&gt;
  
  
  2. Configuration: one typed config file
&lt;/h2&gt;

&lt;p&gt;JSS spread host names and keys across &lt;code&gt;scjssconfig.json&lt;/code&gt;, &lt;code&gt;temp/config&lt;/code&gt; and environment variables. The Content SDK pulls this into one file, &lt;code&gt;sitecore.config.ts&lt;/code&gt;, using &lt;code&gt;defineConfig&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;defineConfig&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s1"&gt;'@sitecore-content-sdk/nextjs/config'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;default&lt;/span&gt; &lt;span class="nf"&gt;defineConfig&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;api&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;edge&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="cm"&gt;/* contextId, edgeUrl, clientContextId */&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;local&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="cm"&gt;/* apiKey, apiHost */&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;defaultSite&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;NEXT_PUBLIC_DEFAULT_SITE_NAME&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="c1"&gt;// defaultLanguage, editingSecret, redirects, multisite, personalize...&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;api.edge&lt;/code&gt; covers XM Cloud and Edge. &lt;code&gt;api.local&lt;/code&gt; covers local XM, containers and fallback. Middleware and the client both consume the redirects, multisite and personalize settings.&lt;/p&gt;

&lt;p&gt;Commit a &lt;code&gt;sitecore.config.ts.example&lt;/code&gt; and keep secrets in environment variables only. The mental shift is to stop reading &lt;code&gt;temp/config&lt;/code&gt; everywhere. You import &lt;code&gt;sitecore.config&lt;/code&gt; and build a single &lt;code&gt;SitecoreClient&lt;/code&gt; from it.&lt;/p&gt;

&lt;h2&gt;
  
  
  3. Generated artifacts: &lt;code&gt;.sitecore/&lt;/code&gt;
&lt;/h2&gt;

&lt;p&gt;The component builder output is replaced by a &lt;code&gt;.sitecore/&lt;/code&gt; folder containing the component map, client component map, import maps, &lt;code&gt;sites.json&lt;/code&gt; and &lt;code&gt;metadata.json&lt;/code&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="n"&gt;components&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s1"&gt;'.sitecore/component-map'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A client-side provider passes that map into &lt;code&gt;SitecoreProvider&lt;/code&gt; and loads &lt;code&gt;.sitecore/import-map.client&lt;/code&gt; for editor and design library scenarios.&lt;/p&gt;

&lt;p&gt;Most teams git-ignore these generated files. If you do, document that CI has to run &lt;code&gt;sitecore-tools&lt;/code&gt; before the build, or the build will fail on missing imports.&lt;/p&gt;

&lt;h2&gt;
  
  
  4. Routing: Pages Router to App Router
&lt;/h2&gt;

&lt;p&gt;The JSS catch-all route had &lt;code&gt;getStaticPaths&lt;/code&gt;, &lt;code&gt;getStaticProps&lt;/code&gt;, a page-props factory with plugins for layout, dictionary, component props and redirects, and &lt;code&gt;SitecoreContext&lt;/code&gt; with a component factory.&lt;/p&gt;

&lt;p&gt;The Content SDK version is an async Server Component:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// app/[...path]/page.tsx&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;page&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;client&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getPage&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;path&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;site&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;locale&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;For components that export &lt;code&gt;getServerSideProps&lt;/code&gt;, a small helper resolves their data:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="nf"&gt;getComponentProps&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;page&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;componentMap&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;context&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The rest is a thin presentational wrapper plus a client &lt;code&gt;SitecorePageProvider&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;A few changes here are Next.js shifts and not Sitecore-specific: &lt;code&gt;params&lt;/code&gt; is now a Promise, you call &lt;code&gt;notFound()&lt;/code&gt; from &lt;code&gt;next/navigation&lt;/code&gt;, and &lt;code&gt;revalidate&lt;/code&gt; and &lt;code&gt;dynamic&lt;/code&gt; become route segment config instead of &lt;code&gt;getStaticProps.revalidate&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;When stripping multisite or personalization prefixes from the URL, use the SDK helpers &lt;code&gt;normalizeSiteRewrite&lt;/code&gt; and &lt;code&gt;normalizePersonalizedRewrite&lt;/code&gt;, since middleware may add those prefixes back.&lt;/p&gt;

&lt;h2&gt;
  
  
  5. Data access: layout service factories to &lt;code&gt;SitecoreClient&lt;/code&gt;
&lt;/h2&gt;

&lt;p&gt;Retire the &lt;code&gt;GraphQLLayoutService&lt;/code&gt; and &lt;code&gt;RestLayoutService&lt;/code&gt; factories and the large page-props factory. Replace them with one client:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;SitecoreClient&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s1"&gt;'@sitecore-content-sdk/nextjs/client'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="n"&gt;scConfig&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s1"&gt;'sitecore.config'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;client&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;SitecoreClient&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;scConfig&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;client&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getPage&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;itemPath&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;site&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;locale&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;client&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getDictionary&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;site&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;locale&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="n"&gt;client&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getHeadLinks&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;layoutData&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;options&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If you run custom GraphQL, import &lt;code&gt;GraphQLRequestClient&lt;/code&gt; from &lt;code&gt;@sitecore-content-sdk/nextjs/client&lt;/code&gt; and not from JSS.&lt;/p&gt;

&lt;h2&gt;
  
  
  6. React integration: context and hooks
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;JSS&lt;/th&gt;
&lt;th&gt;Content SDK&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;SitecoreContext&lt;/code&gt; with &lt;code&gt;layoutData&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;SitecoreProvider&lt;/code&gt; with &lt;code&gt;page: Page&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;useSitecoreContext()&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;useSitecore()&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;layoutData.sitecore.context.pageEditing&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;page.mode.isEditing&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;withSitecoreContext&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;withSitecore&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;An editing check after migration looks like this:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;page&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;useSitecore&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;page&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;mode&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;isEditing&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Pass &lt;code&gt;page&lt;/code&gt;, not only raw &lt;code&gt;layoutData&lt;/code&gt;, into the placeholder.&lt;/p&gt;

&lt;p&gt;One caution: because placeholders are client-bound, it is tempting to mark the whole Layout as a client component. Sitecore's own migration notes warn against this, since it cancels out the benefits of the App Router. Keep the main Layout a Server Component where you can, and push the client boundary down to the providers and components that need it.&lt;/p&gt;

&lt;h2&gt;
  
  
  7. Placeholders
&lt;/h2&gt;

&lt;p&gt;&lt;code&gt;&amp;lt;Placeholder name="..." rendering={route} /&amp;gt;&lt;/code&gt; becomes:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight tsx"&gt;&lt;code&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;AppPlaceholder&lt;/span&gt;
  &lt;span class="n"&gt;page&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="n"&gt;page&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="n"&gt;componentMap&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="n"&gt;components&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"..."&lt;/span&gt;
  &lt;span class="n"&gt;rendering&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="n"&gt;route&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="o"&gt;/&amp;gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Nested placeholder keys and rendering UIDs are largely unchanged. Only the component API is different.&lt;/p&gt;

&lt;h2&gt;
  
  
  8. Middleware: multisite, locale, redirects, personalize
&lt;/h2&gt;

&lt;p&gt;JSS used a custom plugin list from its middleware package. The Content SDK gives you ready-made classes:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;defineMiddleware&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nc"&gt;LocaleMiddleware&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nc"&gt;AppRouterMultisiteMiddleware&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nc"&gt;RedirectsMiddleware&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nc"&gt;PersonalizeMiddleware&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s1"&gt;'@sitecore-content-sdk/nextjs/middleware'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="n"&gt;sites&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s1"&gt;'.sitecore/sites.json'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="n"&gt;scConfig&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s1"&gt;'sitecore.config'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="c1"&gt;// Chain: locale, multisite, redirects, personalize&lt;/span&gt;
&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;defineMiddleware&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;locale&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;multisite&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;redirects&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;personalize&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;exec&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;ev&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A version note: in Content SDK 2.x, &lt;code&gt;defineMiddleware&lt;/code&gt; is renamed &lt;code&gt;defineProxy&lt;/code&gt;, in line with Next.js 16. The composition idea is the same, so check which name your SDK version uses.&lt;/p&gt;

&lt;p&gt;Order matters. Run &lt;code&gt;LocaleMiddleware&lt;/code&gt; first when your locales are not only defined in &lt;code&gt;next.config.js&lt;/code&gt; i18n, which is common with App Router and next-intl. Feed &lt;code&gt;sites&lt;/code&gt; from the generated &lt;code&gt;sites.json&lt;/code&gt; and spread the relevant slice of &lt;code&gt;scConfig&lt;/code&gt; into each middleware.&lt;/p&gt;

&lt;h2&gt;
  
  
  9. Experience Editor and Pages builder
&lt;/h2&gt;

&lt;p&gt;JSS used Pages API routes: an editing render route backed by &lt;code&gt;EditingRenderMiddleware&lt;/code&gt;, and an editing data route that cached stashed payloads in Preview Mode.&lt;/p&gt;

&lt;p&gt;The Content SDK replaces these with App Router route handlers:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;app/api/editing/render/route.ts&lt;/code&gt; using &lt;code&gt;createEditingRenderRouteHandlers&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;app/api/editing/config/route.ts&lt;/code&gt; using &lt;code&gt;createEditingConfigRouteHandler&lt;/code&gt;, with the component map, client map and metadata&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The handlers include CORS and OPTIONS handling for the page builder, so there is less custom glue. Set &lt;code&gt;editingSecret&lt;/code&gt; in &lt;code&gt;sitecore.config.ts&lt;/code&gt; and make sure the rendering host URL in Sitecore matches your deployed app.&lt;/p&gt;

&lt;h2&gt;
  
  
  10. Component-level server data
&lt;/h2&gt;

&lt;p&gt;This part barely changes. Components still export &lt;code&gt;getServerSideProps&lt;/code&gt; and read &lt;code&gt;rendering&lt;/code&gt;, layout context and &lt;code&gt;componentProps[uid]&lt;/code&gt; through context. The difference is that you call a small &lt;code&gt;getComponentProps&lt;/code&gt; helper that walks the placeholders on &lt;code&gt;page.layout&lt;/code&gt;, instead of relying on the JSS page-props factory.&lt;/p&gt;

&lt;p&gt;Integrated GraphQL fields still come with the layout from &lt;code&gt;getPage()&lt;/code&gt;. &lt;code&gt;getServerSideProps&lt;/code&gt; is only for extra queries, the same split as before.&lt;/p&gt;

&lt;h2&gt;
  
  
  11. Types and page props
&lt;/h2&gt;

&lt;p&gt;&lt;code&gt;SitecorePageProps&lt;/code&gt; gains a first-class &lt;code&gt;page: Page&lt;/code&gt;. I kept &lt;code&gt;layoutData&lt;/code&gt;, &lt;code&gt;componentProps&lt;/code&gt;, &lt;code&gt;dictionary&lt;/code&gt;, &lt;code&gt;site&lt;/code&gt; and &lt;code&gt;locale&lt;/code&gt; alongside it so I could refactor gradually. Imports move from &lt;code&gt;@sitecore-jss/sitecore-jss-nextjs&lt;/code&gt; to &lt;code&gt;@sitecore-content-sdk/nextjs&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  12. Environment variables checklist
&lt;/h2&gt;

&lt;p&gt;Add or emphasize for Edge:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;SITECORE_EDGE_CONTEXT_ID&lt;/code&gt; and &lt;code&gt;NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;SITECORE_EDGE_URL&lt;/code&gt; and &lt;code&gt;NEXT_PUBLIC_SITECORE_EDGE_URL&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;&lt;code&gt;SITECORE_EDITING_SECRET&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Often retained for local development:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;NEXT_PUBLIC_SITECORE_API_KEY&lt;/code&gt; and &lt;code&gt;NEXT_PUBLIC_SITECORE_API_HOST&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;NEXT_PUBLIC_DEFAULT_SITE_NAME&lt;/code&gt; and &lt;code&gt;NEXT_PUBLIC_DEFAULT_LANGUAGE&lt;/code&gt;
&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Retire or repoint:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;JSS-only disconnected mode variables such as &lt;code&gt;JSS_MODE&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;Debug namespaces like &lt;code&gt;sitecore-jss:*&lt;/code&gt;. Confirm the Content SDK logging names in the docs.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  13. BYOC and FEAAS
&lt;/h2&gt;

&lt;p&gt;BYOC bundles still use &lt;code&gt;@sitecore-feaas/clientside&lt;/code&gt;. The context usually comes from &lt;code&gt;SitecoreProviderReactContext&lt;/code&gt; and &lt;code&gt;page.layout.sitecore.context&lt;/code&gt; for page state, with the Edge URL and context ID taken from &lt;code&gt;sitecore.config&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Suggested migration order
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;Upgrade Next.js and adopt the App Router, or start from Sitecore's official Content SDK starter.&lt;/li&gt;
&lt;li&gt;Swap packages and add &lt;code&gt;sitecore.config.ts&lt;/code&gt; and &lt;code&gt;sitecore.cli.config.ts&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Wire build scripts and generate the &lt;code&gt;.sitecore/&lt;/code&gt; artifacts.&lt;/li&gt;
&lt;li&gt;Replace the catch-all data fetching with &lt;code&gt;SitecoreClient.getPage&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Replace &lt;code&gt;SitecoreContext&lt;/code&gt; with &lt;code&gt;SitecoreProvider&lt;/code&gt; and the component map.&lt;/li&gt;
&lt;li&gt;Run a global find-and-replace for imports, &lt;code&gt;useSitecore&lt;/code&gt;, &lt;code&gt;AppPlaceholder&lt;/code&gt; and the editing routes.&lt;/li&gt;
&lt;li&gt;Port middleware to the Content SDK classes and &lt;code&gt;sites.json&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Remove the layout service factories, old page-props plugins, &lt;code&gt;pages/[[...path]]&lt;/code&gt; and the archived editing API routes.&lt;/li&gt;
&lt;li&gt;Regression test production paths, multisite, preview and editing, personalization and ISR or revalidation.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Gotchas
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Forgetting the pre-build step.&lt;/strong&gt; If &lt;code&gt;sitecore-tools&lt;/code&gt; does not run before &lt;code&gt;next build&lt;/code&gt;, the &lt;code&gt;.sitecore/&lt;/code&gt; imports are missing and the build fails.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Client and server split on the layout.&lt;/strong&gt; Marking the whole Layout as a client component undoes the App Router benefits. Keep it a Server Component where possible and keep client boundaries small. Pass &lt;code&gt;page&lt;/code&gt; into the placeholders.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Version drift.&lt;/strong&gt; Names such as &lt;code&gt;defineMiddleware&lt;/code&gt; and &lt;code&gt;defineProxy&lt;/code&gt; differ between Content SDK 1.x and 2.x, so match the code to the guide for your version.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Experience Editor is gone.&lt;/strong&gt; The Content SDK supports visual editing only through the page builder, and Content Editor preview is not supported. Plan for that if your editors still rely on it.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Reimplementing component props walking.&lt;/strong&gt; Use a single &lt;code&gt;getComponentProps&lt;/code&gt; helper and do not scatter this logic.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Middleware order with i18n.&lt;/strong&gt; Run locale handling first, then multisite, redirects and personalize.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Why this approach
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Typed, central config.&lt;/strong&gt; One &lt;code&gt;sitecore.config.ts&lt;/code&gt; replaces scattered keys and generated config.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;App Router and Edge-first client.&lt;/strong&gt; Server Components fetch the page directly with &lt;code&gt;SitecoreClient&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Simpler editing setup.&lt;/strong&gt; Route handlers replace most of the custom editing middleware.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Small blast radius.&lt;/strong&gt; Item structure, rendering names and most presentation components stay as they are. Only the adapter layer and SDK imports change.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  What I would improve next
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Add automated tests around &lt;code&gt;getComponentProps&lt;/code&gt; and the middleware chain.&lt;/li&gt;
&lt;li&gt;Add a CI check that fails fast when &lt;code&gt;sitecore-tools&lt;/code&gt; has not generated &lt;code&gt;.sitecore/&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Document a rollback path for multisite and personalization during cutover.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Further reading
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;a href="https://developers.sitecore.com/learn/getting-started/sitecoreai/content-sdk/jss-to-content-sdk-upgrade" rel="noopener noreferrer"&gt;JSS to Content SDK upgrade&lt;/a&gt;, Sitecore's overview of the migration paths, including a first-hand account.&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://doc.sitecore.com/sai/developers/content-sdk/20/upgrade-jss-22-0-next-js-apps-to-content-sdk-2-1.html" rel="noopener noreferrer"&gt;Upgrade JSS 22.0 Next.js apps to Content SDK 2.1&lt;/a&gt;, the step-by-step guide for the latest version.&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://doc.sitecore.com/sai/developers/content-sdk/10/upgrade-your-jss-22-9-22-10-next-js-apps-to-content-sdk-1-3-1.html" rel="noopener noreferrer"&gt;Upgrade your JSS 22.9/22.10 Next.js apps to Content SDK 1.3.1&lt;/a&gt;, which includes the App Router general release.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Wrap up
&lt;/h2&gt;

&lt;p&gt;Moving from JSS to the Content SDK is mostly a plumbing exercise: one typed config, generated &lt;code&gt;.sitecore/&lt;/code&gt; artifacts, the App Router, one &lt;code&gt;SitecoreClient&lt;/code&gt;, and updated providers, hooks and middleware. Your content model and most components carry over.&lt;/p&gt;

&lt;p&gt;If you are planning this migration, start by upgrading to the App Router and generating the &lt;code&gt;.sitecore/&lt;/code&gt; artifacts, then work through the data fetching and provider changes in the order above.&lt;/p&gt;

&lt;p&gt;I would love to hear what tripped you up when moving from JSS to the Content SDK. Let me know in the comments.&lt;/p&gt;

</description>
      <category>sitecore</category>
      <category>nextjs</category>
      <category>xmcloud</category>
      <category>headless</category>
    </item>
    <item>
      <title>Hierarchical Facets in Sitecore Search: Building an Expandable Tree UI</title>
      <dc:creator>Rahul Nair</dc:creator>
      <pubDate>Wed, 18 Nov 2026 12:35:37 +0000</pubDate>
      <link>https://dev.to/rahulnair-labs/hierarchical-facets-in-sitecore-search-building-an-expandable-tree-ui-mfg</link>
      <guid>https://dev.to/rahulnair-labs/hierarchical-facets-in-sitecore-search-building-an-expandable-tree-ui-mfg</guid>
      <description>&lt;h2&gt;
  
  
  The problem
&lt;/h2&gt;

&lt;p&gt;Sitecore Search facet responses are flat arrays of &lt;code&gt;{ id, text, count }&lt;/code&gt;. That works for checkboxes, but not when content teams think in taxonomies (industry → sub-industry → detail) and users expect expand/collapse, breadcrumb chips and parent/child selection. Search does not return a nested facet tree.&lt;/p&gt;

&lt;h2&gt;
  
  
  The solution
&lt;/h2&gt;

&lt;p&gt;Keep the hierarchy in the facet text as a path string, like &lt;code&gt;Healthcare|Commercial|Property&lt;/code&gt;. Emit those strings into the index, filter with facet &lt;strong&gt;value IDs&lt;/strong&gt;, and rebuild the tree in React by parsing the text.&lt;/p&gt;

&lt;p&gt;The pipeline: &lt;strong&gt;tag meta → index fields → &lt;code&gt;setSearchFacet&lt;/code&gt; → client-side tree&lt;/strong&gt;.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Add a screenshot of the facet tree here.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h3&gt;
  
  
  Three delimiters, three jobs
&lt;/h3&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Delimiter&lt;/th&gt;
&lt;th&gt;Where&lt;/th&gt;
&lt;th&gt;Purpose&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;`\&lt;/td&gt;
&lt;td&gt;`&lt;/td&gt;
&lt;td&gt;Inside one value / &lt;code&gt;facet.text&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;`\&lt;/td&gt;
&lt;td&gt;\&lt;/td&gt;
&lt;td&gt;`&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;,&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;URL query and &lt;code&gt;filter.values&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Multiple selected facet IDs&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The most common bug is putting &lt;code&gt;Healthcare|Commercial&lt;/code&gt; in the URL instead of the facet value ID returned by Search.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 1: Tags in the index
&lt;/h2&gt;

&lt;p&gt;For every hierarchical tag, emit each level you want facetable: &lt;code&gt;Healthcare&lt;/code&gt;, &lt;code&gt;Healthcare|Commercial&lt;/code&gt;, &lt;code&gt;Healthcare|Commercial|Property&lt;/code&gt;. Siblings in the same meta attribute are joined with &lt;code&gt;||&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight html"&gt;&lt;code&gt;&lt;span class="nt"&gt;&amp;lt;meta&lt;/span&gt;
  &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s"&gt;"industryTags"&lt;/span&gt;
  &lt;span class="na"&gt;content&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s"&gt;"Healthcare||Healthcare|Commercial||Healthcare|Commercial|Property"&lt;/span&gt;
&lt;span class="nt"&gt;/&amp;gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The crawler's document extractor splits on &lt;code&gt;||&lt;/code&gt; into index fields:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;splitMetaList&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;content&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt;
  &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;content&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="s2"&gt;""&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;split&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"||"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;map&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;s&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;s&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;trim&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;filter&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;Boolean&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nb"&gt;document&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;topic_tags&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nf"&gt;splitMetaList&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;meta&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;topicTags&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;industry_tags&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nf"&gt;splitMetaList&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;meta&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;industryTags&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Each array element becomes a facetable value. Strings containing &lt;code&gt;|&lt;/code&gt; stay whole; the UI splits them later.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Important:&lt;/strong&gt; the facet field name in Search (and your CMS component's &lt;code&gt;facetid&lt;/code&gt;) must match the document property, for example &lt;code&gt;industry_tags&lt;/code&gt;, not the label "Industry".&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  Step 2: Sending filters to Sitecore Search
&lt;/h2&gt;

&lt;p&gt;On every query, pass facet types. Add an &lt;code&gt;or&lt;/code&gt; filter of IDs when the URL carries a selection:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;facetTypesFromUrl&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="n"&gt;facets&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;searchParams&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;URLSearchParams&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;facets&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;map&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;facet&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;ids&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;searchParams&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;facet&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;split&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;","&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;filter&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;Boolean&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;ids&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;length&lt;/span&gt;
      &lt;span class="o"&gt;?&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;facet&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;filter&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"or"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;values&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;ids&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
      &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;facet&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;name&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;setSearchFacet&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;types&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nf"&gt;facetTypesFromUrl&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"topic_tags"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"industry_tags"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;searchParams&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A URL like &lt;code&gt;/search?q=insurance&amp;amp;industry_tags=facetid_abc123,facetid_def456&lt;/code&gt; becomes:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"facet"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nl"&gt;"types"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
      &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;"name"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"topic_tags"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="nl"&gt;"name"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"industry_tags"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="nl"&gt;"filter"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;"type"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"or"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nl"&gt;"values"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"facetid_abc123"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"facetid_def456"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
      &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="p"&gt;]&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;setSearchFacet&lt;/code&gt; both applies the filters and returns updated buckets for the UI.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;From click to API:&lt;/strong&gt; a toggle in the facet UI runs cascade logic (parent plus descendants on select, careful ancestor cleanup on deselect), updates the URL with comma-separated IDs, fires &lt;code&gt;onFacetClick&lt;/code&gt; / &lt;code&gt;onFilterClick&lt;/code&gt; per ID so widget state matches, and the next request picks up the new filters. Only the &lt;code&gt;id&lt;/code&gt; goes in the URL; &lt;code&gt;text&lt;/code&gt; stays for display.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 3: Building the tree
&lt;/h2&gt;

&lt;p&gt;Sort shallow paths first, map paths to nodes, then attach children:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="no"&gt;FACET_PATH_DELIMITER&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"|"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;type&lt;/span&gt; &lt;span class="nc"&gt;FacetValue&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="n"&gt;text&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="n"&gt;count&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;number&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;type&lt;/span&gt; &lt;span class="nc"&gt;FacetTreeNode&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;value&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;FacetValue&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="n"&gt;label&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="n"&gt;depth&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;number&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="n"&gt;children&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;FacetTreeNode&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;buildFacetTree&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;values&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;FacetValue&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;FacetTreeNode&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;sorted&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;values&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;sort&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;a&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;b&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt;
      &lt;span class="n"&gt;a&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;text&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;split&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="no"&gt;FACET_PATH_DELIMITER&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;length&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt;
      &lt;span class="n"&gt;b&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;text&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;split&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="no"&gt;FACET_PATH_DELIMITER&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;length&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;byPath&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nb"&gt;Map&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;FacetTreeNode&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;roots&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;FacetTreeNode&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;value&lt;/span&gt; &lt;span class="k"&gt;of&lt;/span&gt; &lt;span class="n"&gt;sorted&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;parts&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;value&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;text&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;split&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="no"&gt;FACET_PATH_DELIMITER&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;node&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;FacetTreeNode&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="n"&gt;value&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;label&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;parts&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;parts&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;length&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;trim&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="n"&gt;value&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;text&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;depth&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;parts&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;length&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;children&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;byPath&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;set&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;value&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;text&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;node&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;parent&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;byPath&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;parts&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;slice&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;join&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="no"&gt;FACET_PATH_DELIMITER&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;parts&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;length&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="n"&gt;parent&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;parent&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;children&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;push&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;node&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;else&lt;/span&gt; &lt;span class="n"&gt;roots&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;push&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;node&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// no parent in the bucket: still show the node&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;roots&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  What the facet looks like
&lt;/h3&gt;

&lt;p&gt;The API returns a flat list for &lt;code&gt;industry_tags&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;[&lt;/span&gt;
  &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;"id"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"facetid_a1"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nl"&gt;"text"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Healthcare"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nl"&gt;"count"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;42&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;"id"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"facetid_a2"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nl"&gt;"text"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Healthcare|Commercial"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nl"&gt;"count"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;18&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;"id"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"facetid_a3"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nl"&gt;"text"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Healthcare|Commercial|Property"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nl"&gt;"count"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;7&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;"id"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"facetid_a4"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nl"&gt;"text"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Healthcare|Commercial|Casualty"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nl"&gt;"count"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;5&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;"id"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"facetid_a5"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nl"&gt;"text"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Healthcare|Public Sector"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nl"&gt;"count"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;12&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;"id"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"facetid_b1"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nl"&gt;"text"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Energy"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nl"&gt;"count"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;30&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;]&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The tree renders it with parents, two-level children and three-level children:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Industry
 ☐ ▾ Healthcare (42)                     ← parent (level 1)
      ☐ ▾ Commercial (18)                ← child (level 2)
           ☐ Property (7)                ← grandchild (level 3)
           ☐ Casualty (5)                ← grandchild (level 3)
      ☐ ▸ Public Sector (12)             ← child (level 2, collapsed)
 ☐ ▸ Energy (30)                         ← parent (level 1, collapsed)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Selecting &lt;code&gt;Commercial&lt;/code&gt; cascades to its descendants and sends all three IDs:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt; ▣ ▾ Healthcare (42)                     ← partial (ancestor, not in the URL)
      ☑ ▾ Commercial (18)
           ☑ Property (7)
           ☑ Casualty (5)

Active filters:  [ Healthcare &amp;gt; Commercial × ]
URL:  ?industry_tags=facetid_a2,facetid_a3,facetid_a4
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;UX details that matter:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Checkbox label is the last segment only (&lt;code&gt;Commercial&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;Active filter chips show breadcrumbs: &lt;code&gt;Healthcare &amp;gt; Commercial &amp;gt; Property&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;The in-facet filter box prunes the tree but keeps branches with matches.&lt;/li&gt;
&lt;li&gt;A child appears checked when an ancestor ID is selected.&lt;/li&gt;
&lt;li&gt;Expand/collapse is local state, auto-expanding on search or when a descendant is selected.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Keep cascade and chip deduplication in small pure helpers so the facet component only renders.&lt;/p&gt;

&lt;h2&gt;
  
  
  Gotchas
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Path strings in filters.&lt;/strong&gt; If results come back empty, check that the URL and &lt;code&gt;filter.values&lt;/code&gt; hold facet IDs, not &lt;code&gt;Parent|Child&lt;/code&gt; labels.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A &lt;code&gt;|&lt;/code&gt; inside a label&lt;/strong&gt; breaks the tree. Escape it or change the delimiter.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Large taxonomies&lt;/strong&gt; need facet pagination, often sorted by text ascending for cursor stability.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Why this approach
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Works with the stock widget: &lt;code&gt;setSearchFacet&lt;/code&gt;, facet IDs and &lt;code&gt;or&lt;/code&gt; filters are the documented contract.&lt;/li&gt;
&lt;li&gt;Thin CMS, explicit index contract: hierarchy is just path strings on index fields.&lt;/li&gt;
&lt;li&gt;You own the UX: tree, in-facet search, cascade and chips are testable TypeScript.&lt;/li&gt;
&lt;li&gt;One tag-building module can feed both the crawler and API-pushed documents.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  What I would improve next
&lt;/h2&gt;

&lt;blockquote&gt;
&lt;p&gt;Add your own ideas here, for example facet pagination, delimiter escaping, or unit tests for the cascade helpers.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  Wrap up
&lt;/h2&gt;

&lt;p&gt;Hierarchical facets in Sitecore Search are path-shaped strings in the index, ID-based filters in the request, and a tree algorithm in the browser. If you are building something similar, start by confirming that facet text looks like &lt;code&gt;Parent|Child&lt;/code&gt; and that each path has a stable &lt;code&gt;id&lt;/code&gt;. After that, the tree and cascade code is mostly mechanical.&lt;/p&gt;

&lt;p&gt;I would love to hear how you handle taxonomies in your own Sitecore Search projects. Let me know in the comments.&lt;/p&gt;

</description>
      <category>sitecore</category>
      <category>nextjs</category>
      <category>headless</category>
      <category>search</category>
    </item>
    <item>
      <title>Managing Redirects Without Redeploys: A Sitecore Marketplace App Built on Vercel Global Config</title>
      <dc:creator>Rahul Nair</dc:creator>
      <pubDate>Tue, 17 Nov 2026 12:25:07 +0000</pubDate>
      <link>https://dev.to/rahulnair-labs/managing-redirects-without-redeploys-a-sitecore-marketplace-app-built-on-vercel-global-config-93b</link>
      <guid>https://dev.to/rahulnair-labs/managing-redirects-without-redeploys-a-sitecore-marketplace-app-built-on-vercel-global-config-93b</guid>
      <description>&lt;h2&gt;
  
  
  The problem
&lt;/h2&gt;

&lt;p&gt;On a headless Sitecore site, redirects usually end up in one of two places: hardcoded in the Next.js app (&lt;code&gt;next.config.js&lt;/code&gt; or middleware), or managed inside the CMS. The first means every redirect change needs a code change and a redeploy. The second can be heavy, and it ties redirect handling to content publishing.&lt;/p&gt;

&lt;p&gt;I wanted something simpler: a small admin UI where redirects can be added, edited or deleted, and the change goes live without touching the headless application's code or triggering a deployment.&lt;/p&gt;

&lt;h2&gt;
  
  
  The solution
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Redirect Manager&lt;/strong&gt; is a Sitecore Marketplace extension that manages pathname redirects stored in &lt;strong&gt;Vercel Global Config&lt;/strong&gt;. Global Config is a globally distributed key-value store on Vercel, built for configuration data that is read often and changed rarely. That fits redirect rules well.&lt;/p&gt;

&lt;p&gt;The extension stores all rules under a single item called &lt;code&gt;redirects&lt;/code&gt;. It reads and writes that item, and it does not modify the main headless application.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Add a screenshot of the dashboard here.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  How it works
&lt;/h2&gt;

&lt;p&gt;The flow is straightforward:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;A user opens the dashboard inside Sitecore as a full-screen Marketplace extension.&lt;/li&gt;
&lt;li&gt;They pick a Global Config from a dropdown, which lists only the configs you have connected through environment variables.&lt;/li&gt;
&lt;li&gt;They list, add, edit or delete redirect rules.&lt;/li&gt;
&lt;li&gt;The extension writes the change to Global Config through the Vercel API.&lt;/li&gt;
&lt;li&gt;If configured, it calls a revalidate endpoint on the headless app so the cached redirect rules are cleared and the new rules take effect.&lt;/li&gt;
&lt;/ol&gt;

&lt;h3&gt;
  
  
  Routes
&lt;/h3&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Route&lt;/th&gt;
&lt;th&gt;Marketplace extension point&lt;/th&gt;
&lt;th&gt;Purpose&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;/&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Standalone (optional)&lt;/td&gt;
&lt;td&gt;Landing page with a link to the dashboard&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;/dashboard&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Full screen&lt;/td&gt;
&lt;td&gt;Pick a Global Config, then list, add, edit and delete &lt;code&gt;redirects&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;/api/global-configs&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;n/a&lt;/td&gt;
&lt;td&gt;Lists Global Configs through the Vercel API&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;/api/redirects&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;n/a&lt;/td&gt;
&lt;td&gt;Lists, creates, updates and deletes &lt;code&gt;redirects&lt;/code&gt;, and purges the headless app's redirect cache when configured&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;/api/redirects/revalidate-cache&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;n/a&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;POST&lt;/code&gt; that clears the &lt;code&gt;site:global-config:redirects&lt;/code&gt; cache on the headless app (used by the dashboard button)&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h3&gt;
  
  
  The redirect shape
&lt;/h3&gt;

&lt;p&gt;All rules live under a single &lt;code&gt;redirects&lt;/code&gt; key in Global Config. Each rule is keyed by the source path, with a destination and a status code:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"redirects"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nl"&gt;"/old-blog"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="nl"&gt;"destination"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"/blog"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nl"&gt;"status"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;301&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"/legacy/pricing"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="nl"&gt;"destination"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"/pricing"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nl"&gt;"status"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;301&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The rules are simple on purpose:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Sources must start with &lt;code&gt;/&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Setup
&lt;/h2&gt;

&lt;h3&gt;
  
  
  Environment variables
&lt;/h3&gt;

&lt;p&gt;Copy &lt;code&gt;.env.local.example&lt;/code&gt; to &lt;code&gt;.env.local&lt;/code&gt; and fill in the values:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Variable&lt;/th&gt;
&lt;th&gt;Required&lt;/th&gt;
&lt;th&gt;Purpose&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;GLOBAL_CONFIG_REDIRECTS_1&lt;/code&gt; to &lt;code&gt;_3&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Yes (read)&lt;/td&gt;
&lt;td&gt;Global Config connection strings, one per config you use&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;VERCEL_API_TOKEN&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Yes (write)&lt;/td&gt;
&lt;td&gt;Used for &lt;code&gt;PATCH /v1/global-config/{id}/items&lt;/code&gt; (&lt;a href="https://vercel.com/docs/global-config/vercel-api" rel="noopener noreferrer"&gt;Vercel API docs&lt;/a&gt;)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;GLOBAL_CONFIG_ID&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;td&gt;Overrides the &lt;code&gt;ecfg_...&lt;/code&gt; ID if needed; otherwise it is parsed from the connection string&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;VERCEL_TEAM_ID&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Team stores&lt;/td&gt;
&lt;td&gt;Required as &lt;code&gt;?teamId=&lt;/code&gt; on PATCH when the config is not on your personal Hobby scope&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;NEXT_PUBLIC_APP_BASE_URL&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Cache purge button&lt;/td&gt;
&lt;td&gt;Origin of the headless app, for example &lt;code&gt;http://localhost:3000&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;SITECORE_REVALIDATE_SECRET&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Cache purge button&lt;/td&gt;
&lt;td&gt;Must match the headless app; sent as the &lt;code&gt;x-revalidate-secret&lt;/code&gt; header&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Security note:&lt;/strong&gt; &lt;code&gt;.env.local&lt;/code&gt; holds your Vercel API token and secrets. Keep it in &lt;code&gt;.gitignore&lt;/code&gt; and never commit it. If a token ever ends up in a public repo, revoke it and create a new one.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h3&gt;
  
  
  Run it locally
&lt;/h3&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;cd&lt;/span&gt; extensions/RedirectManager
pnpm install
pnpm dev
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Then open &lt;code&gt;http://localhost:3000/dashboard&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Reading the redirects in your Next.js app
&lt;/h2&gt;

&lt;p&gt;The extension only manages the data. The headless app reads the &lt;code&gt;redirects&lt;/code&gt; item and applies it at request time. Vercel's guide covers the basic proxy approach: &lt;a href="https://vercel.com/kb/guide/dynamic-redirects-with-global-config-and-next-js-proxy" rel="noopener noreferrer"&gt;Dynamic redirects with Global Config and Next.js proxy&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;That guide reads Global Config on every request. I wrapped the read in a tagged remote cache, so the rules are fetched once per cache window and the extension can purge them on demand:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// lib/redirects.ts&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;get&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s1"&gt;'@vercel/global-config'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;cacheLife&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;cacheTag&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s1"&gt;'next/cache'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="no"&gt;REDIRECTS_TAG&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s1"&gt;'site:global-config:redirects'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;getRedirects&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="s1"&gt;'use cache: remote'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nf"&gt;cacheTag&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="no"&gt;REDIRECTS_TAG&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="nf"&gt;cacheLife&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'minutes'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'redirects'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;When the extension saves or deletes a rule, it calls the revalidate endpoint, which runs &lt;code&gt;revalidateTag(REDIRECTS_TAG, 'max')&lt;/code&gt; and clears the cache.&lt;/p&gt;

&lt;h3&gt;
  
  
  Things to check
&lt;/h3&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Next.js version:&lt;/strong&gt; &lt;code&gt;use cache: remote&lt;/code&gt; and the two-argument &lt;code&gt;revalidateTag(tag, 'max')&lt;/code&gt; are Next.js 16 features. On Next.js 15, use &lt;code&gt;unstable_cache&lt;/code&gt; with &lt;code&gt;revalidateTag(tag)&lt;/code&gt; instead.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Cache Components:&lt;/strong&gt; &lt;code&gt;use cache&lt;/code&gt; must be enabled in &lt;code&gt;next.config.ts&lt;/code&gt; with &lt;code&gt;cacheComponents: true&lt;/code&gt;, otherwise the build fails.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Directive placement:&lt;/strong&gt; put the directive inside the function body (as above) or at the top of the file, as a string statement.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Proxy limitation:&lt;/strong&gt; call &lt;code&gt;getRedirects()&lt;/code&gt; from a route handler (for example &lt;code&gt;/api/redirects-cache&lt;/code&gt;) and have the proxy fetch it, instead of calling it in &lt;code&gt;proxy.ts&lt;/code&gt; directly. Exclude &lt;code&gt;/api&lt;/code&gt; in the proxy &lt;code&gt;matcher&lt;/code&gt; to avoid a redirect loop.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Cache lifetime:&lt;/strong&gt; &lt;code&gt;cacheLife('minutes')&lt;/code&gt; is a built-in profile. Use &lt;code&gt;cacheLife({ revalidate: 300 })&lt;/code&gt; for an explicit 5-minute window.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Public route:&lt;/strong&gt; &lt;code&gt;/api/redirects-cache&lt;/code&gt; returns your rules to anyone who requests it, so don't store anything sensitive in them.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  App screenshots
&lt;/h2&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fk47esp1t5s1h7anuuzz8.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fk47esp1t5s1h7anuuzz8.png" alt=" " width="800" height="586"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Marketplace App Configurations
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;Update the dashboard url(/dashboard) in the route url in Stand alone and Full screen.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fd86fwsv3l1w0fex28nih.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fd86fwsv3l1w0fex28nih.png" alt=" " width="800" height="393"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Update the deployment url(Non-prod/prod deployment url can be updated here)&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Note : For local development the localhost url can be updated - &lt;a href="http://localhost:3000" rel="noopener noreferrer"&gt;http://localhost:3000&lt;/a&gt;) &lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fqqq32wh7a0iij7238ibj.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fqqq32wh7a0iij7238ibj.png" alt=" " width="800" height="135"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Gotchas
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;PATCH returns &lt;code&gt;404&lt;/code&gt; or &lt;code&gt;not_found&lt;/code&gt;.&lt;/strong&gt; Check that your &lt;code&gt;VERCEL_API_TOKEN&lt;/code&gt; is scoped to the same team as the Global Config store, and set &lt;code&gt;VERCEL_TEAM_ID&lt;/code&gt;. This is the most likely problem if reads work but writes fail.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Changes do not appear on the site.&lt;/strong&gt; The headless app caches redirect rules. On save and delete, the extension calls &lt;code&gt;POST /api/admin/global-config-redirects/revalidate&lt;/code&gt; when &lt;code&gt;NEXT_PUBLIC_APP_BASE_URL&lt;/code&gt; and &lt;code&gt;SITECORE_REVALIDATE_SECRET&lt;/code&gt; are both set. If they are not set, use the &lt;strong&gt;Purge redirects cache&lt;/strong&gt; button on the dashboard.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why this approach
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;No redeploys for redirect changes.&lt;/strong&gt; Rules live in Global Config, not in the app's code.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Globally distributed.&lt;/strong&gt; Global Config is built for fast reads close to users.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Separate from the headless app.&lt;/strong&gt; The extension does not modify the main application, so it is easy to adopt or remove.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Simple data model.&lt;/strong&gt; One item, one JSON shape, easy to inspect and debug.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  What I would improve next
&lt;/h2&gt;

&lt;blockquote&gt;
&lt;p&gt;Add your own ideas here, for example bulk import from CSV, validation for redirect loops, audit history of who changed what, or wildcard and regex rules.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  Wrap up
&lt;/h2&gt;

&lt;p&gt;If you manage redirects on a headless Sitecore site, moving them out of code and into a small managed store takes a recurring chore off the development team.&lt;/p&gt;

&lt;p&gt;The source is here: &lt;a href="https://github.com/rahulnair-labs/vercel-redirects" rel="noopener noreferrer"&gt;https://github.com/rahulnair-labs/vercel-redirects&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;I would love to hear how you handle redirects in your own Sitecore projects. Let me know in the comments.&lt;/p&gt;

</description>
      <category>sitecore</category>
      <category>nextjs</category>
      <category>vercel</category>
      <category>headless</category>
    </item>
  </channel>
</rss>
