All about jQuery plugin manifest file

As it was described in our previous post “How to prepare your plugin for the new jQuery plugins site” you will need to add a manifest file if you want your plugin to appear on the new jQuery plugins site. In this post we will cover everything you need to know about the manifest file, how to format it and where to put it.

What is a jQuery plugin manifest file?

It is a JSON file (not JavaScript literal) that carries all necessary information about your plugin. Information like: plugin name, description, version, author, homepage, licenses, plugin dependencies, etc. The upcoming plugins.jquery.com site will use this data to populate its’ database and create an individual pages for each plugin.

Manifest file naming conventions

The manifest file’s name must be yourpluginname.jquery.json. For example, jTwitter plugins manifest file name would be named: jtwitter.jquery.json. Please be advised, at first the file name was planned to be package.json (following common.js conventions). However, after some discussions it was changed to *.jquery.json.

There is also a concept of suites. Suites are a way to namespace many plugins in a single repository (e.g. jQuery UI would name their fils: ui.tabs.jquery.json). Suites are created manually by jQuery team.

Naming restrictions

There are 3 restrictions while naming your manifest file:

• Your manifest file can not start with a suite name. For example, you can not name it ui.jtwitter.jquery.json, however you can name it ui.tabs.*.jquery.json;
• Your plugin name can not be one of these:
  • docs
  • index.php
  • wp-admin
  • tag
  • category
  • jquery
  For an up to date list, please see this file.
• Manifest file must contain your plugins name.

Manifest file must be placed in the root directory of your repository.

Manifest file contents

The manifest file specification is not final yet and some changes may be introduced. Please see an up to date specification here.

First, let’s see an example of the very minimal manifest file:

{
    "name": "jtwitter",
    "version": "0.1.2",
    "title": "jTwitter Plugin",
    "author": {
        "name": "Uzbekjon"
    },
    "licenses": [
        {
            "url": "http://example.com/license"
        }
    ],
    "dependencies": {
        "jquery": "1.4.2"
    }
}

This manifest file contains all 6 required fields: name, version, title, author, licenses and dependencies. This is the bare minimum info that must be in your manifest file.

There are also 8 more additional fields that will help users find and use your plugin:

• description
• keywords
• homepage
• docs
• demo
• download
• bugs
• maintainers

See more detailed description of each field here.

{
    "name": "jtwitter",
    "version": "0.1.2",
    "title": "jTwitter Plugin",
    "author": {
        "name": "Uzbekjon",
        "email": "uzbekjon@example.com",
        "url": "http://github.com/uzbekjon"
    },
    "licenses": [
        {
            "type": "MIT",
            "url": "https://github.com/jquery/jquery-color/raw/2.0.0-beta.1/MIT-LICENSE.txt"
        },
        {
            "type": "GPLv2",
            "url": "https://github.com/jquery/jquery-color/raw/2.0.0-beta.1/GPL-LICENSE.txt"
        }
    ],
    "dependencies": {
        "jquery": "1.4.2",
        "underscore": "~0.9"
    },
    "description": "jQuery plugin that helps you get any Twitter user's last N tweets without oAuth authorization or API keys.",
    "keywords": [
        "twitter",
        "tweets",
        "social"
    ],
    "homepage": "http://github.com/uzbekjon/jtwitter",
    "docs": "http://github.com/uzbekjon/jtwitter/wiki",
    "demo": "http://custom-drupal.com/jquery-demo/jtwitter/",
    "download": "http://github.com/uzbekjon/jtwitter/tarball",
    "bugs": "http://github.com/uzbekjon/jtwitter/issues",
    "maintainers": [
        {
            "name": "Uzbekjon",
            "email": "uzbekjon@example.com",
            "url": "http://github.com/uzbekjon"
        },
        {
            "name": "Joe Smith",
            "email": "joesmith@example.com",
            "url": "http://example.com"
        }
    ]
}

So this is the file that jQuery plugins site will fetch and parse to populate it’s database and create your plugin’s page on plugins.jquery.com/jtwitter. To keep jQuery plugins site update on your new releases you’ll need to set a “post-receive-hook” on GitHub as it was described in our previous post.

Caveats and notes

I would like to leave you with some notes and caveats:

• Manifest file content must be valid JSON and not JavaScript literal. This means that hash keys must be strings ("name": "X", not name: "X"), numbers can be only integers ("version": "1.2", not "version": 1.2), values can be string, integer, [], {}, true, false and null.
• You must create a tag in your repository that matches the version set in your manifest file. For example: I set version to 1.0.2repository tag named 1.0.2 or v1.0.2.
• If jQuery plugins site encounters a problem parsing your manifest file it will not notify you. It is recommended to check that your plugins page is updated correctly after you push a new release.
• You must specify minimal version of jquery as your dependency.
• Install grunt to automate most of the manual work of creating a jQuery plugin.