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 a tool to help manage multiple versions of Node.js on on machine. fnm is popular in the department at the moment, although nvm and asdf are also used.
If you are not sure which tool you have in use, the command which node can give you a clue.
If you use nvm, you might find this gist helpful.
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 git@github.com:guardian/dotcom-rendering.git
$ cd dotcom-rendering
$ make devmake dev will start the development server on port 3030: http://localhost:3030.
make build && make start will start the production server on port 9000: http://localhost:9000.
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
| Name | Description |
|---|---|
HOSTNAME |
Defaults to localhost. If running behind a reverse proxy (Github Codespaces / Ngrok) this needs to be set to the hostname used to access DCR |
NODE_ENV |
production or development. Toggles features such as hot reloading, compression, localhost access, etc |
GU_STAGE |
PROD or DEV. Typically used to decide if DCR should call Production downstream API's or CODE downstream API's |
GU_PUBLIC |
Any value, undefined will disable. Toggles serving assets on the /assets/ endpoint |
DISABLE_LOGGING_AND_METRICS |
Boolean. Toggle for enabling Log4js |
Most of these variables are set by our make scripts and you don't need to worry about setting them.
If you're new to JavaScript 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.
For a high-level overview of some of the key ideas behind the design of the Dotcom website, see design.theguardian.com. This resource was made in 2018 and is not maintained so it should not be taken as authoritative on details, but most of it still applies and it gives a very quick and visual overview. It also provides an explanation of some journalism- or Guardian-specific terms that you might see in the codebase, like 'kicker' and 'standfirst'.
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
- EnhanceCAPI
- 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.
After completing this setup guide, we would greatly appreciate it if you could complete our dotcom-rendering setup questionnaire. It should only take 3 minutes and will help us improve this documentation and the setup process in the future. Thank you! 🙏
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 pnpm audit.
We 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.
Staged changes are automatically prettified on commit. You can disable this by adding --no-verify to your commit command.
To run the prettier check manually, run either of the following commands from the workspace root:
pnpm prettier:check→ Checks for prettier issuespnpm prettier:write→ Checks and fixes prettier issues
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 }
If you prefer not to use an editor like VSCode then you can use the following commands to manage formatting and (try to fix) linting errors:
make fix→ Checks and fixes prettier and linting issues
Thanks to Chromatic for providing the visual testing platform that helps us catch unexpected changes on time