Skip to content

HTTPS clone URL

Subversion checkout URL

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