Meta: Discussion of jQuery plugin package.json schema

[ajpiano]

If you have comments or concerns about the way we've configured the package.json for jQuery plugins, this here's the place to raise them.

[matthewlein]

I would love a dummy example for a plugin. Maybe use one of the "official" plugins as a guide.

[evmcl]

I think an optional "demo" URL field, similar to the "homepage" field would be of use. It was certainly handy in the old plugin site to have a direct link to a working demo you could have a look at.

[RedWolves]

@matthewlein The notion of "official" plugins is no more. see http://blog.jquery.com/2011/04/16/official-plugins-a-change-in-the-roadmap/

[jrburke]

For dependency names, I suggest making sure they follow the file name, not the object name. So, if something depends on jQuery, the dependency should be 'jquery': '>=1.7.0', and not 'jQuery'. Similar for something like Backbone, using 'backbone' will be better. This will fit better with how node and AMD normally find modules -- by looking at the file name.

[jrburke]

What about supporting the package.json in a comment in the JS file itself?

I have opened a similar issue with npm, but basically, it would be nice for your tooling to recognize a comment like so:

/*package.json
{}
*/

This would avoid having to create a separate file for this info, and since it is a comment, it should minify out for deployment.

[rdworth]

@jrburke said:

I suggest making sure they follow the file name, not the object name

Yup, although to be pedantic, we'll match it to the plugin name (the name field in the package.json) which will be used to determine the url on plugins.jquery.com. But the filename of course would have other stuff in it, and is not actually required to be specified. Example:

filename: jquery.imageslider.js
object name: jquery.fn.imageSlider
plugin name: imageslider

[rdworth]

@matthewlein: Great thinking. As Ralph points out, we no longer use the term "official plugins", but the jQuery core team maintains the color plugin, so I added a package.json for it as a sample at the end of the spec file.

[rdworth]

@jrburke said:

What about supporting the package.json in a comment in the JS file itself?

One of the main problems with this is discoverability. What we've achieved to date is that given a GitHub repo url (comes down to username + repo name), we can walk all tags that are valid semvers, and attempt to process the package.json file in the root of each of those. This breaks down pretty mightily when that same metadata might be in the header of any number of files in the repo, and those files could have any name and be at any depth in the folder hierarchy (/src, /lib, /js, etc.). So not only do we not know which file to look inside, there's no way to restrict the repo to only have one manifest (which is a design feature for us).

I read isaacs comments on your issue in npm. I think one distinct difference (to his comment, not your request) is the likelihood that a jQuery plugin would be authored with a filename of index.js and be in the root. This seems quite reasonable for a something like an npm package, but I don't know that it is for a jQuery plugin. Partly because plugins so often are single files, and often thrown into a single folder, so people already given them unique names that support that out-of-the-box, without having to rename, or having to keep every plugin in its own folder. If we had a recommended standard for filenames, it would be jquery.pluginname.js. That would seem to work (as an alternative to index.js, as long as we're searching for a magically-named file) except that we don't know the plugin name until we find it in the package.json. Again, this is a difference from npm, and is a bit by-design. Rather than submit a plugin by specifying a plugin name AND a repo (or a plugin name AND a package.json) we just want to be pointed at that repo. And there's nothing that says that repo name will be useful in determining the exact name of the plugin (and thus, the name of the file that has the package.json in the header).

What I'd recommend is a build step to pull the json out of the file header and put it in a generated package.js in the root. So, much like minified files (for some) this would only be in the tag, not maintained otherwise in the repo, to avoid duplication.

[jrburke]

@rdworth said:

Yup, although to be pedantic, we'll match it to the plugin name (the name field in the package.json) which will be used to determine the url on plugins.jquery.com. But the filename of course would have other stuff in it, and is not actually required to be specified. Example:

filename: jquery.imageslider.js
object name: jquery.fn.imageSlider
plugin name: imageslider

Ideally, for the case above, the package name would be 'jquery.imageslider', and anything that depended on it would name the dependency 'jquery.imageslider'.

My main interest in this is to allow other tools besides the plugin site to install these files into projects, like perhaps being able to use npm or cpm, and I expect at least one other kind of tool like this. If the names match CommonJS/AMD module ID conventions, it makes it much easier/portable.

If that is not possible for some reason, at least making sure that 'jquery' is used for jQuery dependency, and 'backbone' for Backbone.

On the topic of package.json as a JS comment:

One of the main problems with this is discoverability.

My assumption was that there would only be one top-level .js file in the repo, and that would be the plugin. In that case, the file could be inspected for the package.json comment. Of course for larger projects that need a few files or have complex directories, an explicit package.json makes sense. So the tests for package.json info:

• if package.json use that
• else if only one .js file at the top level, look in there for package.json comment
• else error

[pupunzi]

I would suggest to introduce an optional "demo" URL and "documentation" URL fields on the package.json

[jzaefferer]

Along with npm and cpm, there's also bpm: https://github.com/bpm/bpm - might be good to get them onboard as well.

[tanepiper]

@jzaefferer I've mentioned this before, but there is also ender.js - http://ender.no.de/ supports the same package.json format and is specifically designed for client side lib building

[benpickles]

What about browser compatibility? With "HTML5" functionality I imagine there might be a lot of this: ie: ">=9".

[scottgonzalez]

We should definitely not encourage users to build plugins that don't work cross-browser.

[tanepiper]

@scottgonzalez @benpickles Definitely should not be encouraged, but maybe some kind of object that can contained tested-on browsers so if you do use it on IE6/7 it's a "Here be dragons" situation