An API for plugins (the official thread)

[Soviut]

There has been a lot of discussion about an API to create plugins for LESS. Let this be the official thread where said API and plugin mechanics be discussed!

(This is continued from #1483 in case anyone goes there first)

[Soviut]

The first thing I can think of is that the plugin system is going to need several entry points or hooks. The first two I can think of are pre-compile and post-compile hooks. These would be useful for conditional blocks before compiling or adding vendor prefixes after compiling.

Once we delve into the core, a pre and post hook for each stage of the compilation process would probably be a good idea. If only to be able to alert external listeners that a stage has begun or completed.

Finally, hooks when each node along the AST tree seem logical.

[jonschlinkert]

Thanks @Soviut! You're on top of it!

Here are a few general (non-platform-specific) conventions I'd like to see:

• Plugins are easily registered with Less.js
• Plugins have a light and readable signature
• Plugins should always follow a single-responsibility pattern. libraries can still combine and consume plugins to create richer applications and extensions, but the rule of thumb should be "one thing, and one thing only".
• The core Less.js team should provide generic utilities to be used in plugins, as well as documentation, examples and best-practices for creating them.

[Soviut]

Plugins should have a very well defined naming convention, something along the lines of jquery plugins.

less.autoprefixer.js

or

lessjs.autoprefixer.js

Personally, I prefer the first since it reads far better, especially when you take the .js extension into account as part of the name,

[Soviut]

Plugins should have an explicit manifest, similar to package.json in npm. This doesn't necessarily have to be an external file, it may be better suited to an object within the plugin on a reserved variable.

The main reason for this would be to allow the plugin to explain whether it's suitable for browser compilation, server compilation, or both. Version information and other details may also be worth adding, but that may begin to add unnecessary clutter.

[jonschlinkert]

Yeah, a naming convention is definitely something to consider. The main advantage is for indexing/search, as with other projects like Yeoman, jQuery, Grunt and Gulp. But it doesn't have to be in the name of the project, it can also be a registration system and/or keywords in package.json (for node.js plugins), or other methods.

Ultimately some plugins won't conform to this, and shouldn't necessarily have to. So let's just be pragmatic and creative about the approach.

[lukeapage]

My plan was that plugins would be seperate repos and less would scan for those repos begining less-plugin* and then use them.

So far I have just exposed a plugins option which is an array of visitors, following the internal format for visitors.

Its all great other people having input on plugins but unless someone else has time to help implement something different, a small expansion on the above is about as far an API as people are going to get.

I'm of course happy to change any naming or anything else - I already discussed with Jon about the naming of the core plugins repo and thats yet to change.

So please understand the code already outstanding. References.

https://github.com/less/less-plugins.js
https://github.com/less/less.js/blob/master/lib/less/parser.js#L557
less/less-plugin-inline-urls#1

and perhaps the last issue over the naming could do with some good ideas, although @jonschlinkert I think has made a good start.

[jonschlinkert]

it may be better suited to an object within the plugin on a reserved variable.

Yeah, that may not be a bad way to go. We have lots of other great libraries out there to look at for examples. But just to emphasize my last point... I think plugins should consist of code that - whenever possible - is usable outside of the Less.js ecosystem - so whatever "register" signature we use should be promoted as a wrapper for more generalized code. Of course, there will be many exceptions to this, when developers need to create something that will only work with Less.js, but exceptions shouldn't drive the rule.

I think express middleware, gulp plugins and handlebars helpers (in particular) are great examples.

[jonschlinkert]

all good points, @lukeapage. Maybe it would be best if we just look at this thread as being focused on a best-case scenario, not an expectation (which I don't think anyone has anyway)

[jonschlinkert]

I already discussed with Jon about the naming of the core plugins repo and thats yet to change.

did we decide that was going to change? sorry I don't remember

[Soviut]

Regarding modularity, Grunt provides a good example of how to wrap existing tools in a thin wrapper so they're compatible with the core. However, the do maintain a good naming convention for plugins grunt-name and for core plugins grunt-contrib-name. So I would at least propose naming the wrappers with a less prefix.

[jonschlinkert]

Grunt provides a good example of how to wrap existing tools in a thin wrapper

Yeah, that's definitely the goal with Grunt plugins, to make them thin wrappers. But a couple things to consider. Grunt doesn't require names to follow that convention (see assemble, they just encouraged it initially, but the Gruntfile doesn't care what a plugin is named as long as it's registered.

Also, Grunt is a task runner that offers a declarative config and extensive API for "wrapping" other libs, but (unless we're thinking differently here, which might be good) Less.js won't be "running" anything.

Rather, Less.js just needs to expose an API for registering plugins so that other tools like Grunt and Gulp can consume Less.js along with the plugins that should be registered. meaning that any naming convention would be a convenience for finding plugins (by users, not Less.js). I think that Less.js itself should care about plugin names as much as it does about the name of a file referenced in an @import statement.

But I do agree that we should "encourage" a naming convention for Less.js plugins so that they are easier to find on npm, bower etc

[Soviut]

Agreed, I only meant we should establish an official naming convention, not that it should be strictly enforced. It's just very difficult to establish conventions like this after the fact.

[jonschlinkert]

👍