Spec

THIS PAGE IS DEPRECATED. THE SPECIFICATIONS HAVE MOVED TO https://github.com/component/spec/blob/master/component.json/specifications.md

Home of the component spec-ish. If you're new to components perhaps read this blog post. The following "spec" is very much in flux as we try things out and see what works best. Feel free to open up issues for any changes you would suggest. The motiviation behind this document is to encourage other communities (Ruby, Python, etc) to develop similar tools in their native language if desired.

WARNING: please do not edit this page without discussing changes.

component.json

Components MUST provide a "component.json" file to describe the component's functionality and contents. Component developers MUST explicitly state the relevant file(s) via scripts, styles and others. This makes it easy for consumers to work with packages and reduces I/O. Another added benefit of this is that component installation tools may skip tarballs and fetch these files directly if desired, which can drastically improve installation times. Below is an example of a tooltip component:

{
  "name": "tip",
  "repo": "component/tip",
  "description": "Tip component",
  "version": "0.0.1",
  "keywords": ["tooltip", "tip", "ui"],
  "dependencies": {
    "component/emitter": "*",
    "component/jquery": "*"
  },
  "scripts": ["index.js", "template.js"],
  "styles": ["tip.css"],
  "license": "MIT"
}

.name

The component MUST have a "name", this is what will be passed to require().

.repo

The component MUST have a "repo" property, this is registry end-point consisting of <username>/<project>, for example "visionmedia/page.js" or "component/dialog".

.description

The component SHOULD have a "description" property, this helps people find and understand your component.

.version

The component MUST include a version, unless used as a local component, allowing other scripts to depend on specific releases of the component.

.keywords

Keywords are used when searching for a component. A component SHOULD list a few keywords.

.main

It is recommended that you use "index.js" for the main component file, however if you use another filename, you MUST define a "main" field for that. A component MUST have only one "main" file specified, and it MUST still be listed in the "scripts" array.

.scripts

The scripts field explicitly specifies the JavaScript files that this component relies on. These MUST be regular JavaScript, not CoffeeScript, LiveScript or similar compiled languages. You may of course develop in these languages and compile to native JavaScript, however it is highly recommended that public components are written using JavaScript.

.styles

The styles field explicitly specifies the stylesheets for this component, and follow the same rules as scripts, compilers such as Stylus or SASS may be used to compile down to regular CSS, however it is not recommended. Keeping components small and focused also greatly reduces the need for such tools. Opinionated styling unless tightly integrated with the component SHOULD be left out. For example Calendar has very minimal structural styling only, while the Aurora Calendar theme provides more opinionated styles.

.images

The images field MUST be supported and fetched upon installation, this allows component build tools to rewrite stylesheet url()s in order to accomodate various file serving techniques.

.fonts

The fonts field MUST be supported and fetched upon installation, this allows component build tools to rewrite stylesheet url()s in order to accomodate various file serving techniques.

.files

In the future we will classify more file types, however for those which are not treated uniquely such as fonts may be placed in a files array to aid build and installation tools.

.dependencies

Runtime dependencies. For example:

{
  "dependencies": {
    "component/emitter": "*",
    "visionmedia/page.js": "1.3.0"
  }
}

.development

Development dependencies. For example:

{
  "development": {
    "component/assert": "*",
    "visionmedia/mocha": "*"
  }
}

.local

Local dependencies are already located on disk, these are not installed, but are however included in the builds, thus no versions need to be defined. Local components should be located in a directory specified within .paths.

{
  "local": ["my-emitter"]
}

.remotes

The "remotes" property MAY be supported to support additional component servers, where github is implied. When supported installation attempts MUST be made in the order defined by the array.

{
  "remotes": [
    "http://localhost:3000",
    "http://user:pass@private"
  ]
}

The remote "https://raw.github.com" is implied and automatically added to the end of the remotes array at all times. To increase performance if most of your components originate from GitHub it is recommended to add it as the first remote so that it is hit before the others:

{
  "remotes": [
    "https://raw.github.com",
    "http://localhost:3000",
    "http://user:pass@private"
  ]
}

.paths

The root component SHOULD be able to utilize an array of lookup paths, allowing users to separate local and remote components:

{
  "paths": ["my-components", "path/to/my-other-components"]
}

.templates

The templates array MUST provide the contents of each file as a require-able module. For example the following must provide the HTML string via require('user.html').

{
  "templates": ["user.html"]
}

.demo

Optional full url for a live demonstration of a component.

.license

The license string such as "MIT" may be used for search output and other reporting, developers SHOULD specify this field

Custom properties

Custom properties may of course be used to facilitate custom build steps. For example if you're a fan of CoffeeScript and you wish to skip manual compilation for custom app-specific components, you could simply add a property named coffee: ["foo.coffee"] and handle the translation in the build step. Custom properties SHOULD be namespaced to prevent future collisions.

Templates

Templates SHOULD be compiled down to regular JavaScript and added to the scripts array before publishing a release to Github. For example: Jade, Hogan and many other template engines allow templates to be compiled to a self-contained executable function; they do not require the entire library itself. When possible it is strongly suggested that you use raw HTML and intrinsic DOM manipulation for public components so that contributors feel comfortable. This is often easily possible, as components are focused, for example a tooltip or dialog has very little markup. Your private application may utilize custom properties to auto-compile templates as part of the build, public components must use pre-built templates.

Installation

Tools such as the JavaScript component(1) implementation allow consumers to install, search, and build components. These tools may vary from community to community, however they SHOULD:

• allow installation via <user>/<project> for example "component/tip"
• default installation to the ./components directory
• allow building of the component(s) for development
• allow searching components

The installation tool MUST install the component to a directory using the <user> / <project> combo, with the / replaced by a hypen -. For example $ component install visionmedia/page would install the files to ./components/visionmedia-page. The following snippet further illustrates this for a "popover" component:

$ ls -1 components
component-emitter
component-jquery
component-tip

Registry

Components are currently fetched from Github, however in the future we may allow for completely swapping out the registry, as well as multiple registry support. This means alternative registries MUST comply with the Github-style urls following:

• GET /:user/:project/master/:file to fetch files for *, otherwise the same as below
• GET /:user/:project/:version/:file to fetch a file's contents (GET /component/tip/0.0.1/component.json)

Building

TODO: detail...

For reference view the JavaScript builder implementation.

License

MIT