forked from bower/bower
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Signed-off-by: Chris Aniszczyk <zx@twitter.com>
- Loading branch information
0 parents
commit c220329
Showing
64 changed files
with
2,102 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
node_modules | ||
components | ||
.DS_Store |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
language: node_js | ||
node_js: | ||
- 0.8 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
Copyright (c) 2012 Twitter and other contributors | ||
|
||
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: | ||
|
||
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. | ||
|
||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
test: | ||
./node_modules/.bin/mocha -R spec -t 10000 | ||
|
||
.PHONY: test |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,208 @@ | ||
BOWER [![Build Status](https://secure.travis-ci.org/twitter/bower.png)](http://travis-ci.org/twitter/bower) | ||
===== | ||
|
||
### Introduction | ||
|
||
Bower is a package manager for the web. Bower lets you easily install assets such as images, CSS and JavaScript, and manages dependencies for you. | ||
|
||
For example, to install a package, run: | ||
|
||
bower install jquery | ||
|
||
This will download jQuery to `./components/jquery`. That's it. The idea is that Bower does package management and package management only. | ||
|
||
### Installing Bower | ||
|
||
Bower is installed using [Node](http://nodejs.org/) and [npm](http://npmjs.org/) (oh my, how meta). | ||
|
||
npm install bower -g | ||
|
||
### Usage | ||
|
||
Your best friend at this stage is probably `bower --help`. | ||
|
||
To install a package: | ||
|
||
bower install jquery | ||
bower install git://github.com/maccman/package-jquery.git | ||
bower install http://code.jquery.com/jquery-1.7.2.js | ||
bower install ./repos/jquery | ||
|
||
As you can see, packages can be installed by name, Git endpoint, URL or local path. | ||
|
||
To update a package, reference it by name: | ||
|
||
bower update jquery-ui | ||
|
||
To list installed packages: | ||
|
||
bower list | ||
|
||
To search for packages: | ||
|
||
bower search [name] | ||
|
||
To list all the available packages, just call `bower search` without specifying a name. | ||
|
||
### Defining a package | ||
|
||
You can create a `component.json` file in your project's root, specifying all of its dependencies. This is similar to Node's `package.json`, or Ruby's `Gemfile`, and is useful for locking down a project dependencies. | ||
|
||
```json | ||
{ | ||
"name": "myProject", | ||
"version": "1.0.0", | ||
"main": "./path/to/main.css" | ||
"dependencies": { | ||
"jquery": "~1.7.2" | ||
} | ||
} | ||
``` | ||
|
||
Put this under your project's root, listing all of your dependencies. When you run `bower install`, Bower will read this `component.json` file, resolve all the relevant dependencies and install them. | ||
|
||
For now, `name`, `version`, `main`, and `dependencies` are the only properties that are used by Bower. If you have several files you're distributing as part of your package, pass an array to `main` like this: | ||
|
||
```json | ||
{ | ||
"name": "myProject", | ||
"version": "1.0.0", | ||
"main": ["./path/to/app.css", "./path/to/app.js", "./path/to/sprite.img"] | ||
"dependencies": { | ||
"jquery": "~1.7.2" | ||
} | ||
} | ||
``` | ||
|
||
### Installing dependencies | ||
|
||
Dependencies are installed locally via the `bower install` command. First they’re resolved to find conflicts. Then they’re downloaded and unpacked in a local sub directory called `./components`, for example: | ||
|
||
|
||
``` | ||
/component.json | ||
/components/jquery/index.js | ||
/components/jquery/component.json | ||
``` | ||
|
||
You can also install packages one at a time `bower install git://my/git/thing` | ||
|
||
There are no system wide dependencies, no dependencies are shared between different apps, and the dependency tree is flat. | ||
|
||
### Deploying | ||
|
||
The easiest approach is to use bower statically, just reference the packages manually from a script tag: | ||
|
||
<script src="components/jquery/index.js"></script> | ||
|
||
For more complex projects, you'll probably want to concatenate your scripts. Bower is just a package manager, but there are lots of awesome libraries out there to help you do this, such as [Sprockets](https://github.com/sstephenson/sprockets) and [RequireJS](http://requirejs.org/). | ||
|
||
For example, to use Sprockets: | ||
|
||
```ruby | ||
environment = Sprockets::Environment.new | ||
environment.append_path 'components' | ||
environment.append_path 'public' | ||
run environment | ||
``` | ||
|
||
### Package Consumption | ||
|
||
Bower also makes available a source mapping – this can be used by build tools to easily consume bower components. | ||
|
||
If you pass the option `--map` to bower's `list` command it will generate a json with dependency objects. Alternatively, you can pass the `--paths` flag to the `list` command to get a simple path to name mapping: | ||
|
||
```json | ||
{ | ||
"backbone": "components/backbone/index.js", | ||
"jquery": "components/jquery/index.js", | ||
"underscore": "components/underscore/index.js" | ||
} | ||
``` | ||
|
||
### Authoring packages | ||
|
||
To register a new package, it's as simple as specifying a `component.json`, pushing the package to a Git endpoint, say GitHub, and running: | ||
|
||
bower register myawesomepackagename git://github.com/maccmans/face | ||
|
||
There's no authentication or user management. It's on a first come, first served basis. Think of it like a URL shortener. Now anyone can run `bower install myawesomepackagename`, and get your library installed. | ||
|
||
### Philosophy | ||
|
||
Currently, people are managing dependencies, such as JavaScript libraries, manually. This sucks, and we want to change it. | ||
|
||
In a nutshell, Bower is a generic tool which will resolve dependencies and lock packages down to a version. It runs over Git, and is package-agnostic. A package may contain JavaScript, CSS, images, etc., and doesn't rely on any particular transport (AMD, CommonJS, etc). | ||
|
||
Bower then makes available a simple programatic api which exposes the package dependency model, so that existing build tools (like Sprockets, LoadBuilder, curls.js, Ender, etc.) can consume it and build files accordingly. | ||
|
||
|
||
### FAQ | ||
|
||
**What distinguishes Bower from Jam, Volo or Ender? What does it do better?** | ||
|
||
Bower is a lower level component then Jam, Volo, or Ender. These managers could consume bower as a dependency. | ||
|
||
Bower's aim is simply to install git paths, resolve dependencies from a component.json, check versions, and then provide an api which reports on these things. Nothing more. This is a major diversion from past attempts at browser package management. | ||
|
||
Bower is working under the assumption that there is a single, common problem in frontend application development: dependency resolution. Past attempts (Jam, Volo, Ender) try to tackle this problem in such a way that they actually end up alienating and further segregating the javascript community around transports (sprockets, commonjs, requirejs, regular script tags). | ||
|
||
Bower offers a generic, unopionated solution to the problem of package management, while exposing an api that can be consumed by a more opinionated build stack. | ||
|
||
**Volo is an arguably more established project and works with the GitHub search API. Will it take long for Bower to contain a decent number of packages?** | ||
|
||
Bower (being a git powered package manager) should, in theory, be capable of consuming most every package that Volo does, with the additional benefit of supporting internal networks and other git repositories not hosted on github. | ||
|
||
**We recently saw what happened when the NPM registry went down. Is a central point of failure possible for Bower and if so, do you have redundancy planned?** | ||
|
||
There's no redundancy planned at the moment, as bower just installs git urls. It's up to the url provider to establish redundancy. | ||
|
||
**Isn't having a package.json file going to conflict with my npm's package.json? Will this be a problem?** | ||
|
||
Don't use a package.json – user component.json. | ||
|
||
**Bower is an open-source Twitter project. How well can we expect it to be maintained in the future?** | ||
|
||
Twitter is in the process of migrating it's frontend architecture onto bower, so it's fairly safe to say it will be maintained and invested in going forward. | ||
|
||
|
||
### Contact | ||
|
||
Have a question? Ask on our mailing list! | ||
|
||
twitter-bower@googlegroups.com | ||
|
||
http://groups.google.com/group/twitter-bower | ||
|
||
### Authors | ||
|
||
+ [@fat](http://github.com/fat) | ||
+ [@maccman](http://github.com/maccman) | ||
|
||
Thanks for assistance and contributions: | ||
|
||
+ [@addyosmani](http://github.com/addyosmani) | ||
+ [@angus-c](http://github.com/angus-c) | ||
+ [@borismus](http://github.com/borismus) | ||
+ [@chriseppstein](http://github.com/chriseppstein) | ||
+ [@danwrong](http://github.com/danwrong) | ||
+ [@desandro](http://github.com/desandro) | ||
+ [@isaacs](http://github.com/isaacs) | ||
+ [@josh](http://github.com/josh) | ||
+ [@jrburke](http://github.com/jrburke) | ||
+ [@mklabs](http://github.com/mklabs) | ||
+ [@paulirish](http://github.com/paulirish) | ||
+ [@rvagg](http://github.com/rvagg) | ||
+ [@sindresorhus](http://github.com/sindresorhus) | ||
+ [@SlexAxton](http://github.com/SlexAxton) | ||
+ [@sstephenson](http://github.com/sstephenson) | ||
+ [@tomdale](http://github.com/tomdale) | ||
+ [@visionmedia](http://github.com/visionmedia) | ||
+ [@wagenet](http://github.com/wagenet) | ||
+ [@wycats](http://github.com/wycats) | ||
|
||
## License | ||
|
||
Copyright 2012 Twitter, Inc. | ||
|
||
Licensed under the MIT License |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,40 @@ | ||
#!/usr/bin/env node | ||
|
||
var semver = require('semver'); | ||
var nopt = require('nopt'); | ||
var path = require('path'); | ||
var pkg = require(path.join(__dirname, '..', 'package.json')); | ||
|
||
var template = require('../lib/util/template'); | ||
var bower = require('../lib'); | ||
|
||
var command; | ||
var options; | ||
var shorthand; | ||
var input = process.argv; | ||
var cmdList = Object.keys(bower.commands); | ||
var nodeVer = process.version; | ||
var reqVer = pkg.engines.node; | ||
|
||
process.title = 'bower'; | ||
|
||
if (reqVer && !semver.satisfies(nodeVer, reqVer)) { | ||
throw new Error('Required: node ' + reqVer); | ||
} | ||
|
||
shorthand = { 'v': ['--version'] }; | ||
options = { version: Boolean }; | ||
options = nopt(options, shorthand, process.argv); | ||
|
||
bower.version = pkg.version; | ||
|
||
if (options.version) return console.log(bower.version); | ||
if (~cmdList.indexOf(command = options.argv.remain && options.argv.remain.shift())) bower.command = command; | ||
|
||
bower.commands[bower.command || 'help'].line(input) | ||
.on('data', function (data) { data && console.log(data); }) | ||
.on('end', function (data) { data && console.log(data); }) | ||
.on('error', function (err) { | ||
if (options.verbose) throw err; | ||
else template('error', { message: err.message }).on('data', function (d) { console.log (d); }); | ||
}) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,35 @@ | ||
// ========================================== | ||
// BOWER: Help API | ||
// ========================================== | ||
// Copyright 2012 Twitter, Inc | ||
// Licensed under The MIT License | ||
// http://opensource.org/licenses/MIT | ||
// ========================================== | ||
|
||
var events = require('events'); | ||
var hogan = require('hogan.js'); | ||
var nopt = require('nopt'); | ||
var path = require('path'); | ||
var fs = require('fs'); | ||
var _ = require('underscore'); | ||
|
||
var template = require('../util/template'); | ||
var config = require('../core/config'); | ||
|
||
module.exports = function (name) { | ||
var context = {}; | ||
var emitter = new events.EventEmitter; | ||
var commands = require('../commands'); | ||
var templateName = name ? 'help-' + name : 'help'; | ||
|
||
if (!name) context = { commands: Object.keys(commands).join(', ') }; | ||
_.extend(context, config) | ||
template(templateName, context).on('data', emitter.emit.bind(emitter, 'end')); | ||
return emitter; | ||
} | ||
|
||
module.exports.line = function (argv) { | ||
var options = nopt({}, {}, argv); | ||
var paths = options.argv.remain.slice(1); | ||
return module.exports(paths[0]); | ||
}; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,20 @@ | ||
// ========================================== | ||
// BOWER: Public Commands List | ||
// ========================================== | ||
// Copyright 2012 Twitter, Inc | ||
// Licensed under The MIT License | ||
// http://opensource.org/licenses/MIT | ||
// ========================================== | ||
|
||
module.exports = { | ||
'help': require('./help'), | ||
'install': require('./install'), | ||
'list': require('./list'), | ||
'ls': require('./list'), | ||
'uninstall': require('./uninstall'), | ||
'update': require('./update'), | ||
'lookup': require('./lookup'), | ||
'info': require('./info'), | ||
'register': require('./register'), | ||
'search': require('./search') | ||
}; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,44 @@ | ||
// ========================================== | ||
// BOWER: Lookup API | ||
// ========================================== | ||
// Copyright 2012 Twitter, Inc | ||
// Licensed under The MIT License | ||
// http://opensource.org/licenses/MIT | ||
// ========================================== | ||
|
||
var Emitter = require('events').EventEmitter; | ||
var nopt = require('nopt'); | ||
|
||
var template = require('../util/template'); | ||
var source = require('../core/source'); | ||
var help = require('./help'); | ||
|
||
var optionTypes = { help: Boolean }; | ||
var shorthand = { 'h': ['--help'] }; | ||
|
||
module.exports = function (name) { | ||
var emitter = new Emitter; | ||
|
||
name && source.info(name, function (err, result) { | ||
if (err) return emitter.emit('error', err); | ||
emitter.emit('end', result); | ||
}); | ||
|
||
return emitter; | ||
}; | ||
|
||
module.exports.line = function (argv) { | ||
var emitter = new Emitter; | ||
var options = nopt(optionTypes, shorthand, argv); | ||
var names = options.argv.remain.slice(1); | ||
|
||
if (options.help || !names.length) return help('info'); | ||
|
||
module.exports(names[0]) | ||
.on('error', emitter.emit.bind(emitter, 'error')) | ||
.on('end' , function (data) { | ||
template('info', data).on('data', emitter.emit.bind(emitter, 'end')); | ||
}); | ||
|
||
return emitter; | ||
}; |
Oops, something went wrong.