Introduction to Component

by Toby Ho on 1/23/2014

Hello, and welcome to the first post of Small.js! This post will cover the basics of Component. Component is a frontend Javascript package manager developed by the prolific Tj Holowaychuk. It embodies the philosophy of small modules and is designed to manage assets as well as Javascript. Currently, there exists over 1600 "components". Although there are more popular JS package managers than Component, I chose to cover it first because I love an underdog.

Update: There is a screencast for this post as well for those who prefer watching over reading.

Installing

Before getting started, you'll need to install Node - which is a prerequisite of Component. Installing Node is as simple as clicking on "Download" on the Node website, and then running the installer. To verify you have successfully installed Node, run node from the command line and see that the executable exists.

Next, install Component using npm (sudo is required on some platforms)

npm install component -g

Component is installed! If you type component you should see its usage info

Usage: component [options]

Options:

-h, --help     output usage information
-V, --version  output the version number

Commands:

install [name ...]      install one or more components
create [dir]            create a component skeleton
search [query]          search with the given query
convert <file ...>      convert html files to js modules
info <name> [prop]      output json component information
changes <name>          output changelog contents
wiki                    open the components list wiki page
build                   build the component
ls                      list installed components

Component has several commands. For this tutorial we'll cover only install, and build.

Create a Project

To create an application which uses components, all that's required is that the root directory of the project contains a valid component.json file. So let's set these up

mkdir hello_component
cd hello_component

Next, create a file component.json with the following content

{
  "name": "hello_component"
}

Congratulations! Now, we can start installing components.

Installing a Component

For demostration purposes, we'll install the dialog component:

component install component/dialog

component/dialog is simply an alias to the Github url: https://github.com/component/dialog. All components are identified by their Github URL. Once you've installed dialog, you'll notice that a components directory was created, and that it contains a component-dialog subdirectory plus a bunch of others

$ ls components
component-classes          component-indexof
component-css              component-matches-selector
component-delegate         component-overlay
component-dialog           component-query
component-dom              component-sort
component-domify           component-type
component-emitter          component-value
component-event

All the other components that were installed were installed because they are either a direct dependency or a transitive dependency of component/dialog.

Also note that your component.json has been doctored - a "dependencies" field has been added containing component/dialog

"dependencies": {
  "component/dialog": "*"
}

keeping the dependencies in component.json allows you to easily get back all the components you need even if you've deleted the components directory, via the command: component install.

Next, to test out the dialog, we need to build it.

Build It

In order to consume any components, you will need build them - which combines all of the components you've currently installed into a .js file and a .css file. Why CSS? Because components can contain CSS - dialog does.

component build

Now you should see a build directory which contains a build.js as well as a build.css.

Test It

The only other thing we need to do now is to create a test page that links these files

<!doctype html>
<html>
<head>
  <title>Hello Dialog</title>
  <link href="build/build.css" rel="stylesheet">
  <script src="build/build.js"></script>
</head>
<body>
  <h1>Hello Dialog</h1>
</body>
</html>

Sweet! Open it up in your browser, but nothing happens. Oops, we still need to write some Javascript. First let's bring in the dialog component using the require function

var Dialog = require('dialog');

Then make an openDialog function which calls the dialog component API

function openDialog(){
  var dialog = new Dialog('Hello World', 'Welcome human!')
    .closable() // this adds an `x` button on the top right
    .modal()    // makes it a modal dialog

  dialog.show()
}

To activate this function, put a button on a page, and just for now, use an onclick attribute

<button id="button" onclick="openDialog()">Open</button>

Refresh the page, click the button you should see a modal dialog!

Dialog Screenshot

Full Source

Do Some DOM

Using the onclick attribute is ok for a quick toy example, but would be unsanitary for a real app, so let's rewrite that in a cleaner way. jQuery time, right? Not so fast! In the land of Component, instead of jQuery, we can use the much more light-weight dom component

component install component/dom

Check your component.json and make sure it contains "component/dom" as a dependency. There's currently a bug in Component that causes a dependency not to get added if it already exists in the components directory. If it's not there, just add it manually - so we should have

"dependencies": {
    "component/dialog": "*",
    "component/dom": "*"
}

rebuild the components

component build

Now, we can do this

var dom = require('dom');
...
dom('#button').on('click', openDialog);

Same result, but cleaner code! Very jQuery-like, no?

Full Source

Finding Components

How to know what components exist? You can peruse the components wiki page - which in fact is the official registry for components. Alternatively you can also use the component search command, for example

component search dom

to search for all dom-related components.

Homework

What's that? Ohhhh yes! Of course there's homework! Don't look so surprised. What? Yes, you have to do it. If you don't, everything you've learned thus far will be lost.

Your homework is to browse the registry and pick one that looks interesting to you. Then, you are going to install it and incorporate it into your code. Good luck!

Screencast

Component Part 1 from Toby Ho on Vimeo.