Skip to content

Commit 08bfd2c

Browse files
meirzamoodlemeirzamoodle
committed
MDL-87759 [docs] Add React build tools documentation
Add new React documentation pages under `docs/guides/javascript/react`: - `index.md` with a React overview and navigation - `buildtools.md` describing the React build workflow in Moodle Document key tooling details including: - Grunt tasks (`react`, `react:dev`) - watch/lint workflow - TypeScript alias generation - esbuild externals and output conventions Also update `general/development/tools/nodejs.md` to include the new React Grunt commands.
1 parent 9448879 commit 08bfd2c

3 files changed

Lines changed: 153 additions & 0 deletions

File tree

‎docs/guides/javascript/react/buildtools.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
---
2+
title: Build tools
3+
tags:
4+
- react
5+
- javascript
6+
- moodle
7+
description: Overview of Moodle's React developer documentation and what each page covers.
8+
---
9+
10+
Moodle provides React TypeScript component builds using esbuild integrated with Grunt.
11+
This page focuses on the React build toolchain used in Moodle.
12+
13+
## What is covered
14+
15+
### React build is integrated into Grunt
16+
17+
React is part of the JavaScript build pipeline alongside AMD and YUI. All JS build
18+
orchestration lives in `.grunt/tasks/javascript.js`.
19+
20+
New Grunt task: `react`, with three modes:
21+
22+
| Command | Description |
23+
|---|---|
24+
| `grunt react` | Production build (minified, no sourcemaps) |
25+
| `grunt react:dev` | Development build (inline sourcemaps, no minification) |
26+
| `grunt react:watch` | esbuild native watch mode (see below) |
27+
28+
Build orchestration is handled by `.esbuild/build.mjs`, which:
29+
30+
1. Generates TypeScript path aliases.
31+
2. Builds all plugin and core React component bundles.
32+
33+
### Context-aware `grunt` from React source directories
34+
35+
Running `grunt` in `js/react/src` now triggers `grunt react`.
36+
37+
```bash
38+
cd public/mod/book/js/react/src
39+
grunt
40+
```
41+
42+
### Watch mode uses esbuild native context
43+
44+
`grunt react:watch` uses esbuild's own `context.watch()` to monitor React source
45+
files. This is intentionally separate from `grunt watch` — esbuild maintains an
46+
incremental build graph internally, so rebuilds reuse the previous parse result
47+
rather than restarting from scratch on every change.
48+
49+
After each rebuild, ESLint runs on the changed source files in check-only mode
50+
(no `--fix`) to avoid re-triggering esbuild with auto-fixed rewrites.
51+
52+
```bash
53+
grunt react:watch
54+
```
55+
56+
:::warning
57+
58+
`grunt watch` does not monitor React files.
59+
60+
:::
61+
62+
### React linting
63+
64+
- `grunt eslint:react` — runs ESLint with `fix: true` (auto-fix)
65+
66+
### Cross-component alias generation is automatic
67+
68+
Aliases like `@moodle/lms/<component>/*` are generated from Moodle component metadata.
69+
70+
- Generator: `.esbuild/generate-aliases.mjs`
71+
- Output: `tsconfig.aliases.json`
72+
- Source of truth: `.grunt/components.js`
73+
74+
Only components with real TypeScript files under `js/react/src` are included.
75+
76+
#### What `tsconfig.aliases.json` is for
77+
78+
`tsconfig.aliases.json` is generated during the React build and provides TypeScript
79+
path mappings for the `@moodle/lms/*` aliases used in React source code. It is read
80+
by `tsconfig.json` so that editors and type-checking can resolve cross-component
81+
imports correctly.
82+
83+
:::warning
84+
85+
Do not edit `tsconfig.aliases.json` manually. It is generated by `grunt react`.
86+
87+
:::
88+
89+
### External packages are excluded from bundles
90+
91+
The following imports are marked as external in the esbuild configuration and are
92+
not bundled into component output:
93+
94+
- `react`
95+
- `react-dom`
96+
- `react-dom/client`
97+
- `@moodle/lms`
98+
- `@moodle/lms/*`
99+
100+
This ensures shared runtime packages are not duplicated across bundles.
101+
102+
## Directory conventions
103+
104+
React source and output follow this structure per component:
105+
106+
```text
107+
<component>/
108+
└── js/
109+
└── react/
110+
├── src/ # TypeScript/TSX source
111+
└── build/ # Generated ES module output
112+
```
113+
114+
## Commands for developers
115+
116+
```bash
117+
# Build all React components (production)
118+
grunt react
119+
120+
# Build all React components (development)
121+
grunt react:dev
122+
123+
# Watch React files with esbuild native watch
124+
grunt react:watch
125+
126+
# React lint with auto-fix
127+
grunt eslint:react
128+
```
129+
130+
## See also
131+
132+
- [Grunt](/general/development/tools/nodejs#grunt) - How to install Grunt and Watchman

‎docs/guides/javascript/react/index.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
title: React
3+
tags:
4+
- react
5+
- javascript
6+
- moodle
7+
description: Overview of Moodle's React developer documentation and what each page covers.
8+
---
9+
10+
## Overview
11+
12+
This section provides an end-to-end overview of React development in Moodle, including setup, bundling, integration patterns, code quality, testing, and debugging workflows.
13+
14+
## Build tools
15+
16+
The build documentation explains how React source code is compiled, bundled, and prepared for use in Moodle. It also covers the supporting build tools and common setup requirements.
17+
18+
## See also
19+
20+
- [Build tools](./buildtools.md)

‎general/development/tools/nodejs.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,7 @@ Typical commands:
9393
grunt amd # Alias for "ignorefiles", "eslint:amd", "rollup"
9494
grunt js # Alias for "amd", "yui" tasks.
9595
grunt css # Alias for "scss", "rawcss" tasks.
96+
grunt react # Build all React components.
9697
grunt shifter # Run Shifter
9798
grunt componentlibrary # Build the component library
9899
grunt eslint --show-lint-warnings # Show pedantic lint warnings for JS

0 commit comments

Comments
 (0)