Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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