npm package: @simpleview/cms-headless
Description: CMS Headless Library
Author: Quinton Price
Latest version: 1.0.23

# cms-headless

```
npm install cms-headless
```

CMS-Headless is a core library for supporting [React](https://reactjs.org/) 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](https://mui.com/) 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](package.json) for the current `peerDependencies`.

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

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

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

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

# Installation

* Ensure you have [sv-kubernetes](https://github.com/simpleviewinc/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.

```js
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`
1. Start local storybook by navigating to the container and running `sudo npm run docker`
1. 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