Mention that `@import` forces asynchronous behaviour

[p3k]

(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.

[matthew-dean]

It's not so much an "@import forces asynchronous behaviour" as much as async is all that is available in the browser. But yes, that should be called out as a Node-only feature. Sorry it was confusing for you!