npm package: @ircsignpost/signpost-base
Description: Base components for Signpost websites.
Author: IRC Signpost
Latest version: 16.45.0

# 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][npmjs] 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

   ```sh
   yarn install
   ```

2. Install Git hooks

   ```sh
   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:

```shell
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:

```shell
# 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](https://github.com/unitedforukraine/beporsed-ma-ra/blob/main/pages/locale-select.tsx#L10).

If you want to use hot-reload, [change next config to refresh based on
node_modules](https://github.com/vercel/next.js/discussions/33929#discussioncomment-2710035).

### 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](https://github.com/unitedforukraine/beporsed-ma-ra/blob/main/pages/_app.tsx#L3).

## 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][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][npmjs].

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](https://github.com/unitedforukraine/signpost-base/commit/16aac71a5a13e9dde03f53cdfacecde4e791b3bd) of an automatically created release PR.

   2. Merge the release PR on GitHub as described in [the action's documentation](https://github.com/google-github-actions/release-please-action#whats-a-release-pr).

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](https://docs.npmjs.com/unpublishing-packages-from-the-registry#unpublishing-a-single-version-of-a-package). For example, to unpublish version 3.7.0 of this project, you would run `npm unpublish @ircsignpost/signpost-base@3.7.0` in your terminal.

## Package's design

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

### Architecture

[Signpost Website Infrastructure Design
Doc](https://docs.google.com/document/d/1rv-o78QyVWzjivNlNyWC2wZOGBDLLVF7Q_ayaxmSRW8/edit?resourcekey=0-ALEDs8E3tCKcn6DpIs7rcQ)
describes the overall architecture of the Signpost ecosystem including this
package,
[signpost-template](https://github.com/unitedforukraine/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](https://github.com/vercel/next.js/issues/13282).

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

[release-please]: https://github.com/googleapis/release-please
[npmjs]: https://www.npmjs.com/package/@ircsignpost/signpost-base

## 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"](https://docs.google.com/document/d/1IbtY_EvIm0c1C8yeKpEPWwPvWJyHiNehYkRpVJJ65kg/edit#).

### 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](https://docs.google.com/document/d/1RyKzdU5ytXyswHtMoefjpvC7DtEMcJ1ZwJtMRsP5r4E/edit)
to add meta tags or link buttons.