React Helsinki Headless CMS

React UI component library to visualize Headless CMS data using Helsinki Design System.

Introduction
- The known clients that are using this library
Installation
Development
Testing
- Testing in IDE terminal
Usage
Releases, changelogs and deployments
Known issues
Contributing
Issues
License

Introduction

React Helsinki Headless CMS is a highly customized component library based on HDS. It is designed for City of Helsinki web applications using preconfigured WordPress Headless CMS environments. This library provides a set of unified visual components for Pages, Articles, and Article Archives.

It provides:

Unified designs for pages, layouts, and custom components across multiple applications.
Ability to pass app-specific configurations, such as translations and themes.
A set of components for visually presenting data from WordPress content modules and features.
A set of utilities, type and constants required for components implementation.
Support for required Apollo providers, such as linked events and venue search.

Note: This library does not inject the Helsinki Grotesk font for you; you must add it yourself.

Note: This library uses HDS design tokens through the SCSS interface so that mismatched design token versions do not lead to unexpected results.

The known clients that are using this library

The city of Helsinki Events: https://tapahtumat.hel.fi | https://github.com/City-of-Helsinki/events-helsinki-monorepo
The city of Helsinki Hobbies: https://harrastukset.hel.fi | https://github.com/City-of-Helsinki/events-helsinki-monorepo
The city of Helsinki Sports: https://liikunta.hel.fi | https://github.com/City-of-Helsinki/events-helsinki-monorepo
The city of Helsinki Kultus: https://kultus.fi | https://github.com/City-of-Helsinki/palvelutarjotin-ui
The city of Helsinki Culture Kids: https://kummilapset.hel.fi/ | https://github.com/City-of-Helsinki/kukkuu-ui

Installation

yarn add @city-of-helsinki/react-helsinki-headless-cms

Development

NOTE: The library is for general use and should not be developed for a single application environment only! Check the known clients

When to develop

The general requirements for new Component development:

The new Component must be connected to an instance of the WordPress Headless CMS.
The Wordpress Headless CMS environment has new Component compatible architecture, features and data structure (component library is heavily dependent on the GraphQL schemas).
The new Component is not presented in HDS or HDS cannot fully fulfill the specifications.
The new Component exists in HDS backlog, however, still it is not released by HDS team. In that case, HCRC new Component can be implemented and later must be replaced with HDS component when one is available.
New Component can be reused across multiple applications.

Available scripts

Name	Purpose	Useful Options
`yarn dev`	Starts storybook environment that can be used for developing components.
`yarn typecheck`	Runs the ts type check in the project components.
`yarn lint`	Lints the application to be according to quality standards (eslint) and formatting standards (prettier).	`--fix`: fix fixable problems
`yarn test`	Runs tests with jest.	`--watch`: enable watch mode
`yarn test-storybook`	Runs storybook accessibility tests jest.
`yarn build`	Builds application with rollup.
`yarn docker:dev`	Runs the application with docker with Development target environment.
`yarn docker:prod`	Runs the application with docker with Production target environment.
`yarn docker:down`	Shuts down the docker environment.
`yarn generate:graphql`	Generates / updates GraphQL schema for the project.

NOTE: To manually publish a new version to the NPM, you will need the credentials that can be found from the City of Helsinki Culture and Leisure's Vault-service.

Development environments

You can use docker local environment for development:

docker compose up --build when using Docker

podman compose up --build when using Podman

Alternatively, the local environment can be used:

yarn dev

Module structure

This library consists of three modules.

Core module that includes data naive components.
Apollo module that wraps core module components with logic that is able to fetch data with the help of an ApolloClient instance.
Nextjs module that provides utilities when working with Nextjs and Apollo.

Husky Git Hooks

This project uses Husky to manage Git hooks. Husky is configured to run specific scripts before committing changes to ensure code quality and consistency.

Pre-commit Hook

The pre-commit hook is configured to run the following commands:

yarn doctoc .
yarn lint-staged --relative

yarn doctoc .: This command updates the table of contents in your markdown files.
yarn lint-staged --relative: This command runs linting on staged files to ensure they meet the project's coding standards. The lint-staged configuration can be found from package.json.
- Using --relative flag to reduce command line length, as the combined length of all the absolute paths for a large commit can get quite long

