Create Shareable POC Pages in a SitecoreAI Project and Keep Them Out of Production

// next.config.js
/**
 * `.dev.tsx` / `.dev.ts` pages are routable in every environment except PROD,
 * so POC and test pages ship to DEV/QA/UAT for review.
 * NOTE: for the Pages Router this is not enough on its own; see "strip-dev-pages".
 */
const isProd = process.env.NEXT_PUBLIC_ENV === "PROD";
const baseExtensions = ["tsx", "ts", "jsx", "js"];
const pageExtensions = isProd ? baseExtensions : [...baseExtensions, "dev.tsx", "dev.ts"];

/** @type {import('next').NextConfig} */
const nextConfig = {
  pageExtensions,
  // ...
};

module.exports = nextConfig;

// src/Layout.tsx (simplified; keep your existing head, scripts, design-library handling)
import type { JSX, ReactNode } from "react";
import { Placeholder, type Page } from "@sitecore-content-sdk/nextjs";
import SitecoreStyles from "src/components/content-sdk/SitecoreStyles";

interface LayoutProps {
  page: Page;
  /** When provided, replaces the main placeholder. POC pages use this to borrow the header and footer. */
  mainReplacementChildren?: ReactNode;
}

const Layout = ({ page, mainReplacementChildren }: LayoutProps): JSX.Element => {
  const { route } = page.layout.sitecore;

  return (
    <>
      <SitecoreStyles layoutData={page.layout} />
      <header>
        <div id="header">{route && <Placeholder name="headless-header" rendering={route} />}</div>
      </header>
      <main>
        <div id="content">
          {mainReplacementChildren ?? (route && <Placeholder name="headless-main" rendering={route} />)}
        </div>
      </main>
      <footer>
        <div id="footer">{route && <Placeholder name="headless-footer" rendering={route} />}</div>
      </footer>
    </>
  );
};

export default Layout;

// src/poc/lib/without-placeholders.ts
import type { Page } from "@sitecore-content-sdk/nextjs";

/** Returns a copy of the page whose route no longer contains the named placeholders. */
export const withoutPlaceholders = (page: Page, names: readonly string[]): Page => {
  const route = page.layout.sitecore.route;
  if (!route) return page;

  const placeholders = Object.fromEntries(Object.entries(route.placeholders).filter(([name]) => !names.includes(name)));

  return {
    ...page,
    layout: {
      ...page.layout,
      sitecore: { ...page.layout.sitecore, route: { ...route, placeholders } },
    },
  };
};

// src/poc/lib/get-poc-server-side-props.ts
import type { GetServerSideProps } from "next";
import client from "lib/sitecore-client";
// @ts-ignore - generated by the Content SDK CLI at build time
import components from ".sitecore/component-map";
import { withoutPlaceholders } from "./without-placeholders";

/** Placeholders the POC page replaces, so we don't fetch server props for them. */
const REPLACED_PLACEHOLDERS = ["headless-main"] as const;

/** Item whose header/footer the POC borrows. Override per request with ?shell=/some/path. */
const DEFAULT_SHELL_PATH = "/";

export const getPocServerSideProps: GetServerSideProps = async (context) => {
  const { shell, site } = context.query;
  const shellPath = typeof shell === "string" ? shell : DEFAULT_SHELL_PATH;

  const fullPage = await client.getPage(shellPath, {
    locale: context.locale,
    site: typeof site === "string" ? site : undefined,
  });
  if (!fullPage) return { notFound: true };

  const page = withoutPlaceholders(fullPage, REPLACED_PLACEHOLDERS);

  return {
    props: {
      page,
      dictionary: await client.getDictionary({ site: page.siteName, locale: page.locale }),
      componentProps: await client.getComponentData(page.layout, context, components),
    },
  };
};

// src/pages/poc/card-playground.dev.tsx
import type { JSX } from "react";
import Head from "next/head";
import type { SitecorePageProps } from "@sitecore-content-sdk/nextjs";
import Layout from "src/Layout";
import Providers from "src/Providers";
import CardPlayground from "src/poc/components/CardPlayground/CardPlayground";
import { getPocServerSideProps } from "src/poc/lib/get-poc-server-side-props";

