Skip to content

Commit c410811

Browse files
arelraarelra
committed
Expand VS Code setup. Fnm setup. Reorder sections. Add links
1 parent ab65013 commit c410811

File tree

2 files changed

+89
-63
lines changed

2 files changed

+89
-63
lines changed

‎README.md

Lines changed: 2 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,11 @@
1-
# Dotcom & Apps Rendering
1+
# Dotcom Rendering & Apps Rendering
22

3-
This repository contains the rendering code for theguardian.com.
3+
This repository contains the rendering logic for theguardian.com.
44

55
It is a monorepo with 2 projects, `apps-rendering` and `dotcom-rendering`.
66

7-
## Install
8-
9-
Run `pnpm install` in the root directory of this project to install all packages.
10-
117
## Run
128

13-
You should always `cd` into the correct subdirectory before running commands
14-
159
### `apps rendering`
1610

1711
Go to [apps rendering](apps-rendering/README.md) for more details.

‎dotcom-rendering/README.md

Lines changed: 87 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -28,19 +28,45 @@ $ cd dotcom-rendering
2828

2929
### Install Node.js
3030

31-
To install and manage Node versions we recommend using a Node version manager such as [fnm](https://github.com/Schniz/fnm), [nvm](https://github.com/nvm-sh/nvm) or [asdf](https://asdf-vm.com/guide/getting-started.html).
31+
To install and manage Node versions, we highly recommend installing a Node version manager such as [fnm](https://github.com/Schniz/fnm) (preferred), [nvm](https://github.com/nvm-sh/nvm) or [asdf](https://asdf-vm.com/guide/getting-started.html).
3232

33-
To install Node, follow the instructions for the version manager of your choice.
33+
Ensure you're at the root directory of this project, then follow the instructions for your version manager to install Node.
3434

35-
Our preferred Node version manager is [fnm](https://github.com/Schniz/fnm).
35+
For `fnm` this will be:
3636

37-
Once installed, check the running Node version, ignoring any 'v' prefix, matches the version in [.nvmrc](../.nvmrc)
37+
```
38+
$ fnm use
39+
```
40+
41+
For `nvm` this will be:
42+
43+
```
44+
$ nvm use
45+
```
46+
47+
Once installed, check the running Node version (ignoring any 'v' prefix) matches the version in [.nvmrc](../.nvmrc)
3848

3949
```
4050
$ node --version
4151
```
4252

43-
#### corepack
53+
#### fnm
54+
55+
[fnm](https://github.com/Schniz/fnm) has some useful features which we recommend to make Node version detection as seamless as possible:
56+
57+
##### --use-on-cd
58+
59+
This configuration automatically detects and changes to the required Node version when changing directories.
60+
61+
https://github.com/Schniz/fnm/blob/master/docs/configuration.md#--use-on-cd
62+
63+
##### --version-file-strategyrecursive
64+
65+
This configuration allows the Node version detection to scan all parent directories.
66+
67+
https://github.com/Schniz/fnm/blob/master/docs/configuration.md#--version-file-strategyrecursive
68+
69+
### Corepack
4470

4571
Enable [corepack](https://github.com/nodejs/corepack) to install the correct package manager:
4672

@@ -50,7 +76,7 @@ $ corepack enable
5076

5177
If you're using `asdf`, you'll need to run `asdf reshim nodejs` after running `corepack enable`.
5278

53-
### Install Dependencies
79+
### Install dependencies
5480

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

@@ -66,19 +92,13 @@ $ make install
6692

6793
If you get an Node version error then check the setup for your version manager.
6894

69-
With `fnm` you can force it to use the version in .nvmrc with:
70-
71-
```
72-
$ fnm use
73-
```
74-
7595
### Running locally
7696

7797
```sh
7898
$ make dev
7999
```
80100

81-
This will start the development server on [http://localhost:3030](http://localhost:3030).
101+
Will start the development server on [http://localhost:3030](http://localhost:3030).
82102

83103
A list of content types with example URLs is available on the [root path](http://localhost:3030).
84104

@@ -88,29 +108,62 @@ http://localhost:3030/Article/https://www.theguardian.com/sport/2019/jul/28/tour
88108
You can view the JSON representation of an article as sent by [Frontend](https://github.com/guardian/frontend) to DCR, by appending `.json?dcr=true` to the production URL, for example:
89109
https://www.theguardian.com/sport/2019/jul/28/tour-de-france-key-moments-egan-bernal-yellow-jersey.json?dcr=true
90110

91-
### Detailed Setup
111+
### Detailed setup
92112

93-
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](docs/contributing/detailed-setup-guide.md).
113+
If you're trying to integrate with other applications, we also have a more [detailed setup guide](docs/contributing/detailed-setup-guide.md).
114+
115+
## VS Code
116+
117+
We recommend using [VSCode](https://code.visualstudio.com/).
118+
119+
### Settings
120+
121+
We have configured a collection of _required_ VS Code settings in the file `.vscode/settings.json.required`.
122+
123+
We have configured a collection of _recommended_ VS Code settings in the file `.vscode/settings.json.recommended`.
124+
125+
Copy the required settings and any recommended settings you wish to use over to `.vscode/settings.json` to activate them.
126+
127+
The `settings.json` file is git ignored to prevent it from overriding any indivdiual developer's settings.
128+
129+
### Extensions
130+
131+
VSCode should prompt you to install our recommended extensions when you open the project.
132+
133+
You can also find these extensions by searching for `@recommended` in the extensions pane.
134+
135+
### Auto fix on save
136+
137+
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:
138+
139+
1. Open the Command Palette (`shift + cmd + P`) and select:
140+
141+
```
142+
Preferences: Open Workspace Settings (JSON)
143+
```
144+
145+
2. If it doesn't already exist add the following:
146+
```json
147+
"editor.codeActionsOnSave": {
148+
"source.fixAll.eslint": true
149+
}
150+
```
94151
95152
## Technologies
96153
97154
| Technology | Description |
98155
| -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
156+
| <img alt="Typescript" src="./docs/images/logo-typescript.png" width="350" /> | DCR is written in [TypeScript](https://www.typescriptlang.org/) |
99157
| <img alt="Preact" src="./docs/images/logo-preact.jpg" width="350" /> | 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. |
100-
| <img alt="Emotion CSS-in-JS" src="./docs/images/logo-emotion.png" width="350" /> | Emotion is css-in-js library, DCR uses the `css` tagged template literal style to allow CSS copy-pasting. |
101-
| <img alt="Typescript" src="./docs/images/logo-typescript.png" width="350" /> | DCR is written in Typescript. You can see the [block element types](./src/lib/content.d.ts) as an example of our Typescript types. |
102-
| <img alt="Express" src="./docs/images/logo-express.png" width="350" /> | We use Express as a very thin server to communicate with the Frontend endpoint. |
103-
| <img alt="Storybook" src="./docs/images/logo-storybook.jpg" width="350" /> | We use [storybook to generate component variations and 'layouts'](https://main--63e251470cfbe61776b0ef19.chromatic.com) 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. |
104-
| <img alt="Chromatic" src="./docs/images/logo-chromatic.jpg" width="350" /> | Chromatic is a visual regression testing tool that reviews our Storybook components at PR time. |
105-
| <img alt="Jest" src="./docs/images/logo-jest.jpg" width="350" /> | Jest is a unit testing tool. You will find Jest tests in the repo with `.test.` filenames. |
106-
| <img alt="Playwright" src="./docs/images/logo-playwright.svg" width="350" /> | Playwright is an integration testing tool that runs tests in the browser. You will find the Playwright tests in the [playwright directory](./playwright). |
158+
| <img alt="Emotion CSS-in-JS" src="./docs/images/logo-emotion.png" width="350" /> | [Emotion](https://emotion.sh) is css-in-js library, DCR uses the `css` tagged template literal style to allow CSS copy-pasting. |
159+
| <img alt="Express" src="./docs/images/logo-express.png" width="350" /> | We use [Express](https://expressjs.com/) as a very thin server to communicate with the Frontend endpoint. |
160+
| <img alt="Storybook" src="./docs/images/logo-storybook.jpg" width="350" /> | We use [Storybook](https://storybook.js.org/) to generate [component variations](https://main--63e251470cfbe61776b0ef19.chromatic.com) that are then visual regression tested in [Chromatic](https://www.chromatic.com/). You'll notice `.stories.` files in the repository that define the component variations. |
161+
| <img alt="Chromatic" src="./docs/images/logo-chromatic.jpg" width="350" /> | [Chromatic](https://www.chromatic.com/) is a visual regression testing tool that tests our Storybook components at PR time. |
162+
| <img alt="Jest" src="./docs/images/logo-jest.jpg" width="350" /> | [Jest](https://jestjs.io) is a unit testing tool. You will find Jest tests in the repo with `.test.` filenames. |
163+
| <img alt="Playwright" src="./docs/images/logo-playwright.svg" width="350" /> | [Playwright](https://playwright.dev/) is an integration testing tool that runs tests in the browser. You will find the Playwright tests in the [playwright directory](./playwright). |
107164
| <img alt="AB Testing" src="./docs/images/logo-ab-testing.png" width="350" /> | The [A/B Testing library](https://github.com/guardian/csnx/tree/main/libs/@guardian/ab-core) is an internal NPM Module. There are [docs here](./docs/development/ab-testing-in-dcr.md). |
108165
| <img alt="Deno" title="Deno logo, MIT License: https://deno.land/artwork" src="./docs/images/logo-deno.svg" width="350" /> | [Deno](https://deno.land/) 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](../scripts/deno/README.md). |
109166
110-
## Design System
111-
112-
[Source](https://theguardian.design) is the Guardian's design system. For detailed and up-to-date information on how to use it, see the [Source guide](https://github.com/guardian/csnx/blob/main/docs/source/README.md).
113-
114167
## Concepts
115168
116169
There are some concepts to learn, that will make working with Dotcom Rendering clearer:
@@ -122,7 +175,11 @@ There are some concepts to learn, that will make working with Dotcom Rendering c
122175
- [Enhancers](docs/patterns/enhancers.md)
123176
- Data generated in Frontend
124177
125-
## Code Quality
178+
## Design system
179+
180+
[Source](https://theguardian.design) is the Guardian's design system. For detailed and up-to-date information on how to use it, see the [Source guide](https://github.com/guardian/csnx/blob/main/docs/source/README.md).
181+
182+
## Code quality
126183
127184
You can ensure your code passes code quality tests by running:
128185
@@ -149,7 +206,9 @@ $ make fix
149206

150207
See [the makefile](./makefile) for the full list.
151208

152-
[Read about testing tools and testing strategy](docs/testing.md).
209+
## Testing
210+
211+
[Testing tools and testing strategy](docs/testing.md)
153212

154213
## Debugging
155214

@@ -168,30 +227,3 @@ To check for vulnerabilities in development, you can run:
168227
```sh
169228
$ make audit
170229
```
171-
172-
## IDE
173-
174-
We recommend using [VSCode](https://code.visualstudio.com/).
175-
176-
### Extensions
177-
178-
VSCode should prompt you to install our recommended extensions when you open the project.
179-
180-
You can also find these extensions by searching for `@recommended` in the extensions pane.
181-
182-
### Auto fix on save
183-
184-
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:
185-
186-
1. Open the Command Palette (`shift + cmd + P`) and select:
187-
188-
```
189-
Preferences: Open Workspace Settings (JSON)
190-
```
191-
192-
2. Add the following:
193-
```json
194-
"editor.codeActionsOnSave": {
195-
"source.fixAll.eslint": true
196-
}
197-
```

0 commit comments

Comments
 (0)