Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 248 lines (184 sloc) 8.311 kb
98a5bb9 @tj Initial commit
tj authored
1
8078059 @tj add logo to readme
tj authored
2 ![web component logo](http://i49.tinypic.com/e7nj9v.png)
3
4 Component package manager for building a better web.
d06fab4 @tj docs
tj authored
5
6 ## Installation
7
37b0511 @tj docs
tj authored
8 $ npm install -g component
d06fab4 @tj docs
tj authored
9
10 ## Installing packages
11
12 To install one or more packages, simply pass their github
13 repo names as arguments to `component install`. Dependencies
14 are resolved and the component contents are downloaded into
4c0b62e @tj docs
tj authored
15 `./components` by default. View `component help install` for details.
d06fab4 @tj docs
tj authored
16
17 ```
18 $ component install component/tip
19
20 install : component/tip@master
21 dep : component/emitter@master
22 install : component/emitter@master
23 dep : component/jquery@master
24 install : component/jquery@master
25 fetch : component/tip:index.js
26 fetch : component/tip:tip.css
27 fetch : component/tip:tip.html
28 fetch : component/emitter:index.js
29 fetch : component/jquery:index.js
30 complete : component/emitter
31 complete : component/jquery
32 complete : component/tip
33 ```
34
4a8ab92 @tj add search docs
tj authored
35 ## Searching for components
36
37 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":
38
39 ```
40 $ component search ui
41
42 component/dialog
43 url: https://github.com/component/dialog
44 desc: Dialog component
45 ★ 12
46
47 component/notification
48 url: https://github.com/component/notification
49 desc: Notification component
50 ★ 10
51
52 component/overlay
53 url: https://github.com/component/overlay
54 desc: Overlay component
55 ★ 7
56
57 ```
58
d06fab4 @tj docs
tj authored
59 ## Usage
60
61 Via `--help`:
62
63 ```
7a29005 @tj docs
tj authored
64
d06fab4 @tj docs
tj authored
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
9058a5a @tj fix remotes
tj authored
74 install [name ...] install one or more components
75 create [dir] create a component skeleton
d3cbf4f @tj update help usage
tj authored
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 open <name> open component github repo
9058a5a @tj fix remotes
tj authored
82 wiki open the components list wiki page
d3cbf4f @tj update help usage
tj authored
83 build build the component
84 ls list installed components
7a29005 @tj docs
tj authored
85
d06fab4 @tj docs
tj authored
86 ```
98a5bb9 @tj Initial commit
tj authored
87
32f16ca @tj docs
tj authored
88 ## Features
89
82e5b3a @tj docs
tj authored
90 - write modular commonjs components
8fc1748 @tj docs
tj authored
91 - write components that include their own styles, images, scripts, or any combo
4c0b62e @tj docs
tj authored
92 - no registry publishing or account required, uses github repositories
b33beb6 @tj docs
tj authored
93 - extensible sub-commands via `component-YOURCOMMAND` git-style
6b2b654 @tj docs
tj authored
94 - component skeleton creation command
4c0b62e @tj docs
tj authored
95 - installs dependencies from the command-line or ./component.json
babb5be @tj docs
tj authored
96 - avoid name squatting through github's naming conventions
fa6b64c @tj docs
tj authored
97 - build your components with `--standalone` to share them with non-component(1) users
8fc1748 @tj docs
tj authored
98 - view documentation from the command line
c3804ea @tj docs
tj authored
99 - simple private registry set up (all you need is a file server)
ce5e68f @tj docs
tj authored
100 - very fast
32f16ca @tj docs
tj authored
101
4c0b62e @tj docs
tj authored
102 ## Using Github as a registry
0724267 @tj docs
tj authored
103
104 By using GitHub as the registry, `component(1)` is automatically
105 available to you without further explicit knowledge or work
106 creating a registry account etc.
107
108 A nice side-effect of this namespaced world is that dependencies
109 are explicit and self-documenting. No longer do you need to query
110 the registry for a "repo" property that may not exist, it's simply
4c0b62e @tj docs
tj authored
111 built in to the package name, for example ["visionmedia/page.js"](https://github.com/visionmedia/page.js) rather
efebc26 @tj docs
tj authored
112 than the unclear "page".
0724267 @tj docs
tj authored
113
fb3e50a @tj docs
tj authored
114 Another benefit of this is that there are zero name collisions, for example
115 you may use "component/tip" for a dependency of "foo", and "someuser/tip"
116 as a dependency of "bar", providing `require('tip')` in each. This prevents
117 obscure or irrelevant naming such as "progress", "progress2", "progress-bar",
118 "progress-component" found in npm.
119
7c0b0a2 @tj docs
tj authored
120 ## Creating a component
121
122 The `component-create(1)` command can create a component
123 project skeleton for you by filling out the prompts. Once
124 this repo is published to Github, you're all done!
125
126 ```
2811ddd @tj update docs
tj authored
127 name: popover
128 description: Popover UI component
7c0b0a2 @tj docs
tj authored
129 does this component have js? yes
130 does this component have css? yes
131 does this component have html? yes
132
2811ddd @tj update docs
tj authored
133 create : popover
134 create : popover/index.js
135 create : popover/template.html
136 create : popover/popover.css
137 create : popover/Makefile
138 create : popover/Readme.md
139 create : popover/.gitignore
140 create : popover/component.json
7c0b0a2 @tj docs
tj authored
141
142 ```
143
67002d6 @tj docs
tj authored
144 A `Makefile` is created for you in order to create a build of the component,
145 complete with installed dependencies simply execute `make`.
146
8947deb @tj docs
tj authored
147 ## Templates
148
149 Because `component(1)` has no notion of a "template", even simple HTML files
150 should be converted to a `require()`-able module. It is recommended that public
03671fe @tj docs
tj authored
151 components shared within the community use regular HTML templates, and regular
8947deb @tj docs
tj authored
152 CSS stylesheets to maximize contributions, however if you wish to use alternate
153 technologies just make sure to compile them before publishing them to Github.
154
03671fe @tj docs
tj authored
155 For the recommended use-case of regular HTML, the `component-convert(1)` command
156 will translate a regular HTML file to its `require()`-able JavaScript counterpart.
157
8947deb @tj docs
tj authored
158 ## Developing component(1) sub-commands
460e6fe @tj add some dev docs
tj authored
159
160 `component(1)` and sub-commands are structured much like `git(1)`,
161 in that sub-commands are simply separate executables. For example
162 `$ component info pkg` and `$ component-info pkg` are equivalent.
163
164 Because of this you'll likely want `PATH="./bin:$PATH"` in your
165 profile or session while developing component, otherwise `./bin/component`
166 will have a hard time finding the sub-commands.
167
771c084 @tj docs
tj authored
168 ## Running tests
169
170 Make sure dependencies are installed:
171
172 ```
173 $ npm install
174 ```
175
176 Then run:
177
178 ```
179 $ make test
180 ```
181
8b84f23 @tj docs
tj authored
182 ## Shout-outs
183
8ad0d21 @tj add FAQ link
tj authored
184 The concept of components themselves are nothing new, Drupal
1329bfc @tj add Drupal mention
tj authored
185 for example has been doing this for years, however it seemed the concept was never
186 really translated to the client. My hope is that other communities will re-implement this
8b84f23 @tj docs
tj authored
187 simple tool in their language of choice so that we can all consume components
188 easily.
189
e0b7fda @tj add link to first screencast
tj authored
190 ## Screencasts
191
192 - [App integration introduction](https://vimeo.com/48054442)
193
aa02f3f @tj links
tj authored
194 ## Links
195
e961815 @tj links
tj authored
196 - [List](https://github.com/component/component/wiki/Components) of all available components
197 - [Wiki](https://github.com/component/component/wiki)
aa02f3f @tj links
tj authored
198 - [Mailing List](https://groups.google.com/group/componentjs)
cb2e92e @adamsanderson Update README - Fixed Link
adamsanderson authored
199 - component ["spec"](https://github.com/component/component/wiki/Spec)
c6e47b0 @tj irc channel
tj authored
200 - join `#components` on freenode
454f264 @tj fix prev commit :)
tj authored
201 - follow [@component_js](http://twitter.com/component_js) on twitter
e961815 @tj links
tj authored
202 - [Building better components](https://github.com/component/component/wiki/Building-better-components) tips
8ad0d21 @tj add FAQ link
tj authored
203 - [F.A.Q](https://github.com/component/component/wiki/F.A.Q)
aa02f3f @tj links
tj authored
204
6dc0d57 @tj 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 add damian to contrib
tj authored
216 - Damián Suárez
1277748 @tj contrib
tj authored
217 - Tim Oxley
6dc0d57 @tj add list of contrib
tj authored
218
be1d95e @tj add link to todo
tj authored
219 ## Example applications
220
221 Open source application examples:
222
c143375 @tj docs
tj authored
223 - [Todo list](https://github.com/component/todo)
be1d95e @tj add link to todo
tj authored
224
98a5bb9 @tj 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.