1.0.0.md

Component v1.0.0

Component has finally received the developer love it needed for a long time! The goals of this release are:

• add semantic versioning support
• fix many issues with component in general
• prune component(1) of options and features
• make creating components easier

Please note that component(1) is designed for building small, public components, as well as building apps that do not need a custom build process. If you need to use plugins for your builds, you should use the JS API instead. We don't want to bloat component(1) with options, commands, and features.

For more specific changes, please read the History.md.

What's New

Required Authentication

Actually you don't need an authentication for GitHub, but then you only get 60 API request per hour. With authenticated requests you get 5.000 per hour.

See GitHub API Documentation for more information.

Component tell you when your limit is running short via stdout. You can see an example at the remotes.js travis build. You get these information:

• your rate limit
• your remaining requests
• reset date, when you get more requests again

To authenticate, simply either use a .netrc file or use the appropriate environmental variables for each end point. These environmental variables are currently:

• GITHUB_USERNAME
• GITHUB_PASSWORD
• BITBUCKET_USERNAME
• BITBUCKET_PASSWORD

Instead of providing your password as plaintext you might be interested in using a token. You can create your token on this site personal access tokens.

.netrc example (location: ~/.netrc):

machine api.github.com
  login <token>
  password x-oauth-basic

Semantic Versioning

For a while, Component users were plagued by a lack of semantic versioning support. But fear no longer! Component now supports semver. This also means that Component supports multiple versions of a dependency in a single build and app. You'll notice that components are now installed as <user>/<repo>/<version> instead of <user>-<repo>.

Please use semver ranges in your public components. You'll notice when you component install <user>/<repo>, components will now be installed with a ^ if > v1.0.0 and ~ otherwise. Since we're dealing with frontend development, we want as few duplicates as possible.

But please, stop using *!

Pinning and Updating

Although semantic versioning is great, you still want to pin your app's dependencies to specific versions. Otherwise, a dependency might break your app and hunting the cause might be nontrivial. So Component has added a few commands to make pinning dependencies and updating them easier.

• component pin - pin all your dependencies that use semver ranges to a single version.
• component outdated - check whether any of your pinned dependencies are outdated.
• component update - update all your pinned dependencies to the latest version.
• component duplicates - list any duplicates of dependencies and their dependents

Note that these commands only update the component.json files. To actually install these new versions, run component install again.

Registry Crawler

Most package managers have a registry, but we've found that these registries are an extra source of pain. Instead, Component uses GitHub as a registry! For a while, we used a wiki to keep track of components, but this was a pain in the ass to update and maintain.

Now, we have a dedicated crawler that simply crawls a github user or organization for components! Instead of a publish step, all you have to do is component crawl <user>, and all of your components will essentially be "published". Users can now search for your component using component search or at http://component.github.io

ES6 Module Support

Component v1 now supports ES6 modules by default. Simply write an ES6 module with node-like module references, and your app should still work.

Note that CommonJS and ES6 modules are not completely compatible, ES6 modules aren't standardized yet, and ES6 to CommonJS transpilers are thus not yet stable. Thus, you may run into issues. Please let us know if you find any issues! The relevant repository is: http://github.com/component/builder-es6-module-to-cjs.

Smarter require()s

Not all the maintainers of the component organization use Component - many use npm and browserify. However, this has been a pain as components are generally named with npm's namespace in mind.

The solution now is to use require(<user>-<repo>) in your components, then publish the component to npm as <user>-<repo>. No more aliasing hackery will be required on the browserify and node side.

Watcher

Component now has a component build --watch option, allowing incremental builds. It uses sane under the hood, which seems to be one of the best JS watcher libraries currently published.

Linking

You may now link local components as version dependencies in your app using the component link ../path/to/folder command.

Glob Support

Many people complained about having to list every single file in a component.json manually. Now you can simply do "js": ["**/*.js"]! Keep in mind that this will slow down your build process, so only use globs when necessary.

Easier Local Components

Creating local components is now easier! For one, you can just use globs instead of listing every single file. But most of all, you don't have to name each local's component.json. Component will just use its containing folder's name.

Development Build

Component supports now locals, scripts and styles for the test environment via component build --dev, see example. If you use mocha as test runner you can setup your test.html like this:

<script src="build/build.js"></script>
<link href="build/build.css" type="text/css" rel="stylesheet">
<div id="mocha"></div>
<script>
    require('mocha'); // returns null, but window.mocha is available then
    require("./lib/my-component/test/browser.js"); // use canonical path
    mocha.run();
</script>

What's Removed

Custom Remotes

For now, component(1) only supports GitHub and Bitbucket as remotes. This is primarily because of semantic versioning support - we have to create an adapter for every remote. If you need to use a remote other than GitHub or Bitbucket, you should stick to v0.x for now.

Feel free to add more remotes!

Commands

Some commands have been removed as they were deemed unnecessary. These commands are:

• component create - has moved to https://github.com/component/create.js. It may be re-added at a later date after improvements are made.
• component convert - no longer necessary as Component now supports JSON and HTML strings.
• component wiki - the official "registry" has moved from the wiki to the crawler as stated above

component info and component changes were used to get info about a specific component. However, there were many issues with this, such as some components not having a changelog and others having a changelog name with different casing. Thus, it has been replaced with component open, which just opens the component's GitHub page. This is not bound to fail, and is overall more user-friendly.

component install --force

Force was terribly broken, and was mainly required due to the old installer's inability to handle bad installs. The new installer now handles failed installations correctly (only successful installations are actually saved).

If you need to remove or uninstall a component, you can run rm -rf components or rm -rf components/<user>/<repo>. A CLI utility to do those two simple commands wouldn't be very useful.

component build --use

Support for using plugins from component(1) has been removed. If you need to use a builder plugin, you should use the JS API instead.

What's Changed

component.json

The component.json specifications have changed over time. component validate will warn you of any changes. Generally, these changes are backwards compatible in that Component 1.0.0 can still handle them.

• .templates has been added, removing the necessity of component convert.
• .local has been renamed to .locals as it is an array.
• .repo has been renamed to .repository .
• .development is now a hash of development-only fields. In other words, its usage has changed to .development.dependencies.
• .remotes now handles an array of strings which refer to an remote implementation: 'github' and 'bitbucket', see spec

Breaking Changes

• Since Component supports semantic versioning, dependencies with * fetch the latest published tag now. The master branch will only be used if there are no tags available.
• The require implementation has changed. In versions < 1.0.0, you could do dynamic require: require(base + 'someFile'). This is not possible anymore, because component need to parse all require() calls at build time and resolve the paths. Only a string identifier is allowed in the require path.
• The canonical require path has changed. If you want to require locals which are not the first (boot) component, you need the canonical path. If you have main component like this, then the canonical path is ./client/boot. Non-main files of a local need to be required with the file name and the file extension, for instance: ./client/boot/helper.js. A use case for canonical paths is to require test files for the development environment (component build --dev), see example.

Massive Internal Changes

The internals of component(1) have also changed drastically. Be sure to understand the internal modules if you wish to use the more powerful JS API. Here's a list of all official Component respositories.