Skip to content

README.md

Latest commit

 

History

History
250 lines (158 loc) · 13 KB

README.md

File metadata and controls

250 lines (158 loc) · 13 KB
Raw

Dotcom Rendering

This repository contains the rendering logic for theguardian.com website and a subset of content on the Guardian iOS and Android apps.

It primarily uses TypeScript, Node.js, Express, React and Emotion.

Getting started

This guide will help you get the dotcom-rendering application running on your development machine.

Clone the repository

Start in your ~/code directory:

$ cd ~/code

Clone the repository from GitHub:

$ git clone git@github.com:guardian/dotcom-rendering.git

Change directory to the repository root:

$ cd dotcom-rendering

Install mise

To install the correct versions of tools required to run dotcom-rendering, we only support mise.

Follow the official documentation to install mise:
https://mise.jdx.dev/installing-mise.html#installing-mise

Add mise activation to your shell profile to run mise automatically when you change directories:
https://mise.jdx.dev/shell-setup.html#activate-mise-in-your-shell

The first time mise runs in a project it may, depending on the configuration, need to be trusted with:

$ mise trust

Optional but recommended, globally configure mise to auto update:

$ mise settings set self_update.auto true

Optional but recommended, globally configure mise to auto update given a minimum release age e.g.:

$ mise settings set self_update.minimum_release_age 48h

Important

If you have previously used fnm, nvm or asdf please disable any configuration that automatically sets tool versions on directory changes. This ensures any previous version management tool does not conflict with mise.

Install tools

Ensure you're at the root directory of the project:

$ cd ~/code/dotcom-rendering

If mise has been configured to activate on directory changes the correct tool versions should now be installed and confirmation output to the terminal.

Otherwise you can manually install the required tooling with:

$ mise install

On the first run of mise confirm the requested versions of each tool are installed with:

$ mise ls --current

Confirm the active Node version matches the version in .nvmrc

$ node -v

Confirm the active pnpm version matches the packageManager property in ../package.json

$ pnpm -v

Install dependencies

Change from the project root directory to the inner dotcom-rendering directory:

$ cd dotcom-rendering

Run

$ make install

If you get an Node version error then check your mise setup.

Run

$ make dev

The development server will start on http://localhost:3030

The development server home page lists examples of the various page and content types.

You can render a specific article by appending the production URL to the Article endpoint, for example:
http://localhost:3030/Article/https://www.theguardian.com/sport/2019/jul/28/tour-de-france-key-moments-egan-bernal-yellow-jersey

You can view the JSON data model of a page as sent by Frontend to DCR by appending .json?dcr=true to the production URL, for example:
https://www.theguardian.com/sport/2019/jul/28/tour-de-france-key-moments-egan-bernal-yellow-jersey.json?dcr=true

Detailed setup

If you're trying to integrate with other applications, we also have a more detailed setup guide.

VS Code

We recommend using VS Code.

Settings

Required VS Code settings are in the file .vscode/settings.json.required.

Recommended VS Code settings are in the file .vscode/settings.json.recommended.

Copy the required settings and any recommended settings you wish to use over to .vscode/settings.json to activate them.

The settings.json file is git ignored to prevent it from overriding any individual developer's settings.

TypeScript Version

Configure VS Code to use the workspace version of TypeScript and not its own bundled version using the following instructions:

https://code.visualstudio.com/docs/typescript/typescript-transpiling#_using-the-workspace-version-of-typescript

Auto fix on save

We recommend you update your workspace settings to automatically fix formatting and linting errors on save, this avoids code style validation failures. These instructions assume you have installed the esbenp.prettier-vscode extension:

  1. Open the Command Palette (shift + cmd + P) and select:

    Preferences: Open Workspace Settings (JSON)

  2. If it doesn't already exist add the following:

    "editor.codeActionsOnSave": {
	"source.fixAll.eslint": true
}

Extensions

VS Code should prompt you to install our recommended extensions when you open the project.

You can also find these extensions by searching for @recommended in the extensions pane.

Technologies

Technology Description
Typescript DCR is written in TypeScript
Preact DCR is rendered on the server with Preact and uses Preact as the Client-side framework. We use preact-compat to ensure compatibility with React.
Emotion CSS-in-JS Emotion is a css-in-js library. DCR uses the css tagged template literal style to enable the use of vanilla CSS properties.
Express We use Express as a thin server to handle requests from Frontend.
Webpack Webpack is used for its dev server and as a bundler for our production code.
SWC SWC is used as a Webpack loader that allows for very fast compilation.
Storybook We use Storybook to generate component variations that are then visual regression tested in Chromatic. You'll notice .stories. files in the repository that define the component variations.
Chromatic Chromatic is a visual regression testing tool that tests our Storybook components at PR time.
Jest Jest is a unit testing tool. You will find Jest tests in the repo with .test. filenames.
Playwright Playwright is an integration testing tool that runs tests in the browser. You will find the Playwright tests in the playwright directory.
AB Testing The A/B Testing framework is developed in-house. There are docs here.
Deno Deno is a JavaScript runtime that we've started incorporating into some of our Github Actions workflows. You will only need to install it if you are planning to run the workflow scripts locally. Some installation and troubleshooting instructions can be found in the Deno scripts folder.

Concepts

There are some concepts to learn, that will make working with Dotcom Rendering clearer:

Design system

Source is the Guardian's design system. For detailed and up-to-date information on how to use it, see the Source guide.

Code quality

You can ensure your code passes code quality tests by running:

$ make validate

This runs our linting tool, the TypeScript compiler and our tests, before finally building the bundles.

You can also run these tasks individually:

$ make lint
$ make stylelint
$ make tsc
$ make test

If you get lint errors, you can attempt to automatically fix them with:

$ make fix

See the makefile for the full list.

Testing

Testing tools and testing strategy

Debugging

DCR provides a visual debugging tool through a bookmarklet which you can find out more about in the debug tool docs.

Vulnerabilities

Dependabot

To monitor vulnerabilities from GitHub, you can use Dependabot alerts in the security tab.

Manual audit

To check for vulnerabilities in development, you can run:

$ make audit