NOTE: doctoc and husky does not work seamlessly together, since the doctoc does update the TOCs of the markdown files, but does not reject the pre-commit hook execution, and only leaves the refactored files as unstaged in Git.

Commit-msg Hook

The commit-msg hook is configured to run the following command:

npx --no-install commitlint --edit "$1"

npx --no-install commitlint --edit "$1": This command uses Commitlint to lint commit messages based on the project's commit message conventions. This repo follows the Conventional Commits.

CI

Checks

Tests pass
Lint pass
Build completes
Type check pass

CD

On additions to main, a canary version gets published to npm.

On a new release, a new version is released to npm.

Storybook

Storybook is a frontend workshop for building UI components and pages in isolation https://storybook.js.org/. The Storybook can be used to develop and to test the components, but also to document the components and their features.

The project is using the Storybook 10.

NOTE: Storybook version 10 may require the playwright-chromium installation.

The yarn dev command will start storybook in port 6006. When you make changes in src, they'll be automatically updated to storybook.

Apollo

This can handle data queries for you if you are using a supported library to fetch your data.

By importing data dependent components from @city-of-helsinki/react-helsinki-headless-cms/apollo, this library will request the data for you.

Note: An Apollo client linked to a graphql endpoint with a supported schema (headless CMS) must be provided in the apolloClient field of the config object.

Simplified example

import { Page } from '@city-of-helsinki/react-helsinki-headless-cms/apollo';
import { Navigation } from '@city-of-helsinki/react-helsinki-headless-cms/apollo';

<ConfigProvider
  config={{
    // ...
    apolloClient: client, // A client for the CMS
    eventsApolloClient: client, // A client to connect a events datasource (the LinkedEvents)
    venuesApolloClient: 'disabled', // A client to connect a venue datasource (the Servicemap / "TPREK")
    // ...
  }}
>
  <Page
    uri="/en/url"
    navigation={<Navigation menuName="Name of menu in headless CMS" />}
  />
</ConfigProvider>;

NextJS

We provide utilities for fetching headless data for NextJs in @city-of-helsinki/react-helsinki-headless-cms/nextjs. These can be used when generating static pages.

Build

This project uses rollup for its final bundle.

NOTE: Check the known issues!!

Use as a application dependency

NOTE: After any changes done to the React Helsinki Headless CMS -library, remember to build again!

Folder-based links

The easiest way to test the React Helsinki Headless CMS -library is to install it as a dependency of an application by using a local relative path:

The steps to use the local relative path as a dependency:

Build the React Helsinki Headless CMS -library with yarn build. You should now have a /dist -folder that contains the built library package.
Add the /dist-directory as a dependency. Remember to use the right relative local path:

{
  "dependencies": {
    "@city-of-helsinki/react-helsinki-headless-cms": "file:../react-helsinki-headless-cms/dist"
  }
}

Tarball-based links

When file: points to a .tgz file, Yarn will transparently let you require files from within the archive. For the node_modules linker, it means that the archive will be unpacked into the generated node_modules folder.

You can create a tarball by first building the package and then calling pack

yarn build
yarn pack

The steps to use the local tarball as a dependency:

{
  "dependencies": {
    "@city-of-helsinki/react-helsinki-headless-cms": "file:../react-helsinki-headless-cms-v2.1.0.tgz"
  }
}

Use portals (with monorepos and Yarn)

See more: https://yarnpkg.com/protocol/portal

The portal: protocol is similar to the link: protocol (it must be a relative path to a folder which will be made available without copies), but the target is assumed to be a package instead.

The portal: protocol is specifically designed for linking local directories (often containing extracted tarballs) into the dependency graph while maintaining correct resolution and deduplication logic.

Portals vs links: Links have to operate under the assumption that their target folder may not exist until the install is finished; this prevents them from reading the content of the folder, including any package.json files, and in turn preventing them from listing dependencies. Portals, on the other hand, must exist at resolution time or an error is thrown. This lets them read the content of the package.json file and be treated like any other package in the dependency tree - except that its content will be made directly available to the user, rather than copied like file: would do.

