A collection of sharable components for Signpost sites.
This README.md is meant for developers and maintainers.
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 inpages/_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
This section explains how to set up your development environment.
-
Install Node.js dependencies
yarn install
-
Install Git hooks
yarn prepare
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:
yarn run build
It will create a /dist
directory with updated components from /src
.
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.
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.
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 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:
-
Create a new release:
-
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. -
Merge the release PR on GitHub as described in the action's documentation.
-
-
Publish on NPM. To deploy a new version to the registry, do the following on
main
branch:-
Build the new version of the package.
yarn run build
-
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 onyarn 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 runnpm unpublish @ircsignpost/signpost-base@3.7.0
in your terminal.
This section documents some of the package's design decisions.
Signpost Website Infrastructure Design Doc describes the overall architecture of the Signpost ecosystem including this package, signpost-template, and individual Signpost instances.
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.
This section documents some of the website's design decisions and mechanisms.
To understand how to use the preview mode on Signpost instances, read "Preview mode in unitedforukraine.org".
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.