Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 169 lines (122 sloc) 5.396 kB
98a5bb9 @tj Initial commit
tj authored
1
2 # component
3
d06fab4 @tj docs
tj authored
4 Component package manager.
5
6 ## Installation
7
37b0511 @tj docs
tj authored
8 $ npm install -g component
d06fab4 @tj docs
tj authored
9
10 ## Installing packages
11
12 To install one or more packages, simply pass their github
13 repo names as arguments to `component install`. Dependencies
14 are resolved and the component contents are downloaded into
4c0b62e @tj docs
tj authored
15 `./components` by default. View `component help install` for details.
d06fab4 @tj docs
tj authored
16
17 ```
18 $ component install component/tip
19
20 install : component/tip@master
21 dep : component/emitter@master
22 install : component/emitter@master
23 dep : component/jquery@master
24 install : component/jquery@master
25 fetch : component/tip:index.js
26 fetch : component/tip:tip.css
27 fetch : component/tip:tip.html
28 fetch : component/emitter:index.js
29 fetch : component/jquery:index.js
30 complete : component/emitter
31 complete : component/jquery
32 complete : component/tip
33 ```
34
35 ## Usage
36
37 Via `--help`:
38
39 ```
7a29005 @tj docs
tj authored
40
d06fab4 @tj docs
tj authored
41 Usage: component <command> [options]
42
43 Options:
44
45 -h, --help output usage information
46 -V, --version output the version number
47
48 Commands:
49
914940b @tj docs
tj authored
50 install <name ...> install one or more components
51 create <dir> create a component skeleton
52 search [query] search with the given query
53 convert <file ...> convert html files to js modules
54 info [prop] output json component information
55 open <name> open component github repo
56 ls list installed components
7a29005 @tj docs
tj authored
57
d06fab4 @tj docs
tj authored
58 ```
98a5bb9 @tj Initial commit
tj authored
59
32f16ca @tj docs
tj authored
60 ## Features
61
4c0b62e @tj docs
tj authored
62 - no registry publishing or account required, uses github repositories
6b2b654 @tj docs
tj authored
63 - pretty fast (~2x faster than uncached npm at the time of comparison)
b33beb6 @tj docs
tj authored
64 - extensible sub-commands via `component-YOURCOMMAND` git-style
6b2b654 @tj docs
tj authored
65 - component skeleton creation command
4c0b62e @tj docs
tj authored
66 - installs dependencies from the command-line or ./component.json
32f16ca @tj docs
tj authored
67
4c0b62e @tj docs
tj authored
68 ## Using Github as a registry
0724267 @tj docs
tj authored
69
70 By using GitHub as the registry, `component(1)` is automatically
71 available to you without further explicit knowledge or work
72 creating a registry account etc.
73
74 A nice side-effect of this namespaced world is that dependencies
75 are explicit and self-documenting. No longer do you need to query
76 the registry for a "repo" property that may not exist, it's simply
4c0b62e @tj docs
tj authored
77 built in to the package name, for example ["visionmedia/page.js"](https://github.com/visionmedia/page.js) rather
efebc26 @tj docs
tj authored
78 than the unclear "page".
0724267 @tj docs
tj authored
79
7c0b0a2 @tj docs
tj authored
80 ## Creating a component
81
82 The `component-create(1)` command can create a component
83 project skeleton for you by filling out the prompts. Once
84 this repo is published to Github, you're all done!
85
86 ```
2811ddd @tj update docs
tj authored
87 name: popover
88 description: Popover UI component
7c0b0a2 @tj docs
tj authored
89 does this component have js? yes
90 does this component have css? yes
91 does this component have html? yes
92
2811ddd @tj update docs
tj authored
93 create : popover
94 create : popover/index.js
95 create : popover/template.html
96 create : popover/popover.css
97 create : popover/Makefile
98 create : popover/Readme.md
99 create : popover/.gitignore
100 create : popover/component.json
7c0b0a2 @tj docs
tj authored
101
102 ```
103
67002d6 @tj docs
tj authored
104 A `Makefile` is created for you in order to create a build of the component,
105 complete with installed dependencies simply execute `make`.
106
8947deb @tj docs
tj authored
107 ## Templates
108
109 Because `component(1)` has no notion of a "template", even simple HTML files
110 should be converted to a `require()`-able module. It is recommended that public
03671fe @tj docs
tj authored
111 components shared within the community use regular HTML templates, and regular
8947deb @tj docs
tj authored
112 CSS stylesheets to maximize contributions, however if you wish to use alternate
113 technologies just make sure to compile them before publishing them to Github.
114
03671fe @tj docs
tj authored
115 For the recommended use-case of regular HTML, the `component-convert(1)` command
116 will translate a regular HTML file to its `require()`-able JavaScript counterpart.
117
8947deb @tj docs
tj authored
118 ## Developing component(1) sub-commands
460e6fe @tj add some dev docs
tj authored
119
120 `component(1)` and sub-commands are structured much like `git(1)`,
121 in that sub-commands are simply separate executables. For example
122 `$ component info pkg` and `$ component-info pkg` are equivalent.
123
124 Because of this you'll likely want `PATH="./bin:$PATH"` in your
125 profile or session while developing component, otherwise `./bin/component`
126 will have a hard time finding the sub-commands.
127
771c084 @tj docs
tj authored
128 ## Running tests
129
130 Make sure dependencies are installed:
131
132 ```
133 $ npm install
134 ```
135
136 Then run:
137
138 ```
139 $ make test
140 ```
141
aa02f3f @tj links
tj authored
142 ## Links
143
144 - [Mailing List](https://groups.google.com/group/componentjs)
145
98a5bb9 @tj Initial commit
tj authored
146 ## License
147
148 (The MIT License)
149
150 Copyright (c) 2012 TJ Holowaychuk &lt;tj@vision-media.ca&gt;
151
152 Permission is hereby granted, free of charge, to any person obtaining
153 a copy of this software and associated documentation files (the
154 'Software'), to deal in the Software without restriction, including
155 without limitation the rights to use, copy, modify, merge, publish,
156 distribute, sublicense, and/or sell copies of the Software, and to
157 permit persons to whom the Software is furnished to do so, subject to
158 the following conditions:
159
160 The above copyright notice and this permission notice shall be
161 included in all copies or substantial portions of the Software.
162
163 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
164 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
165 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
166 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
167 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
168 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
169 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.