@guardian/atoms-rendering

Atoms Rendering

Atoms

An Atom is a self contained piece of content that can be inserted into multiple articles. This repository implements atom definitions as part of a library which can be imported into the appropriate rendering service (dotcom-rendering or apps-rendering). Once imported, you can configure your rendering service to render the atom component for the atom data passed from your backend (frontend in the case of web).

Usage

import

To import an atom in your project use yarn add @guardian/atoms-rendering then

import { TheAtomYouWant } from '@guardian/atoms-rendering';

<TheAtomYouWant someProp={localData.someProp} />

Naming conventions

There is mostly a one to one correspondance between atoms as named by CAPI/frontend and their names in atoms-rendering, with the notable exception that the Media atom is named YoutubeAtom here.

Running locally

$ git clone https://github.com/guardian/atoms-rendering.git
or
$ git clone [e-mail]:guardian/atoms-rendering.git

Make sure that you have yarn installed, if not run

$ brew install yarn

Then,

$ yarn
$ yarn storybook

The available yarn commands are given below:

    "scripts": {
        "build": "microbundle --jsx React.createElement",
        "dev": "microbundle watch --jsx React.createElement",
        "storybook": "start-storybook -p 6006",
        "build-storybook": "build-storybook",
        "tsc": "tsc",
        "lint": "eslint . --ext .ts",
        "test": "jest --watch"
    }

dev-nginx setup

Some of the storybook stories need to fetch YouTube scripts that are only available to clients with an allow-listed domain. YouTube has allow-listed dev-gutools.co.uk (along with dotcom code and prod domains). In order for these stories to run as expected locally, you'll need to use dev-nginx to proxy atoms-rendering.local.dev-gutools.co.uk to localhost. This can be set up by

• Running yarn nginx:setup
• Running yarn storybook then opening https://atoms-rendering.local.dev-gutools.co.uk/ in your browser

Testing locally

If you want to test a change before publishing to NPM, you will need to point to this repository. For instance, you might want to check in dotcom-rendering on local that a change you make in this library is correct. For this do the following

• In atoms-rendering run yarn build,
• In atoms-rendering run yarn link, then
• In dotcom-rendering run yarn link "@guardian/atoms-rendering".

Then you will notice that your

dotcom-rendering/node_modules/@guardian/atoms-rendering

is a symlink to the atoms-rendering repository.

When you are done, you should

• In dotcom-rendering run yarn unlink "@guardian/atoms-rendering".
• In atoms-rendering run yarn unlink

And in dotcom-rendering you might also want to run

• yarn install --force, to get the regular package re-installed.

Adding a new atom

Adding a new atom in atoms-rendering involves

1. Adding the component, eg. MyComponent.tsx - Make sure the outer component of the atom contains data-atom-id and data-atom-type in order to be picked up by teleporter. Here is an example
2. Adding stories, eg. MyComponent.stories.tsx
3. Adding a line to index.ts to export the component
4. Publishing a new version of the library to Npm (see below)

An example PR for adding the Profile Atom can be found here. The component is defined in /src/ProfileAtom.tsx, with the supporting type ProfileAtomType in src/types.tsx. Types are transpiled when this project is built, and are made available to your rendering project when you include the published library as a dependency.

Releasing a new version / Publishing to NPM

atoms-rendering is now published to NPM using changesets

Generate a changeset describing your work by running yarn changeset and following the prompts.

Publishing is triggered by merging the auto-generated Bump Version PR that changesets manages.

Once complete, you can update the version of @guardian/atoms-rendering in any consuming project to see the changes.

Snyk Code Scanning

There's a Github action set up on the repository to scan for vulnerabilities. This is set to "continue on error" and so will show a green tick regardless. In order to check the vulnerabilities we can use the Github code scanning feature in the security tab and this will list all vulnerabilities for a given branch etc. You should use this if adding/removing/updating packages to see if there are any vulnerabilities.