less / less/less-docs

Mention that `@import` forces asynchronous behaviour

Open
#483 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

up-for-grabs
Dominant language
Less
Stars
680
Forks
442
PR merge metrics
No merged PRs in 30d

Description

(Copied from less/less.js#3238)

According to the docs, calling less.render() with a callback allows synchronous processing of the resulting CSS code:

If you specify a callback then a promise will not be returned, where as if you do not specify a callback a promise will be given. Under the hood, the callback version is used so that less can be used synchronously.

This works in both environments, NodeJS and browser, until I use an @import statement and the browser starts to behave asynchronously. (NodeJS still renders synchronously using the syncImport option.)

@matthew-dean explains that this is by design:

sync imports used to be used in Less in the browser, but browsers are phasing out the ability to do XHR sync requests at all, because it kills your webpage.

I suggest this should be mentioned either in the paragraph about synchronous processing and/or in the section about @import At-Rules.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the programmatic usage section on synchronous processing and the @import At-Rules section linked in the issue. Document that browser @import processing remains asynchronous even when a callback is supplied, while noting the NodeJS syncImport distinction; done means both relevant sections set this expectation clearly.

Written by the indexing model from the issue text.

Assessment

Tech stack
node.js
Domain
documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
Under an hour
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.