Skip to content

Commit c553afb

Browse files
puckowskipuckowski
committed
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.
1 parent b92dc1a commit c553afb

File tree

1 file changed

+99
-27
lines changed

1 file changed

+99
-27
lines changed

‎content/usage/developing-less.md‎

Lines changed: 99 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -6,50 +6,122 @@ Thanks for thinking about contributing! Please read the [contributing instructio
66

77
## Install These Tools
88

9-
* **node** - <http://nodejs.org/>
10-
* **phantomjs** - <http://phantomjs.org/download.html>
9+
To develop Less.js locally, you’ll need **Node.js** and **pnpm**.
1110

12-
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.
11+
### 1. Install Node.js
12+
Download and install the latest LTS release from [nodejs.org](https://nodejs.org/en/download).
1313

14-
* clone your less.js repository locally
15-
* navigate to your local less.js repository and run `npm install` this installs less' npm dependencies.
14+
Verify that Node.js is on your path:
15+
```bash
16+
node -v
17+
# Example: v20.10.0
18+
```
1619

17-
## Usage
20+
### 2. Install pnpm
21+
Less.js uses [pnpm](https://pnpm.io/) for dependency management.
22+
23+
If `pnpm` isn’t installed yet, add it globally:
24+
```bash
25+
npm install -g pnpm
26+
```
27+
28+
Verify:
29+
```bash
30+
pnpm -v
31+
# Example: 9.6.0
32+
```
33+
34+
> **Note:** pnpm requires Node.js. Installing Node also provides npm, but Less.js uses pnpm for its workspace efficiency and deterministic installs.
1835
19-
[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]`.
36+
### 3. Clone and Install Dependencies
37+
Clone your local copy of the repository and install dependencies:
38+
```bash
39+
git clone https://github.com/less/less.js.git
40+
cd less.js
41+
pnpm install
42+
```
2043

21-
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`
44+
> The first `pnpm install` may take longer as pnpm builds its global content-addressable store.
2245
23-
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.
46+
### 4. Verify Setup
47+
If you start your command line and type:
48+
```bash
49+
node -v
50+
pnpm -v
51+
```
52+
you should see both version numbers.
53+
If you see “command not found,” check your PATH or reinstall the tools.
2454

25-
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.
55+
> **Tip:** If you encounter errors like `Command not found: grunt`, run tasks through
56+
> `pnpm run grunt -- <task>` or install the CLI globally:
57+
> ```bash
58+
> pnpm add -g grunt-cli
59+
> ```
2660
27-
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`).
61+
## Usage
2862
29-
Other grunt commands
63+
Grunt is used for builds, tests, benchmarks, and helper tasks. Run tasks with:
64+
```bash
65+
pnpm run grunt -- <task>
66+
```
67+
(or `grunt <task>` if `grunt-cli` is installed globally).
3068
31-
* `npm run grunt -- benchmark` - run our benchmark tests to get some numbers on performance
32-
* `npm run grunt -- stable` to create a new release
33-
* `npm run grunt -- readme` to generate a new readme.md in the root directory (after each release)
69+
A common shortcut:
70+
```bash
71+
pnpm test
72+
```
73+
is an alias for `pnpm run grunt -- test`.
74+
75+
### Useful Tasks and What They Do
76+
77+
- `pnpm run grunt -- test`
78+
Runs the full test suite (lint, node/browser builds, shell option tests, plugin tests, starts the server, and runs browser tests).
79+
- `pnpm run grunt -- dist`
80+
Builds distributables (runs `shell:build`).
81+
- `pnpm run grunt -- browsertest`
82+
Builds the browser bundle, starts a local server, and runs the browser test runner (uses Sauce Labs locally or Phantom depending on env).
83+
- `pnpm run grunt -- browsertest-server`
84+
Builds browser bundle + generates browser test pages and starts a keepalive server so you can open test runner pages manually.
85+
Open the test pages at: [http://localhost:8081/tmp/browser/](http://localhost:8081/tmp/browser/)
86+
- `pnpm run grunt -- benchmark`
87+
Runs performance benchmarks.
88+
- `pnpm run grunt -- shell-options`
89+
Runs the shell options matrix tests (includes deprecated options).
90+
- `pnpm run grunt -- shell-plugin`
91+
Runs plugin-related shell tests.
92+
- `pnpm run grunt -- quicktest`
93+
Quickly builds CommonJS and runs Node tests.
94+
95+
## Debugging Browser Tests Locally
96+
97+
1. Build the browser bundle and generate test pages:
98+
```bash
99+
pnpm run grunt -- browsertest-lessjs
100+
pnpm run grunt -- shell:generatebrowser
101+
```
102+
or simply:
103+
```bash
104+
pnpm run grunt -- browsertest-server
105+
```
106+
which builds, generates pages, and starts a keepalive server.
107+
108+
2. Open the runner pages in your browser:
109+
```
110+
http://localhost:8081/tmp/browser/
111+
```
112+
113+
If you need to keep the server running and interactively debug tests, use `connect::keepalive` via the `browsertest-server` task.
34114

35115
## How to Run Less in Other Environments
36116

37-
If you look in the libs folder you will see `less`, `less-node`, `less-browser`. The `less` folder is pure javascript with no environment
38-
specifics. if you require `less/libs/less`, you get a function that takes an environment object and an array of file managers. The file
39-
managers are the same file managers that can also be written as a plugin.
117+
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.
40118

41119
```js
42120
var createLess = require("less/libs/less"),
43121
myLess = createLess(environment, [myFileManager]);
44122
```
45123

46-
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)
47-
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).
48-
49-
For file managers we highly recommend setting the prototype as a new AbstractFileManager - this allows you to override what is needed and allows us
50-
to implement new functions without breaking existing file managers. For an example of file managers, see the 2 node implementations, the browser implementation or
51-
the npm import plugin implementation.
52-
53-
## Guide
124+
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)
125+
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).
54126

55-
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.
127+
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.

0 commit comments

Comments
 (0)