How to Use portal: for a Tarball

Extract the Tarball: The portal: protocol requires a folder. You must first extract your .tgz archive (e.g., city-of-helsinki-react-helsinki-headless-cms-v2.1.0.tgz) into a temporary staging folder (e.g., ./.hcrc-dev). The temporary staging folder should be in same directory as the consuming app's package.json file, since the portal: protocol is relative to the package.json file.
Update package.json: In the consuming app's package.json, reference the extracted folder using the portal: protocol:

⚠️ Security Tip: Don't forget to add /.hcrc-dev to your .gitignore so you don't accidentally commit the extracted library code to your repository.

"dependencies": {
  "@city-of-helsinki/react-helsinki-headless-cms": "portal:../../.hcrc-dev/package"
}

Clean and Install: If you have a conflicting dependency in the root package.json, delete it and run yarn install from the monorepo root.

Testing

With new features introduced in Storybook version 7, this library is configured with @storybook/addon-a11y Axe Accessibility Plugin.

The test could be run from the Storybook UI (Accessibility tab of the Story) or using the script.

Testing in IDE terminal

yarn test-storybook

After executing the script, you will get the Axe Accessibility testing report in the terminal window. The number of tests are dynamic per component and decided by Axe plugin logic.

Usage

App.tsx

// ...
import {
  Page,
  PageContent,
  ConfigProvider,
  defaultConfig,
} from "@city-of-helsinki/react-helsinki-headless-cms";

function App() {
  const page = ...;

  return (
    <ConfigProvider config={defaultConfig}>
      <Page
        navigation={
          <Navigation
            languages={...}
            menu={...}
            onTitleClick={() => ...}
            getUrlForLanguage={(language, currentLanguage) => new URL(...)
            }
          />
        }
        content={<PageContent page={page} breadcrumbs={[...]} />}
        footer={...}
      />
    </ConfigProvider>
  );
}

Releases, changelogs and deployments

The used environments are listed in Service environments.

The application uses automatic semantic versions and is released using Release Please.

Release Please is a GitHub Action that automates releases for you. It will create a GitHub release and a GitHub Pull Request with a changelog based on conventional commits.

Each time you merge a "normal" pull request, the release-please-action will create or update a "Release PR" with the changelog and the version bump related to the changes (they're named like release-please--branches--master--components--react-helsinki-headless-cms).

To create a new release for an app, this release PR is merged, which creates a new release with release notes and a new tag. This tag will be picked by Azure pipeline and trigger a new deployment to staging. From there, the release needs to be manually released to production.

When merging release PRs, make sure to use the "Rebase and merge" (or "Squash and merge") option, so that Github doesn't create a merge commit. All the commits must follow the conventional commits format. This is important, because the release-please-action does not work correctly with merge commits (there's an open issue you can track: Chronological commit sorting means that merged PRs can be ignored ).

See Release Please Implementation Design for more details.

And all docs are available here: release-please docs.

Conventional Commits

Use Conventional Commits to ensure that the changelogs are generated correctly.

Releasable units

Release please goes through commits and tries to find "releasable units" using commit messages as guidance - it will then add these units to their respective release PR's and figures out the version number from the types: fix for patch, feat for minor, feat! for major. None of the other types will be included in the changelog. So, you can use for example chore or refactor to do work that does not need to be included in the changelog and won't bump the version.

Configuration

The release-please workflow is located in the release-please.yml file.

The configuration for release-please is located in the release-please-config.json file. See all the options here: release-please docs.

The manifest file is located in the release-please-manifest.json file.

When adding a new app, add it to both the release-please-config.json and release-please-manifest.json file with the current version of the app. After this, release-please will keep track of versions with release-please-manifest.json.

Troubleshooting release-please

If you were expecting a new release PR to be created or old one to be updated, but nothing happened, there's probably one of the older release PR's in pending state or action didn't run.

