guardian / Dotcom Rendering
Programming Languages
Labels
Projects that are alternatives of or similar to Dotcom Rendering
Dotcom Rendering
Frontend rendering framework for theguardian.com. It uses React, with Emotion for styling.
Quick start
This guide will help you get the dotcom-rendering
application running on your development machine.
Install Node.js
The only thing you need to make sure you have installed before you get going is Node.js.
We recommend using nvm (especially combined with this handy gist). It is great at managing multiple versions of Node.js on one machine.
Running instructions
$ git clone [email protected]:guardian/dotcom-rendering.git
$ cd dotcom-rendering
$ make dev
make 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.
Detailed Setup
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.
Technologies
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. | |
Cypress is an integration testing tool that runs tests in the browser. You will find the Cypress tests in the cypress folder. | |
Jest is a unit testing tool. You will find Jest tests in the repo with .test. filenames. |
|
The A/B Testing library is an internal NPM Module. There are a some docs here. |
Architecture Diagram
You can see a web only architecture diagram by running make arch-diagram
. It will give you an overview of the current server and browser web architecture.
Concepts
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
Feedback
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! 🙏
Where can I see Dotcom Rendering in Production?
Add ?dcr
to the URL of a Production (or CODE) article to see it rendered with Dotcom Rendering:
https://www.theguardian.com/info/developer-blog/2016/dec/14/mirrors-lights-sawdust-lasers?dcr
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 (modern)
in the footer after the copyright notice.
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.
Read about testing tools and testing strategy.
IDE setup
We recommend using VSCode.
Extensions
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.
Auto fix on save
We recommend you update your workspace settings to automatically fix formatting 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 type>Preferences: Open Settings (JSON)
-
Add the key value
"tslint.autoFixOnSave": true,
If you prefer not to use an editor like VSCode then you can use the following commands to manage formatting:
yarn prettier:check
// Checks for prettier issues
yarn prettier:fix
// Checks and fixes prettier issues
yarn lint
// Checks for linting issues
yarn lint --fix
// Checks and fixes linting issues
Thanks
Thanks to Chromatic for providing the visual testing platform that helps us catch unexpected changes on time