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