Version: next

Content Composition

Since version 3.11

References

For more detailed information, check out:

Introduction

Content Composition is a powerful feature that allows you to create reusable building blocks for your content. It helps you:

Build modular and maintainable content structures
Implement type-safe GraphQL fragments
Create flexible page layouts using composable components

This guide will walk you through implementing content composition in your Front-Commerce application.

Prerequisites

Before starting, make sure you:

Have a Front-Commerce application set up
Understand how to register an extension
Understand file-based routing in Remix
Know how to load data from the GraphQL schema
Are familiar with GraphQL fragments
Understand React components basics

Tutorial

Define Your Content Types

First, let's define the GraphQL types for our content. Here's an example that defines various content types like Carousel and ProductsList:

./tutorial-extension/modules/core/index.ts
import { createGraphQLModule } from "@front-commerce/core/graphql";

export default createGraphQLModule({
  namespace: "Tutorial/Core",
  typeDefs: /* GraphQL */ `
    extend type Query {
      homePage: HomePage
    }

    type HomePage{
      sharedContent: [SharedContent]
    }

    union SharedContent = Carousel | ProductsList

    type Carousel {
      slides: [CarouselSlide]
    }

    type CarouselSlide {
      title: String
      image: String
      cta: CallToAction
    }

    type ProductsList {
      title: String
      category: Category
    }
  `,
});

Register Content Compositions

Next, register your content compositions using the composition.register method in your extension:

./tutorial-extension/index.ts
import { createContentComposition } from "@front-commerce/core";

// The composed fragment will be named `SharedContentFragment`
const SharedContentComposition = createContentComposition("SharedContent", [
  {
    name: "Carousel", // The fragment name needs to match this name, eg. `CarouselFragment`
    client: {
      component: new URL("./components/Carousel.tsx", import.meta.url),
      fragment: /* GraphQL */ `
        fragment CarouselFragment on Carousel {
          slides {
            title
            image
            cta {
              url
              text
            }
          }
        }
      `,
    },
  },
  {
    name: "ProductsList", // The fragment name needs to match this name, eg. `ProductsListFragment`
    client: {
      component: new URL("./components/ProductsList.tsx", import.meta.url),
      fragment: /* GraphQL */ `
          fragment ProductsListFragment on ProductsList {
            title
            category {
              id
              name
            }
          }
        `,
    },
  },
]);

export default defineExtension({
  unstable_lifecycleHooks: {
    onContentCompositionInit: (composition) => {
      composition.registerComposition(SharedContentComposition);
    },
  },
});

Use the Generated Fragments

The registration process automatically generates a composed fragment that includes all individual fragments:

fragment SharedContentFragment on SharedContent {
  ...CarouselFragment
  ...ProductsListFragment
}

fragment CarouselFragment on Carousel {
  ...
}

fragment ProductsListFragment on ProductsList {
  ...
}

You can now use this fragment in your page queries:

./tutorial-extension/theme/pages/HomePage/HomePageQuery.gql
query HomePage {
  homepage {
    sharedContent {
      ...SharedContentFragment
    }
  }
}

Implement the Page Component

Finally, create your page component that uses the composition:

./example-extension/application-extension/routes/_main.index.ts
import { HomePageDocument } from "~/graphql/graphql";
import { FrontCommerceApp } from "@front-commerce/remix";
import { json } from "@front-commerce/remix/node";
import { useLoaderData } from "@front-commerce/remix/react";
import { CompositionComponent } from "@front-commerce/core/react";
import { LoaderFunctionArgs } from "@remix-run/node";

// 1. Fetch the data for your page
export const loader = async ({ request, context }: LoaderFunctionArgs) => {
  const app = new FrontCommerceApp(context);
  const data = await app.graphql.query(HomePageDocument);
  return json({ homepage: data.homepage });
};

// 2. Render the content composition
export default function HomePage() {
  const { homepage } = useLoaderData<typeof loader>();
  return (
    <CompositionComponent
      name="SharedContent"
      content={homepage.sharedContent}
      // optional custom rendering that wraps the array of react nodes
      renderComponents={(components) => <Stack size="8">{components}</Stack>}
      // optional custom rendering that wraps a single react node
      renderComponent={(component) => {
        if (component.props.__typename !== "Carousel") {
          return <div className="container">{component}</div>;
        }
        return component;
      }}
    />
  );
}

tip

You can also use the useCompositionComponentMap hook to get the individual composition components and build your own rendering logic:

const SharedContent = useCompositionComponentMap("SharedContent");

// <SharedContent.Carousel />
// <SharedContent.ProductsList />

Advanced Usage

Overriding Existing Compositions

You can override existing compositions by registering a new composition with the same name:

composition.register("Wysiwyg", [
  {
    name: "DefaultWysiwyg",
    client: {
      component: new URL("./components/DefaultWysiwyg.tsx", import.meta.url),
      fragment: /* GraphQL */ `
        fragment DefaultWysiwygFragment on DefaultWysiwyg {
          childNodes
          data {
            dataId
          }
          customField  // Add new fields
        }
      `,
    },
  },
]);

tip

When overriding compositions, the last registered extension takes precedence, but all compositions are merged together.

References​

Introduction​

Prerequisites​

Tutorial​

Advanced Usage​

Overriding Existing Compositions​