@alphasquad/saleor-template-advance 0.1.1 → 0.1.2

package/next.config.ts

@@ -1,6 +1,7 @@
 import type { NextConfig } from "next";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import fs from "node:fs";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -47,12 +48,49 @@ function getRemoteImageHosts(): string[] {
   );
 }
 
+// --- Tenant Override Resolution ---
+// When running via @alphasquad/create-saleor-storefront CLI wrapper,
+// process.cwd() is the tenant root. The tenant can place override components
+// in src/overrides/ which the template will use instead of its defaults.
+const tenantRoot = process.cwd();
+const tenantOverridesIndex = path.join(tenantRoot, "src", "overrides", "index.ts");
+const tenantOverridesDir = path.join(tenantRoot, "src", "overrides");
+const hasTenantOverrides =
+  fs.existsSync(tenantOverridesIndex) ||
+  fs.existsSync(tenantOverridesIndex.replace(".ts", ".tsx")) ||
+  fs.existsSync(tenantOverridesIndex.replace(".ts", ".js"));
+
 const nextConfig: NextConfig = {
   // Next.js skips tsconfig path resolution for files inside node_modules.
   // When this template is consumed as a package, we need explicit aliases.
   transpilePackages: ["@alphasquad/saleor-template-advance"],
   webpack(config) {
     config.resolve.alias["@"] = path.resolve(__dirname, "src");
+
+    // Map @tenant-overrides to tenant's src/overrides if it exists,
+    // otherwise use the template's empty defaults
+    config.resolve = config.resolve || {};
+    config.resolve.alias = config.resolve.alias || {};
+
+    if (hasTenantOverrides) {
+      (config.resolve.alias as Record<string, string>)["@tenant-overrides"] =
+        tenantOverridesDir;
+    } else {
+      // When no tenant overrides exist, use the template's empty defaults.
+      // In Next.js, next.config.ts is compiled and __dirname is available.
+      // However when installed as npm package, we need the template package root.
+      // The config file is always at the template root, so we use a simple heuristic:
+      // try the template root (where next.config.ts lives) first, then cwd.
+      const candidates = [
+        path.join(path.dirname(require.resolve("./package.json")), "src", "lib", "overrides", "defaults"),
+        path.join(process.cwd(), "src", "lib", "overrides", "defaults"),
+      ];
+      const defaultsPath = candidates.find((p) =>
+        fs.existsSync(p + ".ts") || fs.existsSync(p + ".js")
+      ) || candidates[0];
+      (config.resolve.alias as Record<string, string>)["@tenant-overrides"] = defaultsPath;
+    }
+
     return config;
   },
   eslint: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alphasquad/saleor-template-advance",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "scripts": {
     "dev": "next dev --turbopack",
     "build": "next build",

package/src/app/components/layout/footer.tsx

@@ -1,3 +1,4 @@
+import { storefrontOverrides } from "@tenant-overrides";
 import { fetchMenuBySlug } from "@/graphql/queries/getMenuBySlug";
 import Image from "next/image";
 import Link from "next/link";
@@ -26,6 +27,15 @@ type FooterSection = {
   children: FooterChild[];
 };
 
+/**
+ * Props passed to both the default and any tenant override footer.
+ * Server-fetched data is always provided, preserving SSR performance.
+ */
+export interface FooterRendererProps {
+  footerMenu: any;
+  siteInfo: any;
+}
+
 const SectionTitle = ({ children }: { children: React.ReactNode }) => (
   <span className="text-base font-secondary font-bold text-white uppercase tracking-wider">
     {children}
@@ -83,22 +93,17 @@ function normalizePhone(raw: string) {
   return digits ? `tel:${digits}` : null;
 }
 
-  const Footer = async () => {
-    const currentYear = new Date().getFullYear();
+const DefaultFooterRenderer = ({ footerMenu, siteInfo }: FooterRendererProps) => {
+  const currentYear = new Date().getFullYear();
 
   const TENANT_NAME = process.env.NEXT_PUBLIC_BRAND_NAME || process.env.NEXT_PUBLIC_TENANT_NAME || "Storefront";
   const logo =
     process.env.NEXT_PUBLIC_LOGO_URL ||
     "https://webshopmanager.com/files/images/logo.png";
 
-  // Fetch footer menu data from backend
-  const footerMenu = await fetchMenuBySlug("footer");
-
-  // Fetch site info for address and phone
-  const siteInfo = await fetchSiteInfo();
   const getInfo = (k: string) =>
     siteInfo?.metadata
-      ?.find((m) => m.key.toLowerCase() === k.toLowerCase())
+      ?.find((m: any) => m.key.toLowerCase() === k.toLowerCase())
       ?.value?.trim() || "";
 
   const address = getInfo("Address");
@@ -280,4 +285,23 @@ function normalizePhone(raw: string) {
   );
 };
 
+/**
+ * Server component that fetches footer data and delegates rendering
+ * to either the tenant's override or the default footer.
+ *
+ * Data fetching always happens server-side regardless of which renderer is used,
+ * preserving SSR performance and SEO.
+ */
+async function Footer() {
+  const [footerMenu, siteInfo] = await Promise.all([
+    fetchMenuBySlug("footer"),
+    fetchSiteInfo(),
+  ]);
+
+  const FooterRenderer =
+    (storefrontOverrides as any).Footer || DefaultFooterRenderer;
+
+  return <FooterRenderer footerMenu={footerMenu} siteInfo={siteInfo} />;
+}
+
 export default Footer;

package/src/app/components/layout/header/header.tsx

@@ -2,17 +2,23 @@ import { Suspense } from "react";
 import { NavBar } from "./navBar";
 import TopBar from "./topBar";
 import { fetchCategories, fetchMenuData } from "@/hooks/serverNavbarData";
+import type { CategoryNode, MenuItem } from "@/hooks/serverNavbarData";
+import { storefrontOverrides } from "@tenant-overrides";
 
-export const Header = async () => {
-  const [categories, menuItems] = await Promise.allSettled([
-    fetchCategories(),
-    fetchMenuData(),
-  ]);
-
-  const categoriesData =
-    categories.status === "fulfilled" ? categories.value : [];
-  const menuItemsData = menuItems.status === "fulfilled" ? menuItems.value : [];
+/**
+ * Props passed to both the default and any tenant override header.
+ * This ensures tenant headers receive server-fetched data without
+ * needing client-side fetches (preserving SSR performance).
+ */
+export interface HeaderRendererProps {
+  categories: CategoryNode[];
+  menuItems: MenuItem[];
+}
 
+const DefaultHeaderRenderer = ({
+  categories,
+  menuItems,
+}: HeaderRendererProps) => {
   return (
     <header className="w-full">
       <Suspense
@@ -23,7 +29,6 @@ export const Header = async () => {
           />
         }
       >
-        {/* Contact + Timings Banner */}
         <TopBar />
       </Suspense>
       <Suspense
@@ -37,8 +42,33 @@ export const Header = async () => {
           />
         }
       >
-        <NavBar categories={categoriesData} menuItems={menuItemsData} />
+        <NavBar categories={categories} menuItems={menuItems} />
       </Suspense>
     </header>
   );
 };
+
+/**
+ * Server component that fetches navigation data and delegates rendering
+ * to either the tenant's override or the default header.
+ *
+ * Data fetching always happens server-side regardless of which renderer is used,
+ * preserving SSR performance and SEO (no client-side fetch waterfalls).
+ */
+export const Header = async () => {
+  const [categories, menuItems] = await Promise.allSettled([
+    fetchCategories(),
+    fetchMenuData(),
+  ]);
+
+  const categoriesData =
+    categories.status === "fulfilled" ? categories.value : [];
+  const menuItemsData = menuItems.status === "fulfilled" ? menuItems.value : [];
+
+  const HeaderRenderer =
+    (storefrontOverrides as any).Header || DefaultHeaderRenderer;
+
+  return (
+    <HeaderRenderer categories={categoriesData} menuItems={menuItemsData} />
+  );
+};

package/src/app/components/showroom/showroomHeroCarousel.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import { storefrontOverrides } from "@tenant-overrides";
 import { GET_PAGE_METADATA_BY_SLUG } from "@/graphql/queries/getHeroMetadata";
 import { useQuery } from "@apollo/client";
 import Image from "next/image";
@@ -62,7 +63,7 @@ const SearchFormSection = () => {
   );
 };
 
-export const ShowroomHeroCarousel = ({}: ShowroomHeroCarouselProps) => {
+const DefaultShowroomHeroCarousel = ({}: ShowroomHeroCarouselProps) => {
   const { data, loading } = useQuery(GET_PAGE_METADATA_BY_SLUG, {
     variables: { slug: "hero-section" },
   });
@@ -139,3 +140,8 @@ export const ShowroomHeroCarousel = ({}: ShowroomHeroCarouselProps) => {
     </div>
   );
 };
+
+// Allow tenant repos to override the hero carousel via storefrontOverrides.ShowroomHeroCarousel
+export const ShowroomHeroCarousel =
+  (storefrontOverrides as any).ShowroomHeroCarousel ||
+  DefaultShowroomHeroCarousel;

package/src/app/components/showroom/testimonialsGrid.tsx

@@ -1,10 +1,11 @@
+import { storefrontOverrides } from "@tenant-overrides";
 import { GET_TESTIMONIAL_PAGE_TYPE } from "@/graphql/queries/getPageTypeId";
 import { GET_TESTIMONIALS } from "@/graphql/queries/getTestimonials";
 import createApolloServerClient from "@/graphql/server-client";
 import Heading from "../reuseableUI/heading";
 import { TestimonialCard } from "../reuseableUI/testimonialCard";
 
-export const TestimonialsGrid = async ({ first = 6 }: { first?: number }) => {
+const DefaultTestimonialsGrid = async ({ first = 6 }: { first?: number }) => {
   let items: Array<{
     id: string;
     name: string;
@@ -104,3 +105,7 @@ export const TestimonialsGrid = async ({ first = 6 }: { first?: number }) => {
     </section>
   );
 };
+
+// Allow tenant repos to override via storefrontOverrides.TestimonialsGrid
+export const TestimonialsGrid =
+  (storefrontOverrides as any).TestimonialsGrid || DefaultTestimonialsGrid;

package/src/app/page.tsx

@@ -9,6 +9,7 @@ import { getStoreName } from "./utils/branding";
 import { BrandsSwiperServer } from "./components/showroom/brandsSwiperServer";
 import NewslettersHomeModal from "./components/reuseableUI/newsletter/newslettersHomeModal";
 import { FeaturesStrip } from "./components/showroom/featureStrip";
+import { withOverride } from "@/lib/overrides/resolve";
 
 export const metadata: Metadata = {
   title: `Home - ${getStoreName()}`,
@@ -73,7 +74,7 @@ const FeaturedBrandsLoadingState = () => {
   );
 };
 
-export default function Home() {
+function DefaultHome() {
   return (
     <main className="overflow-x-hidden">
       <Suspense fallback={<SkeletonLoader type="hero" />}>
@@ -192,3 +193,7 @@ export default function Home() {
     </main>
   );
 }
+
+// Allow tenant repos to override the entire homepage via storefrontOverrides.HomePage
+const HomePage = withOverride("HomePage", DefaultHome);
+export default HomePage;

package/src/lib/overrides/README.md

@@ -0,0 +1,80 @@
+# Tenant Override System
+
+This template supports component overrides from tenant wrapper repos created by `@alphasquad/create-saleor-storefront`.
+
+## How It Works
+
+1. The CLI creates a tenant repo with `src/overrides/index.ts` that exports a `storefrontOverrides` registry
+2. `next.config.ts` maps `@tenant-overrides` to the tenant's `src/overrides/` directory (or empty defaults if none exist)
+3. Template components check the registry and use tenant overrides when available, falling back to template defaults
+
+## SSR & Performance Guarantees
+
+The override system is designed to preserve server-side rendering and performance:
+
+- **Header**: The template always fetches `categories` and `menuItems` server-side. Both the default and any tenant override receive these as props (`HeaderRendererProps`). Tenant headers do NOT need to fetch navigation data client-side.
+- **Footer**: The template always fetches `footerMenu` and `siteInfo` server-side. Both the default and any tenant override receive these as props (`FooterRendererProps`).
+- **ShowroomHeroCarousel**: Client component. Override replaces it 1:1.
+- **TestimonialsGrid**: Server component. Override replaces it 1:1.
+- **HomePage**: Full page replacement. The template's metadata export still applies.
+
+**Rule**: If the template component is a server component that fetches data, the override system passes that data as props. Tenant overrides should NOT re-fetch the same data client-side.
+
+## Supported Override Keys
+
+| Key | Props Received | Rendering |
+|-----|---------------|-----------|
+| `HomePage` | None (full page) | Server or Client |
+| `Header` | `{ categories, menuItems }` | Server-fetched, render only |
+| `Footer` | `{ footerMenu, siteInfo }` | Server-fetched, render only |
+| `ShowroomHeroCarousel` | None | Client component |
+| `TestimonialsGrid` | `{ first }` | Server component |
+
+## Tenant Override Example
+
+```ts
+// src/overrides/index.ts
+import MyHomePage from "./HomePage";
+import MyHeader from "./Header";
+
+export const storefrontOverrides = {
+  HomePage: MyHomePage,
+  Header: MyHeader,
+};
+```
+
+```tsx
+// src/overrides/Header.tsx
+// Receives server-fetched data as props - no client-side fetching needed
+export default function MyHeader({ categories, menuItems }) {
+  return (
+    <header>
+      <nav>
+        {menuItems.map(item => (
+          <a key={item.id} href={item.url}>{item.name}</a>
+        ))}
+      </nav>
+    </header>
+  );
+}
+```
+
+## Adding New Override Points
+
+To make a new component overridable while preserving SSR:
+
+1. Import: `import { storefrontOverrides } from "@tenant-overrides";`
+2. If the component fetches data server-side:
+   - Define a `RendererProps` interface with the fetched data
+   - Split into: async data-fetcher (stays as export) + renderer (overridable)
+   - The data-fetcher passes props to whichever renderer is active
+3. If the component is client-only:
+   - Rename: `const DefaultFoo = ...`
+   - Export with override: `export const Foo = (storefrontOverrides as any).Foo || DefaultFoo;`
+
+## Zero Impact When Unused
+
+When no tenant overrides exist (e.g., running the template directly):
+- `@tenant-overrides` resolves to `src/lib/overrides/defaults.ts` (empty object)
+- All override checks resolve to `DefaultXxx` immediately
+- No bundle size increase, no runtime overhead

package/src/lib/overrides/defaults.ts

@@ -0,0 +1,5 @@
+/**
+ * Default (empty) overrides registry.
+ * Used as fallback when no tenant overrides are found.
+ */
+export const storefrontOverrides: Record<string, never> = {};

package/src/lib/overrides/resolve.ts

@@ -0,0 +1,38 @@
+/**
+ * Override Resolution System
+ *
+ * Allows tenant wrapper repos (created by @alphasquad/create-saleor-storefront)
+ * to override specific template components by placing files in src/overrides/.
+ *
+ * Supported override keys (expand as needed):
+ *   - HomePage: Replaces the entire homepage content
+ *   - Header: Replaces the site header
+ *   - Footer: Replaces the site footer
+ *   - ShowroomHeroCarousel: Replaces the hero section
+ *   - FeaturesStrip: Replaces the features strip
+ *   - CategoryGrid: Replaces the category grid
+ *   - ProductGrid: Replaces the product grid
+ *   - TestimonialsGrid: Replaces the testimonials section
+ *   - AboutUs: Replaces the about us section
+ *   - BrandsSwiper: Replaces the brands swiper
+ */
+
+export { storefrontOverrides } from "@tenant-overrides";
+
+// Re-export a typed helper
+import { storefrontOverrides } from "@tenant-overrides";
+import type { ComponentType } from "react";
+
+/**
+ * Resolves an override component by key.
+ * Returns the tenant's override if available, otherwise the provided default.
+ */
+export function withOverride<P extends Record<string, unknown>>(
+  key: string,
+  DefaultComponent: ComponentType<P>
+): ComponentType<P> {
+  const Override = (storefrontOverrides as Record<string, ComponentType<any>>)[
+    key
+  ];
+  return Override || DefaultComponent;
+}

package/src/lib/overrides/tenant-overrides.d.ts

@@ -0,0 +1,4 @@
+declare module "@tenant-overrides" {
+  import type { ComponentType } from "react";
+  export const storefrontOverrides: Record<string, ComponentType<any>>;
+}