Skip to content

docs: update module usage instructions to remove Grunt and reflect dev-2.0 tooling #7871 #7886

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: dev-2.0
Choose a base branch
from
+69 −70
Open

docs: update module usage instructions to remove Grunt and reflect dev-2.0 tooling #7871 #7886

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
49234c5
docs: replace deprecated grunt commands with npm/vitest scripts in do…
LalitNarayanYadav Jun 7, 2025
083bae8
docs: replace outdated Grunt commands with npm/Vitest equivalents in …
LalitNarayanYadav Jun 7, 2025
88eff1b
docs: revise build instructions to remove Grunt commands
LalitNarayanYadav Jun 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 6 additions & 15 deletions contributor_docs/archive/custom_p5_build.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,29 +10,20 @@ This feature was suggested as a part of a proposal for Google Summer of Code 201

## Usage

Currently, the usage is through invoking a Grunt task manually from the command line:

p5.js has migrated to modern tooling. Use the following to build and test:

```sh
git clone https://github.com/processing/p5.js.git
cd p5.js
npm ci
npm run grunt
npm run grunt combineModules:module_x:module_y
npm run build # builds the full p5.js bundle
npm test # runs linter and tests using Vitest
Comment on lines 18 to +21
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section is meant to show how to create a custom build of p5.js with selected components. Right now, the commands only build the full library and run the test suite. We should remove the final npm test line and replace it with the command that actually generates a custom bundle. I’m not sure whether the dev-2.0 branch already supports modular builds, @limzykenneth , could you confirm if dev-2.0 lets users assemble p5.js from a chosen set of modules, and if so, what the exact command is?

Comment on lines 18 to +21
Copy link
Collaborator

@perminder-17 perminder-17 Jun 9, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"runs linter and tests using Vitest" also, this line is misleading. Vitest never “runs the linter”, if you look at the script section, we have two different commands,

"scripts" : {
    "test": "vitest",
    "lint": "eslint .",
},

so, for lint we should write npm run lint, however we can probably remove the commands which is used for running tests in p5js from custom_p5_build.md?

```

Here, `module_n` refers to the name of the modules which you want to select. Multiple modules must be passed as shown above. Also, these modules must have the same name as their folders in `/src` directory to work correctly. While `core` is included by default, `core/shape` needs to be included for shapes like line() and other core features to work.

The above usage example will likely output a `p5Custom.js` larger than the complete `p5.min.js` as the output is not minified using the `uglify` task.
To include only selected modules in a custom build, refer to the CONTRIBUTING guide or module-specific documentation. Rollup or tree-shaking through ES modules may be used for advanced setups.

The recommended steps to reduce bundle size as much as possible are:

```sh
git clone https://github.com/processing/p5.js.git
cd p5.js
npm ci
npm run grunt
npm run grunt combineModules:min:module_x:module_y uglify
```
---

## Examples

Expand Down
36 changes: 14 additions & 22 deletions contributor_docs/es/steward_guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -180,7 +180,7 @@ El archivo Gruntfile.js contiene las definiciones principales de construcción p
### Tarea Principal de Construcción

```
grunt.registerTask('default', ['lint', 'test']);
npm test
```

Cuando ejecutamos `grunt` o el script npm `npm test`, ejecutamos la tarea predeterminada que consiste en `lint` y luego `test`.
Expand All @@ -189,7 +189,7 @@ Cuando ejecutamos `grunt` o el script npm `npm test`, ejecutamos la tarea predet
#### Tarea `lint`

```
grunt.registerTask('lint', ['lint:source', 'lint:samples']);
npm run lint
```

La tarea `lint` consiste en dos sub tareas: `lint:source` y `lint:samples`. `lint:source` está subdividida aún más en tres sub tareas adicionales: `eslint:build`, `eslint:source` y `eslint:test`, que utilizan ESLint para verificar los scripts de construcción, el código fuente y los scripts de prueba.
Expand All @@ -201,26 +201,20 @@ A continuación en `lint:samples` está `eslint-samples:source`, que es una tare

#### Tarea `test`

```js
grunt.registerTask('test', [
'build',
'connect:server',
'mochaChrome',
'mochaTest',
'nyc:report'
]);
En la rama `dev-2.0`, la tarea `test` de Grunt ha sido reemplazada por un comando moderno de `npm`:

```
npm test
```

Primero, veamos la tarea `build` dentro de `test`.
Este comando ejecuta la suite de pruebas completa usando [Vitest](https://vitest.dev/), e incluye cobertura y pruebas en múltiples entornos según sea necesario.


```js
grunt.registerTask('build', [
'browserify',
'browserify:min',
'uglify',
'browserify:test'
]);
```
npm run build
```

