What are Components?

Components borrow philosophy from Node and npm - write smaller modules that together form a larger system. Because of this we don't use large frameworks and instead use small modules. Essentially, Components are just packages. They have a version and they have dependencies.

a component may be javascript and css, fonts and images, only css, or only javascript

Further Reading

Read these to get a better understanding of Components.

• FAQ
• Writing better components

Building Components

Components by themselves don't work in the browser. You run component build to compile the component so that we can use it in the browser. This will create a build folder inside the component where the compiled JS and CSS is contained.

Installing Dependencies

Before you can build a component you need to install it's dependencies

component install

This will pull in all dependencies and place them in a components folder.

Structure

A component is just a folder with a component.json file and some scripts, styles, images etc. It encapsulates a single bit of functionality. This might be a widget, a dialog, an accordion, buttons, or a javascript library.

JavaScript

JavaScript in Components is written using the CommonJS style. What this means is that there is no global scope and instead you have access to require and exports. When the JavaScript is compiled it wraps the file in a function to enclose the scope and dynamically creates a require function.

For example:

var Dialog = require('dialog');

function CallbackDialog() {
   Dialog.apply(this, arguments);
}

module.exports = CallbackDialog;

This file requires the dialog component. This name is derived from the dependency in the component.json. The component.json file for this component would look like this:

{
   "name": "callback-dialog",
   "dependencies": {
      "nib-components/dialog": "0.0.1"
   },
   "scripts": ["index.js"]
}

When another component depends on our component, they will use require('callback-dialog') and be given the CallbackDialog function because that is what was exported.

This style is called CommonJS. It is a standard for creating a module system with JavaScript and is the same module system that Node uses. Component wraps this up and makes it usable in the browser.

When the JS is built to build/build.js, it look something like this:

(function(){

// require function logic is generated here

require.register('callback-dialog', function(require, exports, module){
 var Dialog = require('dialog');

  function CallbackDialog() {
    Dialog.apply(this, arguments);
  } 

  module.exports = CallbackDialog;
});

require.register('dialog', function(require, exports, module){
 // dialog code here
});

// Every other component will output here

})();

Examples

• Observable

This is purely JavaScript component so it's just code.

component.json

The manifest, the component.json file, looks like this.

{
  "name": "my-component",
  "scripts": ["index.js"],
  "dependencies": {
    "nib-components/dialog": "0.0.1"
  }
}

It's important to remember that every file in the component needs to be declared in the component.json. There are scripts, styles, templates, files and images.

The full spec is also available.