Component library
To build pages and layouts using a static site generator (SSG), content and content models need to be mapped to corresponding components in the front-end codebase.
These components should be created to be presentational components (also known as stateless components) and are primarily responsible for rendering UI elements based on the data received as props. In our case, the props for each component correspond to specific pieces of content that come from our CMS.
Presentational components are useful because they promote separation of concerns and make your component more reusable. This is really critical in the context of a headless CMS implementation because these components will need to be reused on various pages with different data.
For the most part, headless CMS implementations don't require very specific updates to be made to your components. This is always good practice because you want your component library to be context-agnostic so there is clear separation of concern. We have found from experience that there are some considerations to be made to avoid bugs and issues. These changes don’t and shouldn’t impact the usability of your components in other systems.
CMS modules vs. atomic components
In a headless CMS architecture, we like to separate components into two categories: CMS modules and atomic components.
CMS modules are components that are connected, one-to-one, to a content model in the CMS and used as the building blocks to define the layout of a page (e.g., main hero).
Atomic components are the reusable components used internally in our code base. They are usually building blocks of CMS modules or parts of a page template defined in code (e.g., button, image, pagination).
We usually like grouping them in different folders so it is clear to the developers which components are connected to the CMS (and may require us to test our integration with the CMS) and which are only used internally in our codebase.
Null checks
We often don’t really think about null checking anymore when we leverage Typescript in our component library. That’s because Typescript will automatically ensure that developers are passing in the correct props to your component. It serves as a substitute for explicit null checks. Unfortunately, Typescript won’t work for data that’s passed from a CMS, nor will your content authors get the error message. This is why we talk about the importance of providing the correct field validation in the previous section. Even if you plan to provide field validation, changes to the content model or human error could easily cause your components to break ungracefully. Think of adding null checks in your components as a fallback plan. This could be as easy as adding defaults to props or conditionally checking for props before rendering.
Spacing
When building a component library, developers should build spacing into components to ensure consistency and flexibility in layout design. This can help to ensure consistency in layout design and reduce development time by allowing developers to quickly and easily assemble new modules from existing components. Building consistent spacing values into each component makes components reusable across multiple CMS modules.
In addition, building spacing into components can make it easier for developers to work with the component library, as they will not need to manually adjust spacing values for each instance of a component. This can help speed up development time and reduce the risk of errors or inconsistencies in the layout design.
Using Storybook when building and testing components
Storybook allows developers to visualize and test components in isolation. It provides a way to test and debug components without the distraction of the larger application or CMS environment, making it easier to identify and fix issues early on. It also helps developers see what they're building as they're building it and visualize changes to page margins, spacing, font sizes, colour, etc., without having to rebuild the website, saving time in the development process.
With Storybook, teams can test out and showcase different variants of each component, ensuring that they are working as intended and that they are flexible enough to be used in different contexts.
Storybook also integrates with Chromatic for visual regression testing. This means that you can test each component for visual changes, ensuring that they look and behave as intended across different devices, browsers, and screen sizes, as well as catch accessibility issues.
Stackbit's Storybook plug-in
The Stackbit Storybook plug-in allows you to autogenerate content model schema from your components in Storybook. The generated content models may be missing some fields but is useful for scaffolding content models in a new project based on your existing stories.
Documentation
Ideally, you should have a clear visual representation of your components, content types, and their relationships that is intended for both technical and non-technical stakeholders. You should also have more technical documentation detailing what the components, content types, and attributes are.
As you build the schemas in the CMS, keep your documentation up to date and maintain version control as you iterate. This way, documentation becomes a strategic asset that your teams can reliable refer to.
We prefer to use Storybook to catalogue component libraries. Every time the codebase is changed, components are built and visualized in Storybook with the updated code, and regression tests are run automatically in Chromatic. Since it's separate from the CMS platform, content authors can see all available components without needing access to the CMS.
Whether you use Storybook or Figma or create a separate documentation site, you'll need a central place to document and showcase how each component works and how it should be used.
Last updated