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