Longform README

Welcome to the headless-basics-data project! This repository provides a set of TypeScript modules, services, utilities, and interfaces designed for a headless CMS approach. The code aims to support a flexible, multi-site setup, offering features like content rendering, SEO handling, language-based routing, and more. Below is a comprehensive overview of the project and its underlying code.

Table of Contents

1. Overview
2. Architecture Run Through
3. Components Overview
4. Project Structure
5. Key Features
6. Installation
7. Building
8. Usage
9. Configuration & Environment Variables
10. Publishing the Package
11. Contributing
12. License

Overview

The headless-basics-data project provides a modular and extensible codebase for managing content in a headless CMS environment. It supports multi-site configurations, dynamic content fetching, and SEO metadata generation.

Architecture Run Through

The project is organized into several key areas:

• CMS Integration: Contains modules for interfacing with various CMS platforms such as Umbraco Heartcore, Kontent, and Contentful. This area includes tools for constructing GraphQL queries and processing responses from the CMS.
• Data Services: Responsible for fetching, processing, and aggregating data from the CMS. Services include page data collection, component data processing, and SEO data generation.
• Routing and URL Services: Implements logic for processing URLs and navigation. This involves stripping language prefixes, matching aliases, and transforming CMS URLs into friendly formats.
• UI Tools and Components: Provides utility functions and components for rendering navigation menus, themes, and dynamic content on the frontend.
• Utilities and Logging: A collection of helper functions for string manipulation, hashing, and logging to maintain consistency and aid in debugging.

Components Overview

Components in this project serve as modular building blocks representing discrete sections of a webpage. They are utilized to render dynamic content retrieved from the CMS:

• Dynamic Components: These components are imported dynamically based on the page layout and are responsible for rendering various content sections such as banners, grids, and content blocks.
• Component Services: Each component has associated services that handle data fetching, variable mapping, and query execution. This standardized construction ensures consistency across different pages.
• Theming and Styling: Components leverage Tailwind CSS for styling, and theme-specific modules may override default behaviors to provide a customized look and feel.
• Fallback Mechanisms: When a specific component cannot be loaded, fallback components are used to maintain page functionality and display an appropriate message.

Project Structure

The repository is organized as follows:

• src/

– cms/: Contains CMS-specific tools and constants.
– interfaces/: TypeScript interfaces defining the project's data models.
– multisite/: Tools for handling multi-site URL slugs.
– nextjs/app/: Modules for Next.js page-data handling.
– services/: Core business logic for data fetching, URL processing, SEO, and logging.
– ui-tools/: Utility modules for navigation and theming.
– utils/: General-purpose helpers for string manipulation, prefetching, and more.

• bitbucket-pipelines.yml.disabled: Example pipeline configuration.
• package.json: Project metadata, scripts, and dependencies.
• tsconfig.json: TypeScript configuration for building type definitions.
• tailwind.config.cjs and postcss.config.cjs: Configuration files for Tailwind CSS and PostCSS processing.

Key Features

1. Multi-Site Slug Management: Dynamic transformation of slugs based on language and site configuration.
2. CMS Data Fetching: Supports multiple CMS platforms with GraphQL integration.
3. Flexible Page Data & Layout: Aggregates data for both fixed and dynamic page layouts.
4. SEO & Navigation: Automated generation of SEO metadata and navigation structures.
5. Type-Safe Interfaces: Extensive TypeScript interfaces ensure code maintainability and scalability.

Installation

1. Install pnpm globally: npm install -g pnpm
2. Clone the repository: git clone
3. Navigate into the project directory and install dependencies: pnpm install

Building

To build the project and generate type declarations:

1. Clean the build directory: pnpm run clean
2. Build the project: pnpm run build
   The build artifacts will be located in the dist/ directory.

Usage

To integrate the package into your project:

1. Install the package: pnpm add @conversiondigital/headless-basics-data
2. Import required modules: import { buildPageData } from '@conversiondigital/headless-basics-data';
3. Configure your CMS and multi-site settings, then use the services to fetch data, build pages, and generate SEO metadata.

Configuration & Environment Variables

Configure the following environment variables as needed:

• UMBRACO_GRAPHQL_ENDPOINT: The GraphQL endpoint for Umbraco Heartcore.
• KONTENT_GRAPHQL_ENDPOINT, KONTENT_PROJECT_ID, KONTENT_PREVIEW_API_KEY: Settings for Kentico Kontent.
• CONTENTFUL_GRAPHQL_ENDPOINT, CONTENTFUL_SPACE_ID, CONTENTFUL_DELIVERY_API_KEY: Settings for Contentful.
• NEXT_PUBLIC_LOG_LEVEL: Controls log verbosity (e.g., trace, debug, info, warn, error).
• NEXT_PUBLIC_CMS_VARIANT: Determines which CMS variant to use (e.g., heartcore, contentful, or kontent).

Publishing the Package

When ready to publish the updated package:

1. Update the version in package.json: pnpm version patch
2. Build the project: pnpm run build
3. Publish from the dist/ directory: npm publish ./dist --no-git-checks

Contributing

1. Fork the repository and clone it locally.
2. Create a feature or fix branch from develop.
3. Commit your changes and open a Pull Request detailing your changes and testing steps.

Feel free to suggest improvements to the code structure, documentation, or usage examples.

License

This project is licensed under the ISC License. For details, please refer to the package.json file.