npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2022 – Pkg Stats / Ryan Hefner

@guardian/atoms-rendering

v23.6.0

Published

## Atoms

Downloads

12,997

Readme

Atoms Rendering

Atoms

Atoms Web Architecture

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 [email protected]: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.