const CardPlaygroundPage = ({ page, componentProps }: SitecorePageProps): JSX.Element | null => {
  if (!page) return null;

  return (
    <Providers page={page} componentProps={componentProps}>
      <Layout page={page} mainReplacementChildren={<CardPlayground />} />
      {/* After <Layout>: next/head keeps the last <title> rendered, so this overrides the shell's title. */}
      <Head>
        <title>POC: Card playground</title>
        <meta name="robots" content="noindex, nofollow" />
      </Head>
    </Providers>
  );
};

export default CardPlaygroundPage;

export const getServerSideProps = getPocServerSideProps;

// src/poc/components/CardPlayground/CardPlayground.tsx
import { useState, type JSX } from "react";
import { useSitecore } from "@sitecore-content-sdk/nextjs";
import { useI18n } from "next-localization";
import PromoCard from "src/poc/components/PromoCard/PromoCard";

/** Mock fields in the exact shape the layout service returns, so promotion later is a drop-in. */
const MOCK_FIELDS = {
  heading: { value: "Spring product launch" },
  body: { value: "<p>Everything you need to know before launch day.</p>" },
  link: { value: { href: "/news", text: "Read more" } },
};

const VARIANTS = ["default", "compact", "featured"] as const;
type Variant = (typeof VARIANTS)[number];

const CardPlayground = (): JSX.Element => {
  const { page } = useSitecore();
  const { t } = useI18n();
  const [variant, setVariant] = useState<Variant>("default");

  return (
    <section className="container mx-auto py-8">
      <p>
        Site: {page.siteName} | Locale: {page.locale} | Dictionary check: {t("ReadMore")}
      </p>

      <fieldset>
        <legend>Variant</legend>
        {VARIANTS.map((option) => (
          <label key={option}>
            <input type="radio" name="variant" checked={variant === option} onChange={() => setVariant(option)} />{" "}
            {option}
          </label>
        ))}
      </fieldset>

      <PromoCard fields={MOCK_FIELDS} variant={variant} />
    </section>
  );
};

export default CardPlayground;

import * as Hero from 'src/components/poc/Hero/Hero';
import * as Hero from 'src/components/Hero/Hero';
// ...
  ['Hero', { ...Hero }],
  ['Hero', { ...Hero }],

src/poc/components/CardPlayground/CardPlayground.tsx
src/poc/lib/get-poc-server-side-props.ts

// sitecore.cli.config.ts
import { defineCliConfig } from "@sitecore-content-sdk/nextjs/config-cli";
import { generateSites, generateMetadata, extractFiles, writeImportMap } from "@sitecore-content-sdk/nextjs/tools";
import scConfig from "./sitecore.config";

/** POC-only components: imported directly by .dev pages, never rendered by Sitecore. */
const POC_COMPONENTS = "src/components/poc/**";

export default defineCliConfig({
  config: scConfig,
  build: {
    commands: [
      generateMetadata(),
      generateSites(),
      extractFiles(),
      writeImportMap({
        paths: ["src/components/content-sdk"],
        exclude: [POC_COMPONENTS], // only needed if paths includes src/components (App Router template does)
      }),
    ],
  },
  componentMap: {
    paths: ["src/components"],
    exclude: ["src/components/content-sdk/*", "**/*.stories.*", POC_COMPONENTS],
  },
});

# After `sitecore-tools project component generate-map`
if grep -q "/poc/" .sitecore/component-map.ts; then
  echo "POC components leaked into the Sitecore component map" && exit 1
fi

Route (pages)
┌ ○ /
├ ○ /404
└ ○ /poc/demo.dev        <- the "excluded" POC page, live at a new URL

// scripts/strip-dev-pages.mjs
import { readdir, rm } from "node:fs/promises";
import path from "node:path";

const DEV_PAGE = /\.dev\.(tsx?|jsx?)$/;

if (process.env.NEXT_PUBLIC_ENV !== "PROD" || !process.env.CI) {
  console.log("[strip-dev-pages] Not a CI production build; leaving .dev pages in place.");
  process.exit(0);
}

const pagesDir = path.resolve("src/pages");
const entries = await readdir(pagesDir, { recursive: true, withFileTypes: true });
const devPages = entries.filter((entry) => entry.isFile() && DEV_PAGE.test(entry.name));

await Promise.all(devPages.map((entry) => rm(path.join(entry.parentPath, entry.name))));
console.log(`[strip-dev-pages] Removed ${devPages.length} .dev page(s) before the production build.`);