Este comando construye la biblioteca `p5.js` utilizando herramientas modernas como [Vite](https://vitejs.dev/) o configuraciones personalizadas según `package.json`. Sustituye completamente los pasos anteriores que usaban `browserify` y `uglify`.

Las tareas que comienzan con `browserify` están definidas en [./tasks/build/browserify.js](tasks/build/browserify.js). Todas siguen pasos similares con diferencias menores. Estos son los pasos principales para construir la biblioteca completa de p5.js a partir de sus numerosos archivos fuente en uno solo:

Expand Down Expand Up @@ -270,17 +264,15 @@ Finalmente, después de que todas las construcciones y pruebas estén completas,
Todos los pasos pueden ejecutarse directamente con `npx grunt [step]`. También hay algunas tareas que no se mencionan arriba pero podrían ser útiles en ciertos casos.

```
grunt yui:dev
npm test
```

Esta tarea ejecutará las construcciones de documentación y biblioteca descritas arriba, seguidas de la puesta en marcha de un servidor web que sirve una versión funcionalmente similar de la página de referencia que encontrarás en el sitio web en [http://localhost:9001/docs/reference/](http://localhost:9001/docs/reference/). Luego, supervisará el código fuente en busca de cambios y reconstruirá la documentación y la biblioteca.

`grunt` `yui:dev` es útil cuando estás trabajando en la referencia en la documentación en línea porque no necesitas mover archivos construidos del repositorio de p5.js a un repositorio local de un sitio de p5.js y reconstruir el sitio web cada vez que hagas un cambio, y puedes previsualizar tus cambios con esta versión ligeramente simplificada de la referencia en tu navegador. De esta manera, también puedes tener más confianza en que los cambios que hiciste probablemente se mostrarán correctamente en el sitio web. Ten en cuenta que esto solo está destinado a modificaciones en la documentación en línea; los cambios en la página de referencia en sí, incluido el estilo y el diseño, deben hacerse y probarse en el repositorio del sitio web.

```
grunt watch
grunt watch:main
grunt watch:quick
npm run watch
```

Las tareas de observación vigilarán una serie de archivos en busca de cambios y ejecutarán tareas asociadas para construir la referencia o la biblioteca según los archivos que hayan cambiado. Estas tareas hacen lo mismo, la única diferencia es el alcance.
Expand Down
82 changes: 49 additions & 33 deletions contributor_docs/steward_guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -175,55 +175,68 @@ Dependabot PRs are usually only visible to repo admins so if this does not apply

This section will not cover the general build setup nor commands but rather details about what's happening behind the scenes. Please see the [contributor’s guidelines](contributor_guidelines.md#working-on-p5js-codebase) for more detailed build info.

The Gruntfile.js file contains the main build definitions for p5.js. Among the different tools used to build the library and documentation includes but not limited to Grunt, Browserify, YUIDoc, ESLint, Babel, Uglify, and Mocha. It may be helpful for us to start with the `default` task and work backward from there. It may be helpful at this point to open up the Gruntfile.js document while going through the explainer below.
Starting with p5.js version 2.0, the project no longer uses Grunt for task automation. Instead, the build and test processes are handled using modern tools like npm scripts, ESLint, and [Vitest](https://vitest.dev/).


### Main build task

To run lint checks and unit tests, simply run:

```
grunt.registerTask('default', ['lint', 'test']);
npm test
```

When we run `grunt` or the npm script `npm test`, we run the default task consisting of `lint` then `test`.

This command will run ESLint to check code style and then execute unit and visual tests using Vitest.

#### `lint` Task

In p5.js 2.0, ESLint is used directly via npm scripts for all linting tasks.

To run lint checks on the codebase:

```
grunt.registerTask('lint', ['lint:source', 'lint:samples']);
npm run lint
```

The `lint` task consists of two sub tasks: `lint:source` and `lint:samples`. `lint:source` is further subdivided into three more sub tasks `eslint:build`, `eslint:source`, and `eslint:test`, which uses ESLint to check the build scripts, the source code, and the test scripts.
This checks the source files, build scripts, test files, and documentation examples using ESLint.

The `lint:samples` task will first run the `yui` task which itself consists of `yuidoc:prod`, `clean:reference`, and `minjson`, which extract the documentation from the source code into a JSON document, remove unused files from the previous step, and minify the generated JSON file into `data.min.json` respectively.
If you only want to run linting for specific files or directories, you can use ESLint directly:

Next in `lint:samples` is `eslint-samples:source`, which is a custom written task whose definition is in [../tasks/build/eslint-samples.js](../tasks/build/eslint-samples.js); it will run ESLint to check the documentation example code to make sure they follow the same coding convention as the rest of p5.js (`yui` is run first here because we need the JSON file to be built first before we can lint the examples).
```
npx eslint src/
npx eslint test/
Comment on lines +206 to +207
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, these commands look promising, and the npm run lint command appears to work correctly. Could you confirm whether changing the code’s indentation causes the linter to fail, or does it still pass? In my case, it always passes regardless of indentation.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The linter isn't implemented in v2+ yet. See #7853

In v1+ it wasn't configured for .md files. So my best bet is to not indent the code snippets.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Aah...okay. Thanks for letting me know @error-four-o-four :)

```

There is no separate sample linter or YUIDoc-based pipeline anymore, as documentation is now managed through simpler, modern tooling.

#### `test` Task

```js
grunt.registerTask('test', [
'build',
'connect:server',
'mochaChrome',
'mochaTest',
'nyc:report'
]);
In p5.js 2.0, the testing system no longer uses Mocha via Grunt. Instead, tests are run using [Vitest](https://vitest.dev/) through npm scripts.

To run the full test suite (unit and visual tests), use:

```
npm test
```

This command performs:
- Linting via ESLint
- Unit tests using Vitest
- Visual tests (render-based snapshots)

First let's look at the `build` task under `test`.
Tests are located in the `test/unit` folder, organized to mirror the `src` directory structure. For example, tests for `src/color/p5.Color.js` live in `test/unit/color/p5.Color.js`.

```js
grunt.registerTask('build', [
'browserify',
'browserify:min',
'uglify',
'browserify:test'
]);
To run tests interactively in a browser-like environment (useful for debugging), run:

```
npx vitest --ui
```

Tasks that start with `browserify` are defined in [../tasks/build/browserify.js](../tasks/build/browserify.js). They all have similar steps with minor differences. These are the main steps to build the full p5.js library from its many source code files into one:
Code coverage is also supported using Vitest's built-in tools. Run:

```
npx vitest run --coverage
```

- `browserify` builds p5.js while `browserify:min` builds an intermediate file to be minified in the next step. The difference between `browserify` and `browserify:min` is that `browserify:min` does not contain data needed for FES to function.
- `uglify` takes the output file of `browserify:min` and minify it into the final p5.min.js (configuration of this step is in the main Gruntfile.js).
Expand Down Expand Up @@ -266,22 +279,25 @@ And that covers the default task in the Gruntfile.js configuration!

### Miscellaneous tasks

All of the steps can be run directly with `npx grunt [step]`. There are also a few tasks that are not covered above but could be useful in certain cases.
All of the steps can now be run using npm scripts or directly with Vitest. The Grunt build system and tasks have been removed in the dev-2.0 branch.

You can use the equivalent npm script or local development commands (please refer to the package.json scripts section).

For testing, run:

```
grunt yui:dev
npm test
```

This task will run the documentation and library builds described above, followed by spinning up a web server that serves a functionally similar version of the reference page you will find on the website on [http://localhost:9001/docs/reference/](http://localhost:9001/docs/reference/). It will then monitor the source code for changes and rebuild the documentation and library.

`grunt` `yui:dev` is useful when you are working on the reference in the inline documentation because you don't have to move built files from the p5.js repository to a local p5.js-website repository and rebuild the website each time you make a change, and you can just preview your changes with this slightly simplified version of the reference in your browser. This way, you can also be more confident that the changes you made are likely to show up correctly on the website. Note that this is only meant for modifications to the inline documentation; changes to the reference page itself, including styling and layout, should be made and tested on the website repository.
For running watchers, use:

```
grunt watch
grunt watch:main
grunt watch:quick
npm run watch
```

Note: The previous `grunt yui:dev` task that served the documentation locally and watched for changes is replaced by modern tooling; please check the updated documentation or package.json for exact commands to serve and watch.


The watch tasks will watch a series of files for changes and run associated tasks to build the reference or the library according to what files have changed. These tasks all do the same thing, with the only difference being the scope.

The `watch` task will run all builds and tests similar to running the full default task on detecting changes in the source code.
Expand Down