Frontend rendering framework for theguardian.com. It uses React, with Emotion for styling.
This guide will help you get the dotcom-rendering application running on your development machine.
The only thing you need to make sure you have installed before you get going is Node.js.
We recommend using fnm to help manage multiple versions of Node.js on on machine.
Once Node is installed, make sure you're using the correct package manager by enabling corepack:
$ corepack enableNote
If you're using asdf, you'll need to run asdf reshim nodejs after running corepack enable.
$ git clone [email protected]:guardian/dotcom-rendering.git
$ cd dotcom-rendering
$ make devmake dev will start the development server on port 3030: http://localhost:3030.
Visit the root path of the dev server for some example URLs to visit.
You can render a specific article by specifying the production URL in the query string.
You can view the JSON representation of an article, as per the model sent to the renderer on the server, by going to
If you're new to TypeScript projects, if you're trying to integrate with other applications or if you prefer to take things slow, we also have a more detailed setup guide.
| Technology | Description |
|---|---|
 |
DCR is rendered on the server with Preact and uses Preact as the Client-side framework. We use preact-compat to ensure compatability with React modules. |
 |
Emotion is css-in-js library, DCR uses the css tagged template literal style to allow CSS copy-pasting. |
 |
DCR is written in Typescript. You can see the block element types as an example of our Typescript types. |
 |
We use Express as a very thin server to communicate with the Frontend endpoint. |
 |
We use storybook to generate component variations and 'layouts' that are then visual regression tested in Chromatic. You'll notice .stories. files in the repo for components that define the variations of components as defined by the component props. |
 |
Chromatic is a visual regression testing tool that reviews our Storybook components at PR time. |
 |
Jest is a unit testing tool. You will find Jest tests in the repo with .test. filenames. |
 |
Playwright is an integration testing tool that runs tests in the browser. You will find the Playwright tests in the playwright folder. |
 |
The A/B Testing library is an internal NPM Module. There are a some docs here. |
 |
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. |
Source is the Guardian's design system. For detailed and up-to-date information on how to use it, see the Source guide.
There are some concepts to learn, that will make working with Dotcom Rendering clearer:
- Design and Display Types use the Switch Pattern
- DecideLayout
- Prop Drilling (and why we don't use React Context)
- Dynamic imports
- Enhancers
- Data generated in Frontend
DCR provides a visual debugging tool through a bookmarklet which you can find out more about in the debug tool docs.
You can force DCR on or off explicitly with
?dcr=true or ?dcr=false.
One way to verify whether the article you're looking at is being rendered by DCR or not is to look for (dcr) in the footer after the copyright notice.
You can ensure your code passes code quality tests by running:
$ make validateThis 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 testIf you get lint errors, you can attempt to automatically fix them with:
$ make fixSee the makefile for the full list.
Read about testing tools and testing strategy.
To monitor vulnerabilities from GitHub, you can use Dependabot alerts in the security tab.
To check for vulnerabilities in development, you can run:
$ make auditWe recommend using VSCode.
VSCode 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.
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 VSCode plugin:
-
Open the Command Palette (
shift + cmd + P) and select:Preferences: Open Workspace Settings (JSON) -
Add the following:
"editor.codeActionsOnSave": { "source.fixAll.eslint": true }