Skip to content

Latest commit

 

History

History
235 lines (165 loc) · 7.2 KB

specifications.md

File metadata and controls

235 lines (165 loc) · 7.2 KB
Raw

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",
  "repository": "component/tip",
  "description": "Tip component",
  "version": "0.0.1",
  "keywords": ["tooltip", "tip", "ui"],
  "dependencies": {
    "component/emitter": "*",
    "component/jquery": "*"
  },
  "templates" : ["template.html"],
  "scripts": ["index.js"],
  "styles": ["tip.css"],
  "license": "MIT"
}

.private

A boolean specifying whether the component is private, defaulting to false. A component is considered either private or public. A private component has different restrictions than public components.

.name

A public component MUST have a "name". This is what will be passed to require().

A local component is referenced by its container folder's name. A local component should either have no name or a name matching the containing folder's.

The name (or directory) MUST only consist of lowercase letters, numbers, dashes, and underscores. It must match the regular expression /^[0-9a-z-_]+$/.

.repository

The public component MUST have a "repository" 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 public component MUST include a version, allowing other scripts to depend on specific releases of the component.

local components do not need a version.

.keywords

Keywords are used when searching for a component. A public 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 scripts for this component. For public components, these must be regular JavaScript files. For private components, these should be regular Javascript files.

.styles

The styles field explicitly specifies the stylesheets for this component. For public components, these must be regular CSS files. For private components, these should be regular CSS files.

.json

The json field explicitly specifies the JSON files for this component. Each file must be valid JSON.

.images

The images field MUST be supported and fetched upon installation, this allows component build tools to rewrite stylesheet url()s in order to accommodate 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 accommodate 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"
  }
}

Each dependency must be defined in the following form:

"<user>/<repo>": "* | <git reference> | <semver range>"

A * wildcard dependency will try the following:

  1. Use a version already included in the build
  2. Use the highest semantic version tag
  3. Use the the main branch, usually master

Each reference can be:

  • a git reference including:

    • <tag>
    • <branch> such as master or gh-pages
    • <commit> sha

The public component should have semantic versioned dependencies.

.locals

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.

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

.remotes

The public component must not contain any 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.

If you don't provide any remotes, no property or an empty array, component use these defaults:

{
  "remotes": [
    "github",
    "bitbucket"
  ]
}

If most of your components originate from Bitbucket, you should provide a remotes array with 'bitbucket' as the first element. This will increase the performance. For more information checkout the remote.js repository.

.paths

The public component must not contain any 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'). If you're using component-build the files will be converted automatically using the string plugin of builder2.

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

.development

component.json properties valid only during development. For example:

{
  "development": {
    "dependencies": {
      "component/assert": "*",
      "visionmedia/mocha": "*"
    },
    "locals": [
      "my-debug"
    ],
    "scripts": [
      "test.js"
    ],
    "styles": [
      "test.css"
    ]
  }
}

.license

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

Glob Support

Properties may use globs and globstars to list files only when the order of files is insignificant.

File paths

Properties for file paths in the component.json like the scripts property MUST be written without any leading ./ for relative paths. Otherwise the build output will be broken.

Custom properties

Custom properties may of course be used to facilitate custom build steps and is, in fact, encouraged. 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.