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