Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 271 lines (199 sloc) 9.154 kB
8078059 @tj add logo to readme
tj authored
1 ![web component logo](http://i49.tinypic.com/e7nj9v.png)
2
3 Component package manager for building a better web.
d06fab4 @tj docs
tj authored
4
5 ## Installation
6
21f2c65 @tj add oneliner OSX install with node binary
tj authored
7 With [node](http://nodejs.org) previously installed:
8
37b0511 @tj docs
tj authored
9 $ npm install -g component
77d8a3b @tj links
tj authored
10
21f2c65 @tj add oneliner OSX install with node binary
tj authored
11 With node binary on OSX:
77d8a3b @tj links
tj authored
12
21f2c65 @tj add oneliner OSX install with node binary
tj authored
13 $ (cd /usr/local && \
14 curl -L# http://nodejs.org/dist/v0.8.15/node-v0.8.15-darwin-x86.tar.gz \
15 | tar -zx --strip 1) \
16 && npm install -g component \
17 && printf "installed component(1) %s\n" $(component --version)
18
d06fab4 @tj docs
tj authored
19
910d0f7 @timoxley Present the why & what before the how in readme.
timoxley authored
20 ## Features
21
22 - write modular commonjs components
23 - write components that include their own styles, images, scripts, or any combo
24 - no registry publishing or account required, uses github repositories
25 - extensible sub-commands via `component-YOURCOMMAND` git-style
26 - component skeleton creation command
27 - installs dependencies from the command-line or ./component.json
28 - avoid name squatting through github's naming conventions
29 - build your components with `--standalone` to share them with non-component(1) users
6c413d8 @tj docs
tj authored
30 - discovery of useful packages is simple with a robust search
910d0f7 @timoxley Present the why & what before the how in readme.
timoxley authored
31 - view documentation from the command line
32 - simple private registry set up (all you need is a file server)
9069e4c @tj docs
tj authored
33 - very fast installs (50 components in ~4.5s)
825ae61 @tj add new awesome performance docs
tj authored
34 - very fast search (~300ms)
910d0f7 @timoxley Present the why & what before the how in readme.
timoxley authored
35
77d8a3b @tj links
tj authored
36 ## Extensions
37
38 - [component-graph(1)] dependency graphs for component projects
39
910d0f7 @timoxley Present the why & what before the how in readme.
timoxley authored
40 ## Links
41
42 - [List](https://github.com/component/component/wiki/Components) of all available components
43 - [Wiki](https://github.com/component/component/wiki)
44 - [Mailing List](https://groups.google.com/group/componentjs)
a9f3bad @tj add g+ community link
tj authored
45 - [Google+ Community](https://plus.google.com/u/0/communities/109771441994395167277)
910d0f7 @timoxley Present the why & what before the how in readme.
timoxley authored
46 - component ["spec"](https://github.com/component/component/wiki/Spec)
47 - join `#components` on freenode
48 - follow [@component_js](http://twitter.com/component_js) on twitter
49 - [Building better components](https://github.com/component/component/wiki/Building-better-components) tips
50 - [F.A.Q](https://github.com/component/component/wiki/F.A.Q)
51
52 ## Screencasts
53
e5ee9bc @timoxley typo
timoxley authored
54 - [Creating web components](https://vimeo.com/53730178)
910d0f7 @timoxley Present the why & what before the how in readme.
timoxley authored
55 - [App integration introduction](https://vimeo.com/48054442)
56
77d8a3b @tj links
tj authored
57 ## Articles
b88b644 @tj docs
tj authored
58
59 - building a [date picker component](http://tjholowaychuk.com/post/37832588021/building-a-date-picker-component)
60 - original [component blog post](http://tjholowaychuk.com/post/27984551477/components)
61
910d0f7 @timoxley Present the why & what before the how in readme.
timoxley authored
62 ## Usage
63
64 Via `--help`:
65
66 ```
67
68 Usage: component <command> [options]
69
70 Options:
71
72 -h, --help output usage information
73 -V, --version output the version number
74
75 Commands:
76
77 install [name ...] install one or more components
78 create [dir] create a component skeleton
79 search [query] search with the given query
80 convert <file ...> convert html files to js modules
81 info <name> [prop] output json component information
82 changes <name> output changelog contents
83 docs <name> output readme contents
84 wiki open the components list wiki page
85 build build the component
86 ls list installed components
87
88 ```
89
d06fab4 @tj docs
tj authored
90 ## Installing packages
91
92 To install one or more packages, simply pass their github
93 repo names as arguments to `component install`. Dependencies
94 are resolved and the component contents are downloaded into
4c0b62e @tj docs
tj authored
95 `./components` by default. View `component help install` for details.
d06fab4 @tj docs
tj authored
96
97 ```
98 $ component install component/tip
77d8a3b @tj links
tj authored
99
d06fab4 @tj docs
tj authored
100 install : component/tip@master
101 dep : component/emitter@master
102 install : component/emitter@master
103 dep : component/jquery@master
104 install : component/jquery@master
105 fetch : component/tip:index.js
106 fetch : component/tip:tip.css
107 fetch : component/tip:tip.html
108 fetch : component/emitter:index.js
109 fetch : component/jquery:index.js
110 complete : component/emitter
111 complete : component/jquery
112 complete : component/tip
113 ```
114
4a8ab92 @tj add search docs
tj authored
115 ## Searching for components
116
117 By adding your component to the [Components List](https://github.com/component/component/wiki/Components) wiki page it will become automatically available to `component-search(1)`. When invoked with no query all components are displayed, otherwise a filtered search, ordered by the number of github "stars":
118
119 ```
120 $ component search ui
121
122 component/dialog
123 url: https://github.com/component/dialog
124 desc: Dialog component
125 ★ 12
126
127 component/notification
128 url: https://github.com/component/notification
129 desc: Notification component
130 ★ 10
131
132 component/overlay
133 url: https://github.com/component/overlay
134 desc: Overlay component
135 ★ 7
136
137 ```
138
4c0b62e @tj docs
tj authored
139 ## Using Github as a registry
0724267 @tj docs
tj authored
140
141 By using GitHub as the registry, `component(1)` is automatically
142 available to you without further explicit knowledge or work
143 creating a registry account etc.
144
145 A nice side-effect of this namespaced world is that dependencies
146 are explicit and self-documenting. No longer do you need to query
147 the registry for a "repo" property that may not exist, it's simply
4c0b62e @tj docs
tj authored
148 built in to the package name, for example ["visionmedia/page.js"](https://github.com/visionmedia/page.js) rather
efebc26 @tj docs
tj authored
149 than the unclear "page".
0724267 @tj docs
tj authored
150
fb3e50a @tj docs
tj authored
151 Another benefit of this is that there are zero name collisions, for example
152 you may use "component/tip" for a dependency of "foo", and "someuser/tip"
153 as a dependency of "bar", providing `require('tip')` in each. This prevents
154 obscure or irrelevant naming such as "progress", "progress2", "progress-bar",
155 "progress-component" found in npm.
156
7c0b0a2 @tj docs
tj authored
157 ## Creating a component
158
159 The `component-create(1)` command can create a component
160 project skeleton for you by filling out the prompts. Once
161 this repo is published to Github, you're all done!
162
163 ```
2811ddd @tj update docs
tj authored
164 name: popover
77d8a3b @tj links
tj authored
165 description: Popover UI component
7c0b0a2 @tj docs
tj authored
166 does this component have js? yes
167 does this component have css? yes
168 does this component have html? yes
169
2811ddd @tj update docs
tj authored
170 create : popover
171 create : popover/index.js
172 create : popover/template.html
173 create : popover/popover.css
174 create : popover/Makefile
175 create : popover/Readme.md
176 create : popover/.gitignore
177 create : popover/component.json
7c0b0a2 @tj docs
tj authored
178
179 ```
180
67002d6 @tj docs
tj authored
181 A `Makefile` is created for you in order to create a build of the component,
182 complete with installed dependencies simply execute `make`.
183
8947deb @tj docs
tj authored
184 ## Templates
185
186 Because `component(1)` has no notion of a "template", even simple HTML files
187 should be converted to a `require()`-able module. It is recommended that public
03671fe @tj docs
tj authored
188 components shared within the community use regular HTML templates, and regular
8947deb @tj docs
tj authored
189 CSS stylesheets to maximize contributions, however if you wish to use alternate
190 technologies just make sure to compile them before publishing them to Github.
191
03671fe @tj docs
tj authored
192 For the recommended use-case of regular HTML, the `component-convert(1)` command
193 will translate a regular HTML file to its `require()`-able JavaScript counterpart.
194
8947deb @tj docs
tj authored
195 ## Developing component(1) sub-commands
460e6fe @tj add some dev docs
tj authored
196
197 `component(1)` and sub-commands are structured much like `git(1)`,
198 in that sub-commands are simply separate executables. For example
199 `$ component info pkg` and `$ component-info pkg` are equivalent.
200
201 Because of this you'll likely want `PATH="./bin:$PATH"` in your
202 profile or session while developing component, otherwise `./bin/component`
203 will have a hard time finding the sub-commands.
204
771c084 @tj docs
tj authored
205 ## Running tests
206
207 Make sure dependencies are installed:
208
209 ```
210 $ npm install
211 ```
212
213 Then run:
214
215 ```
216 $ make test
217 ```
218
8b84f23 @tj docs
tj authored
219 ## Shout-outs
220
8ad0d21 @tj add FAQ link
tj authored
221 The concept of components themselves are nothing new, Drupal
1329bfc @tj add Drupal mention
tj authored
222 for example has been doing this for years, however it seemed the concept was never
223 really translated to the client. My hope is that other communities will re-implement this
8b84f23 @tj docs
tj authored
224 simple tool in their language of choice so that we can all consume components
225 easily.
226
6dc0d57 @tj add list of contrib
tj authored
227 ## Contributors
228
229 - TJ Holowaychuk
230 - Guillermo Rauch
231 - Garrett Johnson
232 - Amir Abu Shareb
233 - Adam Sanderson
234 - Matt Mueller
235 - Forbes Lindesay
236 - Arpad Borsos
237 - Dan Williams
d0016e7 @tj add damian to contrib
tj authored
238 - Damián Suárez
1277748 @tj contrib
tj authored
239 - Tim Oxley
6dc0d57 @tj add list of contrib
tj authored
240
be1d95e @tj add link to todo
tj authored
241 ## Example applications
242
243 Open source application examples:
77d8a3b @tj links
tj authored
244
c143375 @tj docs
tj authored
245 - [Todo list](https://github.com/component/todo)
be1d95e @tj add link to todo
tj authored
246
77d8a3b @tj links
tj authored
247 ## License
98a5bb9 @tj Initial commit
tj authored
248
249 (The MIT License)
250
251 Copyright (c) 2012 TJ Holowaychuk &lt;tj@vision-media.ca&gt;
252
253 Permission is hereby granted, free of charge, to any person obtaining
254 a copy of this software and associated documentation files (the
255 'Software'), to deal in the Software without restriction, including
256 without limitation the rights to use, copy, modify, merge, publish,
257 distribute, sublicense, and/or sell copies of the Software, and to
258 permit persons to whom the Software is furnished to do so, subject to
259 the following conditions:
260
261 The above copyright notice and this permission notice shall be
262 included in all copies or substantial portions of the Software.
263
264 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
265 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
266 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
267 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
268 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
269 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
77d8a3b @tj links
tj authored
270 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.