From 50b44817d85fb689b628ca47c5ef734ce45d8c41 Mon Sep 17 00:00:00 2001 From: meirzamoodle Date: Fri, 20 Feb 2026 21:18:23 +0700 Subject: [PATCH] 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. --- docs/guides/javascript/react/buildtools.md | 116 +++++++++++++++++++++ docs/guides/javascript/react/index.md | 20 ++++ general/development/tools/nodejs.md | 2 + 3 files changed, 138 insertions(+) create mode 100644 docs/guides/javascript/react/buildtools.md create mode 100644 docs/guides/javascript/react/index.md diff --git a/docs/guides/javascript/react/buildtools.md b/docs/guides/javascript/react/buildtools.md new file mode 100644 index 0000000000..22d4d56da7 --- /dev/null +++ b/docs/guides/javascript/react/buildtools.md @@ -0,0 +1,116 @@ +--- +title: Build tools +tags: + - react + - javascript + - moodle +description: Overview of Moodle's React developer documentation and what each page covers. +--- + +Moodle provides React TypeScript component builds using esbuild integrated with Grunt. +This page focuses on the React build toolchain used in Moodle. + +## What is covered + +### React build is integrated into Grunt + +- New Grunt task: `react` +- Dev variant: `react:dev` + +Build orchestration is handled by `.esbuild/build.mjs`, which: + +1. Generates TypeScript path aliases. +2. Builds platform bootstrap code (`react_autoinit`). +3. Builds plugin/core React component bundles. + +### Context-aware `grunt` from React source directories + +Running `grunt` in `js/react/src` now triggers `grunt react`. + +```bash +cd public/mod/book/js/react/src +grunt +``` + +### Watch mode supports React TS/TSX files + +`grunt watch` monitors `js/react/src/**/*.ts` and `js/react/src/**/*.tsx` and then: + +1. Runs `eslint:react-check` (check-only, no auto-fix). +2. Runs `reactbuild` to rebuild only changed files. + +This avoids watch loops caused by lint auto-fixes rewriting files. + +### React linting tasks are split by behavior + +- `grunt eslint:react` uses ESLint with `fix: true` +- `grunt eslint:react-check` runs without auto-fix (used by watch) + +### Cross-component alias generation is automatic + +Aliases like `@moodle/lms//*` are generated from Moodle component metadata. + +- Generator: `.esbuild/generate-aliases.mjs` +- Output: `tsconfig.aliases.json` +- Source of truth: `.grunt/components.js` + +Only components with real TypeScript files under `js/react/src` are included. + +#### What `tsconfig.aliases.json` is for + +`tsconfig.aliases.json` is generated during the React build and provides TypeScript +path mappings for the `@moodle/lms/*` aliases used in React source code. It is read +by `tsconfig.json` so that editors and type-checking can resolve cross-component +imports correctly. + +:::warning + +Do not edit `tsconfig.aliases.json` manually. It is generated by `grunt react`. + +::: + +### External package handling is defined for esbuild + +The externals plugin (`.esbuild/externals.mjs`) marks these imports as external: + +- `@moodle/lms` +- `react` +- `react-dom` +- `@moodlehq/design-system` + +This ensures shared runtime packages are not duplicated in each bundle. + +## Directory conventions + +React source and output follow this structure per component: + +```text +/ +└── js/ + └── react/ + ├── src/ # TypeScript/TSX source + └── build/ # Generated ES module output +``` + +## Commands for developers + +```bash +# Build all React components (production) +grunt react + +# Build all React components (development) +grunt react:dev + +# Watch for JS/React changes +grunt watch + +# React lint with auto-fix +grunt eslint:react + +# React lint check-only +grunt eslint:react-check +``` + +## See also + +- [Grunt](/general/development/tools/nodejs#grunt) - How to install Grunt and Watchman diff --git a/docs/guides/javascript/react/index.md b/docs/guides/javascript/react/index.md new file mode 100644 index 0000000000..689f6ebab9 --- /dev/null +++ b/docs/guides/javascript/react/index.md @@ -0,0 +1,20 @@ +--- +title: React +tags: + - react + - javascript + - moodle +description: Overview of Moodle's React developer documentation and what each page covers. +--- + +## Overview + +This section provides an end-to-end overview of React development in Moodle, including setup, bundling, integration patterns, code quality, testing, and debugging workflows. + +## Build tools + +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. + +## See also + +- [Build tools](./buildtools.md) diff --git a/general/development/tools/nodejs.md b/general/development/tools/nodejs.md index 7be9537dea..f59cd2046b 100644 --- a/general/development/tools/nodejs.md +++ b/general/development/tools/nodejs.md @@ -93,6 +93,8 @@ Typical commands: grunt amd # Alias for "ignorefiles", "eslint:amd", "rollup" grunt js # Alias for "amd", "yui" tasks. grunt css # Alias for "scss", "rawcss" tasks. +grunt react # Build all React components (production) +grunt react:dev # Build all React components (development) grunt shifter # Run Shifter grunt componentlibrary # Build the component library grunt eslint --show-lint-warnings # Show pedantic lint warnings for JS