signpost-base

A collection of sharable components for Signpost sites.

This README.md is meant for developers and maintainers.

Usage

This is the source code repository for @ircsignpost/signpost-base Node package.

The package exports two kinds of artifacts:

• Transpiled TypeScript modules that live in the dist directory.
• CSS and Less stylesheets that live in styles. If you want to use React component defined by this package, you need to include its corresponding stylesheet in pages/_app.js.

The components in this package are meant to be used on Signpost sites only and assume that those sites are built with the following technologies:

• Next.js
• React
• Ant Design
• Tailwind

Development environment setup

This section explains how to set up your development environment.

1. Install Node.js dependencies

   yarn install

2. Install Git hooks

   yarn prepare

Developing a new feature

This section gives tips on developing a new sharable feature. This package is not directly connected to an end-user site, so it requires a few more steps to set up a development loop.

Building your changes in signpost-base

Building your changes:

yarn run build

It will create a /dist directory with updated components from /src.

Connecting this package to a local site

To test a component from the version of this package that's on your drive, add it to a site's dependencies:

# e.g., cd /Users/greg/beporsed-ma-ra
cd PATH_TO_A_SITE_REPO
# e.g., yarn add /Users/greg/signpost-base
yarn add PATH_TO_THIS_PACKAGE/signpost-base

It will update @ircsignpost/signpost-base dependency in package.json file to something like: "@ircsignpost/signpost-base": "/Users/greg/signpost-base",

Now the site will use the package from your local drive and not from NPM. To use a new component, just import it. See example at beporsed-ma-ra.

If you want to use hot-reload, change next config to refresh based on node_modules.

Modifying and importing styles

When you add a new file to /styles, it needs to be explicitly imported in your local site, e.g., see example of importing a .less file.

Deployment

Before deploying your changes, create a PR with your changes on a separate branch, get it reviewed and approved, then merged into the main branch.

Release and publish a new version

Release is the process of marking the source code repository with a new version. This package uses release-please to automate the release process.

Deployment (AKA publishing) is the process of pushing the newest package release to NPM, so that it is accessible to its clients. This package is hosted at NPM, @ircsignpost/signpost-base.

Releasing and publishing are two required steps for making a new version available to its clients. First release, then publish:

1. Create a new release:

   1. Merge your changes into main branch, wait for several minutes for release-please to create a release PR. See example of an automatically created release PR.

   2. Merge the release PR on GitHub as described in the action's documentation.

2. Publish on NPM. To deploy a new version to the registry, do the following on main branch:

   1. Build the new version of the package.

      yarn run build

   2. Publish the new package. When prompted to enter a version, enter the one created in the release step. Usually, that means to retype the version shown in the prompt

      yarn publish

      You might get code ENEEDAUTH error on yarn publish but the package still gets published.

NOTE

• Use ! to indicate the change (commit) is breaking: https://github.com/google-github-actions/release-please-action#how-should-i-write-my-commits
• As a rule of thumb, do release and pulish cycle after each merge into the main branch to keep the changeset small
• You can create releases without publishing
• To unpublish a version of the package, you can use the npm unpublish <package-name>@<version> command. For example, to unpublish version 3.7.0 of this project, you would run npm unpublish @ircsignpost/[email protected] in your terminal.

Package's design

This section documents some of the package's design decisions.

Architecture

Signpost Website Infrastructure Design Doc describes the overall architecture of the Signpost ecosystem including this package, signpost-template, and individual Signpost instances.

Styles

The components in this package use either Vanilla CSS or static Less stylesheets.

We do not use CSS modules, because Next.js doesn't allow dependencies to use CSS modules.

We allow for Less, because Signpost website use Ant, which uses Less.

Website's design

This section documents some of the website's design decisions and mechanisms.

Preview

To understand how to use the preview mode on Signpost instances, read "Preview mode in unitedforukraine.org".

Article post-processing

Articles are hosted as plain HTML files on Zendesk. To enable content writers to add modern and consistent elements, the article content component post-processes the HTML content from Zendesk.

Article writers may use custom content elements to add meta tags or link buttons.