Check if the release action ran for the last merge to main. If it didn't, run the action manually with a label.
Check if there's any open release PR. If there is, the work is now included on this one (this is the normal scenario).
If you do not see any open release PR related to the work, check if any of the closed PR's are labeled with autorelease: pending - ie. someone might have closed a release PR manually. Change the closed PR's label to autorelease: tagged. Then go and re-run the last merge workflow to trigger the release action - a new release PR should now appear.
Finally check the output of the release action. Sometimes the bot can't parse the commit message and there is a notification about this in the action log. If this happens, it won't include the work in the commit either. You can fix this by changing the commit message to follow the Conventional Commits format and rerun the action.

Important! If you have closed a release PR manually, you need to change the label of closed release PR to autorelease: tagged. Otherwise, the release action will not create a new release PR.

Important! Extra label will force release-please to re-generate PR's. This is done when action is run manually with prlabel -option

Sometimes there might be a merge conflict in release PR - this should resolve itself on the next push to main. It is possible run release-please action manually with label, it should recreate the PR's. You can also resolve it manually, by updating the release-please-manifest.json file.

Fix merge conflicts by running release-please -action manually

Open release-please github action
Click Run workflow
Check Branch is master
Leave label field empty. New label is not needed to fix merge issues
Click Run workflow -button

There's also a CLI for debugging and manually running releases available for release-please: release-please-cli

Deployments

When a Release-Please pull request is merged and a version tag is created (or a proper tag name for a commit is manually created), this tag will be picked by Azure pipeline, which then triggers a new deployment to staging. From there, the deployment needs to be manually approved to allow it to proceed to the production environment.

The tag name is defined in the azure-pipelines-release.yml.

Publishing new versions manually without release-please

For canary release the naming convention is x.y.z-canary-[gitcommithash]. Running yarn publish should ask for version number too, but a version property in package.json sets the version number.

Build package with yarn build
Publish package yarn publish

Note: A local tarball of built package can be created with yarn pack. Just remember to build first.

Note: There is an a known issue with publishing using Windows environment. If you have a Windows machine use Docker container to publish the package.An Apollo client linked to a graphql endpoint with a supported schema (headless CMS) must be provided in the apolloClient field of the config object.

Known issues

Jest has difficulties loading this library. When this library is required in a test file, it's possible that some imports are cjs and some are esm. These two variants do not share a react context which can result in useConfig calls that return an empty config object even though <ConfigProvider> is declared correctly. I.e. <ConfigProvider> sets values for context1 and useConfig reads context2.
Some of the built packages created with yarn build does some issues with some types. This leads to a situation where the application that uses the library cannot read all the exported types. Especially the exported enums inside a built package might be handled incorrectly (rollup/rollup#4291), but there are other type related issues also, but not on every built package.

Contributing

Read the contributing guide to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes.

Issues

If you notice a bug or want to request a feature, please submit an issue to our GitHub repository.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 462 Commits
.github		.github
.husky		.husky
.storybook		.storybook
.vscode		.vscode
public		public
src		src
static/images		static/images
storybook-server		storybook-server
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.npmignore		.npmignore
.prettierrc.js		.prettierrc.js
.release-please-manifest.json		.release-please-manifest.json
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
babel.config.js		babel.config.js
codegen.yml		codegen.yml
commitlint.config.mjs		commitlint.config.mjs
docker-compose.yml		docker-compose.yml
eslint.config.mjs		eslint.config.mjs
jest-setup.ts		jest-setup.ts
jest.config.js		jest.config.js
package.json		package.json
release-please-config.json		release-please-config.json
rollup.config.js		rollup.config.js
sonar-project.properties		sonar-project.properties
tsconfig.json		tsconfig.json
yarn.lock		yarn.lock

Folders and files

Latest commit

History

Repository files navigation

React Helsinki Headless CMS

Introduction

The known clients that are using this library

Installation

Development

When to develop

Available scripts

Development environments

Module structure

Husky Git Hooks

Pre-commit Hook

Commit-msg Hook

CI

CD

Storybook

Apollo

NextJS

Build

Use as a application dependency

Folder-based links

Tarball-based links

Use portals (with monorepos and Yarn)

Testing

Testing in IDE terminal

Usage

Releases, changelogs and deployments

Conventional Commits

Releasable units

Configuration

Troubleshooting release-please

Fix merge conflicts by running release-please -action manually

Deployments

Publishing new versions manually without release-please

Known issues

Contributing

Issues

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 6

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages