Running Basic Web Component demos

The components in the Basic Web Components are set up for distribution via the Bower package manager, which presents some limitations. Specifically, it is hard to organize files so that the component repository can be used in both of the following ways:

1. As a component installed with Bower. When a component is installed with Bower, the contents of the component repo generally end up inside a folder called bower_components (or, often, just components). This means the component, the component demo, and any other auxiliary imports all expect to find the component's dependencies in peer folders. If a component called basic-list-box has a dependency on another component called basic-element, it expects to find that dependency at the peer location "../basic-element/basic-element.html".

2. As a component repository cloned directly with git. This is often a quick way to get a component's source on to your machine, e.g., so that you can try out a component and confirm it does what you want.

For now, the project repositories are optimized for scenario #1 (installation with Bower), since that's the most common way people will pick up these components.

This means that cloning a Basic Web Component repository and running bower install inside the top folder will likely not give you what you want. You'll end up with the component's dependencies installed inside a new bower_components subfolder. The component source will not be expecting the dependencies to end up there, so the demo will not work.

Creating a minimal project that includes a component

If you just want to try out a component like basic-list-box, the simplest way may to create a trivial project that includes that component:

1. Create a new folder.
2. Copy the following into a file called bower.json:

{
  "name": "test",
  "dependencies": {
    "basic-framed-content": "basic-web-components/basic-framed-content#master",
    "basic-list-box": "basic-web-components/basic-list-box#master"
  }
}

The first dependency is basic-framed-content, a component used in many of the Basic Web Component demos so that those demos can be shown inline on Component Kitchen.

3. Replace basic-list-box in the bower.json with the name of the component you want to try.
4. Run bower install. This will install the component and its dependencies.
5. You can find the demo file for the component in question inside .../bower_components/basic-list-box/index.html. (Replace basic-list-box with the name of the component you're trying.)
6. Use your browser to open that index.html file.