From c553afb94ee28f5bcfbaee9f5fe060bd4587fc58 Mon Sep 17 00:00:00 2001 From: Daniel Puckowski Date: Fri, 31 Oct 2025 17:54:16 -0400 Subject: [PATCH 1/2] feat: update contributing documentation * Update contributing to Less.js documentation to reflect pnpm usage and reflect the fact that PhantomJS is no longer required. Update grunt command options. Fix some Less.js GitHub links. --- content/usage/developing-less.md | 126 ++++++++++++++++++++++++------- 1 file changed, 99 insertions(+), 27 deletions(-) diff --git a/content/usage/developing-less.md b/content/usage/developing-less.md index 46e4c1a5..c68b6031 100644 --- a/content/usage/developing-less.md +++ b/content/usage/developing-less.md @@ -6,50 +6,122 @@ Thanks for thinking about contributing! Please read the [contributing instructio ## Install These Tools -* **node** - -* **phantomjs** - +To develop Less.js locally, you’ll need **Node.js** and **pnpm**. -make sure the paths are setup. If you start your favourite command line and type `node -v` you should see the node compiler. If you run `phantomjs -v` you should see the phantomjs version number. +### 1. Install Node.js +Download and install the latest LTS release from [nodejs.org](https://nodejs.org/en/download). -* clone your less.js repository locally -* navigate to your local less.js repository and run `npm install` this installs less' npm dependencies. +Verify that Node.js is on your path: +```bash +node -v +# Example: v20.10.0 +``` -## Usage +### 2. Install pnpm +Less.js uses [pnpm](https://pnpm.io/) for dependency management. + +If `pnpm` isn’t installed yet, add it globally: +```bash +npm install -g pnpm +``` + +Verify: +```bash +pnpm -v +# Example: 9.6.0 +``` + +> **Note:** pnpm requires Node.js. Installing Node also provides npm, but Less.js uses pnpm for its workspace efficiency and deterministic installs. -[Grunt](https://gruntjs.com/) is used in order to run development commands such as tests, builds, and benchmarks. You can run them either with `grunt [command_name]` if you have `grunt-cli` installed globally or with `npm run grunt -- [command_name]`. +### 3. Clone and Install Dependencies +Clone your local copy of the repository and install dependencies: +```bash +git clone https://github.com/less/less.js.git +cd less.js +pnpm install +``` -If you go to the root of the Less repository you should be able to do `npm test` (a handy alias for `npm run grunt -- test`) - this should run all the tests. For the browser specific only, run `npm run grunt -- browsertest` If you want to try out the current version of less against a file, from here do `node bin/lessc path/to/file.less` +> The first `pnpm install` may take longer as pnpm builds its global content-addressable store. -To debug the browser tests, run `npm run grunt -- browsertest-server` then go to http://localhost:8088/tmp/browser/ to see the test runner pages. +### 4. Verify Setup +If you start your command line and type: +```bash +node -v +pnpm -v +``` +you should see both version numbers. +If you see “command not found,” check your PATH or reinstall the tools. -Optional: To get the current version of the Less compiler do `npm -g install less` - npm is the node package manager and "-g" installs it to be available globally. +> **Tip:** If you encounter errors like `Command not found: grunt`, run tasks through +> `pnpm run grunt -- ` or install the CLI globally: +> ```bash +> pnpm add -g grunt-cli +> ``` -You should now be able to do `lessc file.less` and if there is an appropriate `file.less` then it will be compiled and output to the stdout. You can then compare it to running locally (`node bin/lessc file.less`). +## Usage -Other grunt commands +Grunt is used for builds, tests, benchmarks, and helper tasks. Run tasks with: +```bash +pnpm run grunt -- +``` +(or `grunt ` if `grunt-cli` is installed globally). -* `npm run grunt -- benchmark` - run our benchmark tests to get some numbers on performance -* `npm run grunt -- stable` to create a new release -* `npm run grunt -- readme` to generate a new readme.md in the root directory (after each release) +A common shortcut: +```bash +pnpm test +``` +is an alias for `pnpm run grunt -- test`. + +### Useful Tasks and What They Do + +- `pnpm run grunt -- test` + Runs the full test suite (lint, node/browser builds, shell option tests, plugin tests, starts the server, and runs browser tests). +- `pnpm run grunt -- dist` + Builds distributables (runs `shell:build`). +- `pnpm run grunt -- browsertest` + Builds the browser bundle, starts a local server, and runs the browser test runner (uses Sauce Labs locally or Phantom depending on env). +- `pnpm run grunt -- browsertest-server` + Builds browser bundle + generates browser test pages and starts a keepalive server so you can open test runner pages manually. + Open the test pages at: [http://localhost:8081/tmp/browser/](http://localhost:8081/tmp/browser/) +- `pnpm run grunt -- benchmark` + Runs performance benchmarks. +- `pnpm run grunt -- shell-options` + Runs the shell options matrix tests (includes deprecated options). +- `pnpm run grunt -- shell-plugin` + Runs plugin-related shell tests. +- `pnpm run grunt -- quicktest` + Quickly builds CommonJS and runs Node tests. + +## Debugging Browser Tests Locally + +1. Build the browser bundle and generate test pages: + ```bash + pnpm run grunt -- browsertest-lessjs + pnpm run grunt -- shell:generatebrowser + ``` + or simply: + ```bash + pnpm run grunt -- browsertest-server + ``` + which builds, generates pages, and starts a keepalive server. + +2. Open the runner pages in your browser: + ``` + http://localhost:8081/tmp/browser/ + ``` + +If you need to keep the server running and interactively debug tests, use `connect::keepalive` via the `browsertest-server` task. ## How to Run Less in Other Environments -If you look in the libs folder you will see `less`, `less-node`, `less-browser`. The `less` folder is pure javascript with no environment -specifics. if you require `less/libs/less`, you get a function that takes an environment object and an array of file managers. The file -managers are the same file managers that can also be written as a plugin. +If you look in the libs folder you will see `less`, `less-node`, `less-browser`. The `less` folder is pure javascript with no environment specifics. if you require `less/libs/less`, you get a function that takes an environment object and an array of file managers. The file managers are the same file managers that can also be written as a plugin. ```js var createLess = require("less/libs/less"), myLess = createLess(environment, [myFileManager]); ``` -The environment api is specified in [less/libs/less/environment/environment-api.js](https://github.com/less/less.js/blob/master/lib/less/environment/environment-api.js) -and the file manager api is specified in [less/libs/less/environment/file-manager-api.js](https://github.com/less/less.js/blob/master/lib/less/environment/file-manager-api.js). - -For file managers we highly recommend setting the prototype as a new AbstractFileManager - this allows you to override what is needed and allows us -to implement new functions without breaking existing file managers. For an example of file managers, see the 2 node implementations, the browser implementation or -the npm import plugin implementation. - -## Guide +The environment api is specified in [packages/less/src/less/environment/environment-api.ts](https://github.com/less/less.js/blob/master/packages/less/src/less/environment/environment-api.ts) +and the file manager api is specified in [packages/less/src/less/environment/file-manager-api.ts](https://github.com/less/less.js/blob/master/packages/less/src/less/environment/file-manager-api.ts). -If you look at [http://www.gliffy.com/go/publish/4784259](http://www.gliffy.com/go/publish/4784259), This is an overview diagram of how less works. Warning! It needs updating with v2 changes. +For file managers we highly recommend setting the prototype as a new AbstractFileManager - this allows you to override what is needed and allows us to implement new functions without breaking existing file managers. For an example of file managers, see the 2 node implementations, the browser implementation or the npm import plugin implementation. From e4e67d6c372521b8687b642dcc9d5fb6f3a611de Mon Sep 17 00:00:00 2001 From: Daniel Puckowski Date: Sat, 1 Nov 2025 14:20:25 -0400 Subject: [PATCH 2/2] chore: fix documentation spelling * Fix documentation spelling by switching to a capital 'i'. --- content/usage/developing-less.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/usage/developing-less.md b/content/usage/developing-less.md index c68b6031..fad56ad5 100644 --- a/content/usage/developing-less.md +++ b/content/usage/developing-less.md @@ -114,7 +114,7 @@ If you need to keep the server running and interactively debug tests, use `conne ## How to Run Less in Other Environments -If you look in the libs folder you will see `less`, `less-node`, `less-browser`. The `less` folder is pure javascript with no environment specifics. if you require `less/libs/less`, you get a function that takes an environment object and an array of file managers. The file managers are the same file managers that can also be written as a plugin. +If you look in the libs folder you will see `less`, `less-node`, `less-browser`. The `less` folder is pure javascript with no environment specifics. If you require `less/libs/less`, you get a function that takes an environment object and an array of file managers. The file managers are the same file managers that can also be written as a plugin. ```js var createLess = require("less/libs/less"),