Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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