@simpleview/cms-headless

cms-headless

npm install cms-headless

CMS-Headless is a core library for supporting React CMS headless clients. This library is required to run a CMS-Headless Client and provides core functionality and components.

It is built on top of React Material-UI and is it recommended that you pin to the same version that CMS-Headless is using.

Usage

• Add cms-headless to your package.json and pin to a specific version.
• cms-headless has a host of peerDependencies which are not bundled into the library in order to minimize the bundle size of those that are using the package. You will need to ensure all of the peerDependencies of the package are satisfied. See the package.json for the current peerDependencies.

All components are exported individually and should be imported via destructuring to ensure proper tree-shaking.

import { Section } from "@simpleview/cms-headless"

For faster import statements, import just the resource you want, exposed by package.json "exports" key.

import Section from "@simpleview/cms-headless/components/Section";

Installation

• Ensure you have sv-kubernetes installed.
• If you want your windows box to have TypeScript completions of npm packages.
  • Install Node via https://nodejs.org/en/download/, easiest method is the Windows Install 64-bit. It may ask you to restart your box.
  • In windows cmd

     cd d:\PATH\TO\sv-kubernetes\containers\cms-headless
     npm install
    

• Putty/Shell into sv-kubernetes
  • Install the container
    • sudo sv install cms-headless --type=container --branch=develop
  • Run the container

     cd /sv/containers/cms-headless
     sudo npm run docker
     yarn start
    

The service should now be accessible at http://kube.simpleview.io:6006/

Unit Testing

• Unit tests are not yet implemented. Comming Soon!

Repo Structure

When external parties consume this project the assumption is that all exported components are "top-level" meaning that you can destructure all necessary imports. This is necessary to ensure optimal and easy tree shaking.

import { Section, Unknown } from "@simpleview/cms-headless";

• /components/ - Each exported component have it's own sub-folder in this folder.
  • [Component] - e.g. DataView, DataViewFilterDate
    • index.ts
      • This file File which should re-export the primary component as default. So if in the folder /Section/ then index.ts should re-export /Section/Section.tsx.
      • This file should also export all entities in the [Component].types.ts file. This makes the type definitions usable throughout the project and by external consumers.
    • [Component].tsx - The primary component file.
    • [Component].type.ts - If the component needs to declare it's own typescript Interfaces or Types throughout the folder, declare them here.
    • [Additional].tsx - For private sub-components needed by this component which are not logical to be consumed outside of the project or within the project, simply place them in this folder and do not re-export them in the index.ts.
    • [Component].stories.tsx - Definition of the component playground used to test and demonstrate this components capabilities.
    • [Component].stories.mdx - The text documentation that describes this component and how to use it.
    • [Component].test.js - Jest file for testing this component.
• /theme/ - Definition of shared colors and theming that is used across the project. Exported globally as theme.
• /utils/ - Folder for non-react javascript utilities. Some of these are re-exported by the root index.ts, and some are private to the project.
• index.ts - The primary entrypoint for the project. It will re-export all entities from all public components.

Publishing

Publishing to NPM and storybook is automated. You do not need to run build, or publish.

• Whenever a push to master changes the package.json, @simpleview/cms-headless will be published to NPM via the publish github action which runs scripts/conditional-publish
• Whenever a push to master occurs the storybook is automatically built and pushed to the gh-pages branch via the storybook github action.

Running Locally

1. Install to sv-kubernetes as a container via sudo sv install cms-headless --type=container
2. Start local storybook by navigating to the container and running sudo npm run docker
3. When the docker image is built and started, you can run storybook with the command yarn start

Publishing a new Version

To publish a new version, be