ghengeveld / dotcom-rendering

The (new) Guardian Dot Com

Dotcom Rendering

Frontend rendering framework for theguardian.com. It uses React, with Emotion for styling.

• Chat
• Quick start
  • Install Node.js
  • Running instructions
  • Detailed Setup
  • Architecture Diagram
  • Feedback
• Code Quality
• IDE setup
  • Extensions
  • Auto fix on save
• Thanks

Chat

Check out the Digital/dotcom-rendering channel on Chat. If you haven't already done so already, please ask the Dotcom Platform team for an invite.

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 [e-mail]: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.

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.

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! 🙏

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.

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:

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

   >Preferences: Open Settings (JSON)
   

2. Add the key value "tslint.autoFixOnSave": true,

Thanks

Thanks to Chromatic for providing the visual testing platform that helps us catch unexpected changes on time.