ARG NEXT_PUBLIC_ENV
ENV NEXT_PUBLIC_ENV=$NEXT_PUBLIC_ENV
COPY nextjs/ .
# POC pages ship to lower environments only. pageExtensions alone does not exclude them (see post).
RUN if [ "$NEXT_PUBLIC_ENV" = "PROD" ]; then find src/pages -type f -name '*.dev.*' -print -delete; fi
RUN npm run build

// scripts/assert-no-poc-routes.mjs
import { readFile } from "node:fs/promises";

/** Route manifests written by `next build`: one per router. A project may have either or both. */
const MANIFESTS = [".next/server/pages-manifest.json", ".next/server/app-paths-manifest.json"];

const isPocRoute = (route) => route.includes("/poc/") || /\.dev(\/|$)/.test(route);

if (process.env.NEXT_PUBLIC_ENV !== "PROD") {
  console.log("[assert-no-poc-routes] Not a PROD build; POC routes are expected. Skipping.");
  process.exit(0);
}

const leaked = [];
for (const file of MANIFESTS) {
  try {
    const manifest = JSON.parse(await readFile(file, "utf8"));
    leaked.push(...Object.keys(manifest).filter(isPocRoute));
  } catch {
    // Manifest not present for this router type.
  }
}

if (leaked.length > 0) {
  console.error("[assert-no-poc-routes] POC routes found in a PROD build:", leaked);
  process.exit(1);
}
console.log("[assert-no-poc-routes] OK: no POC routes in the PROD build.");

// package.json (excerpt)
{
  "scripts": {
    "next:build": "node scripts/strip-dev-pages.mjs && next build && node scripts/assert-no-poc-routes.mjs"
  }
}

[assert-no-poc-routes] POC routes found in a PROD build: [ '/poc/demo.dev' ]

# non-PROD (dev.* extensions included)      # PROD
Route (app)                                 Route (app)
┌ ○ /                                       ┌ ○ /
├ ○ /_not-found                             └ ○ /_not-found
└ ○ /poc/demo

src/app/
|- layout.tsx
`- [site]/
   |- layout.tsx
   `- [locale]/
      |- [[...path]]/page.tsx          # Sitecore catch-all
      `- poc/
         |- layout.dev.tsx             # borrows header/footer ONCE for every POC page
         `- card-playground/
            `- page.dev.tsx            # -> /poc/card-playground (non-PROD only)

// src/app/[site]/[locale]/poc/layout.dev.tsx
import type { ReactNode } from "react";
import { notFound } from "next/navigation";
import { NextIntlClientProvider } from "next-intl";
import { setRequestLocale } from "next-intl/server";
import { AppPlaceholder } from "@sitecore-content-sdk/nextjs";
import client from "src/lib/sitecore-client";
import Providers from "src/Providers";
import SitecoreHead from "src/SitecoreHead";
import componentMap from ".sitecore/component-map";

type PocLayoutProps = {
  children: ReactNode;
  params: Promise<{ site: string; locale: string }>;
};

/** Borrows the home page's header and footer so every POC page looks like a real page on the site. */
export default async function PocLayout({ children, params }: PocLayoutProps) {
  const { site, locale } = await params;

  // Same as the catch-all: lets src/i18n/request.ts load this site's dictionary.
  setRequestLocale(`${site}_${locale}`);

  const page = await client.getPage([], { site, locale });
  const route = page?.layout.sitecore.route;
  if (!page || !route) notFound();

  return (
    <NextIntlClientProvider>
      <Providers page={page}>
        <SitecoreHead page={page} />
        <header>
          <div id="header">
            <AppPlaceholder page={page} componentMap={componentMap} name="headless-header" rendering={route} />
          </div>
        </header>
        <main>
          <div id="content">{children}</div>
        </main>
        <footer>
          <div id="footer">
            <AppPlaceholder page={page} componentMap={componentMap} name="headless-footer" rendering={route} />
          </div>
        </footer>
      </Providers>
    </NextIntlClientProvider>
  );
}

// src/app/[site]/[locale]/poc/card-playground/page.dev.tsx
import type { Metadata } from "next";
import CardPlayground from "src/poc/components/CardPlayground/CardPlayground";

export const metadata: Metadata = {
  title: "POC: Card playground",
  robots: { index: false, follow: false },
};

export default function CardPlaygroundPage() {
  return <CardPlayground />;
}