Skip to content
This repository
Newer
Older
100644 261 lines (169 sloc) 16.223 kb
0b59ec4f »
2012-08-04 Add .travis.yml. Fix minify command's error reporting. Remove executa…
1 # Nodefront [![Build Status](https://secure.travis-ci.org/karthikv/nodefront.png)](http://travis-ci.org/karthikv/nodefront)
e82bce7e »
2012-07-19 Add README and fix library not found message.
2
3 To see a styled version of the documentation below, please visit [nodefront's website](http://karthikv.github.com/nodefront).
4
5 ## Overview
6
19a67398 »
2012-07-20 Improve README and add LICENSE.
7 Nodefront is a node.js-powered command-line utility that speeds up front-end development.
e82bce7e »
2012-07-19 Add README and fix library not found message.
8
9 ## Installation
10
11 Installation is simple with npm:
12
13 ```bash
19a67398 »
2012-07-20 Improve README and add LICENSE.
14 $ npm install -g nodefront
e82bce7e »
2012-07-19 Add README and fix library not found message.
15 ```
16
19a67398 »
2012-07-20 Improve README and add LICENSE.
17 ## Introductory Screencast
18
19 Before diving into the documentation, you may view a [screencast that introduces some of nodefront's key features on Vimeo](https://vimeo.com/46197434).
20
e82bce7e »
2012-07-19 Add README and fix library not found message.
21 ## Command Summary
22
23 Compile: `nodefront compile` - Compiles Jade and Stylus files to HTML and CSS. Can compile upon modification, serve files on localhost, and even automatically refresh the browser/styles when files are changed.
24
25 Fetch: `nodefront fetch` - Automatically fetches CSS/JS libraries for use in your project. Provides an interactive mode to add new libraries.
26
27 Insert: `nodefront insert` - Inserts CSS/JS libraries directly into your HTML or Jade files.
28
29 Minify: `nodefront minify` - Minifies CSS and JS files. Can also optimize JPG and PNG images.
30
31 ## Compile Command
32 ### Usage
33
34 ```bash
35 $ nodefront compile [options]
36 ```
37
38 The compile command will look for all Jade (\*.jade) and Stylus (\*.styl, \*.stylus) files in the current directory without recursing (see the recursive option) and compile them to their HTML and CSS counterparts, simply replacing the extension of the originally-named file.
39
40 ### Example
41 If the directory structure initially looks like:
42
43 .
44 |_ index.jade
45 `_ styles.styl
46
47 After running `nodefront compile`, `index.jade` will be compiled to `index.html` and `styles.styl` will be compiled to `styles.css`, resulting in the following new directory structure:
48
49 .
50 |_ index.jade
51 |_ index.html
52 |_ styles.styl
53 `_ styles.css
54
55 ### Options
56 Help: `nodefront compile -h/--help` outputs usage information about the compile command.
57
58 Recursive: `nodefront compile -r/--recursive` recurses through sub-directories instead of only compiling Jade and Stylus files in the current directory.
59
60 Watch: `nodefront compile -w/--watch` watches all Jade and Stylus files in the current directory (and subdirectories if the recursive option is specified) and recompiles them upon modification. `watch` is dependency aware, meaning that if `index.jade` extends/includes `layout.jade`, when `layout.jade` is modified, both `layout.jade` and `index.jade` will be recompiled. This same awareness is present for Stylus files as well.
61
62 Serve: `nodefront compile -s/--serve [port]` creates a `localhost` server via node.js that serves all files in the current directory and any subdirectories. By default, this server is created on port 3000, but this is modifiable via the [port] option. For example, `nodefront --serve 5387` will serve nodefront on port 5387.
63
64 Live: `nodefront compile -l/--live [port]` mimics the serve option (see above) with some added file watching features. For each HTML page that is served to the browser, all of its file dependencies, including the source itself, its CSS styles, and its scripts, are monitored for changes. If the source itself or one of its scripts changes, the browser will automatically refresh. If a CSS stylesheet is modified, it is reloaded without refreshing via a cache-busting query string. This allows for live development with immediate feedback and circumvents the need to keep reloading the browser manually.
65
66 For those who are interested in the more technical aspects of the live command, the `localhost` server that it creates automatically injects web socket code, courtesy of socket.io, into HTML pages. This allows communication between the client and the node.js server. Whenever a file is modified, the server notifies the client via the established socket connection. The client then assesses whether this file affects the current page and takes appropriate actions.
67
68 ## Fetch Command
69 ### Usage
70
71 ```bash
72 $ nodefront fetch [library] [options]
73 ```
74
75 The fetch command will download the given CSS/JS library, [library], from the web and add it to the current directory. Nodefront is already aware of many of the most popular CSS/JS libraries, but can easily be configured to fetch lesser-known ones.
76
77 ### Example
78 To fetch the latest version of jQuery, simply run:
79
80 ```bash
81 $ nodefront fetch jquery
82 ```
83
84 jQuery 1.7.2 (as of 6/19/12) will then be added to the current directory. If, for instance, you'd like to fetch version 1.5, simply use the version option, specified by `-v` or `--version`:
85
86 ```bash
87 $ nodefront fetch jquery -v 1.5
88 ```
89
90 jQuery 1.5 should then be downloaded into the current directory.
91
92 ### Options
93 Help: `nodefront fetch -h/--help` outputs usage information about the compile command.
94
95 Type: `nodefront fetch [library] -t/--type [type]` will set the type, or extension, of the given library, [library]. When the library has finished downloading, it will then be named [library]-[version].\[type\]. Note that the type defaults to js if this option is not given.
96
97 Output: `nodefront fetch [library] -o/--output [directory]` downloads the given library and stores the resultant file (see type option above), in the given directory, [directory].
98
99 Version: `nodefront fetch [library] -v/--version [version]` downloads the given library at the provided version number, [version], and saves it to [library]-[version].\[type\] (see type option above).
100
101 Interactive: `nodefront fetch [library] -i/--interactive` enables interactive mode, where you'll be provided with numerous dialogs that fully explain the process of adding a new library. You can alternatively specify all the configuration parameters necessary by using the command-line (see options below). Note that, if necessary, you can mix and match as well, specifying the URL parameter while also going into interactive mode to get some help setting the path.
102
103 URL: `nodefront fetch [library] -u/--url [url]` will fetch the library file at the given URL, [url], and add it to the current directory with the name [library]-[version].\[type\] (see version/type options above). To make this flexible for different versions of the library, simply add the parameter `{{ version }}` where the version should be inserted in the URL. Then, the version parameter (see above) will determine what value this gets replaced with. Note that, if you specify the URL for a library, all configuration options are automatically saved, meaning that you can fetch the library again at any time simply by running `nodefront fetch [library]`. If you ever need to update the configuration options again, specify the URL once more.
104
105 Path: `nodefront fetch [library] -p/--path [pathRegex]` requires the URL parameter to be provided (see above). It then assumes that the [url] points to a zip file, extracts all files within it, and finds the first one to match the regular expression [pathRegex]. This file will be considered the library you were looking for and is then downloaded.
106
107 Minify: `nodefront fetch [library] -m/--minify` will fetch the given library and minify it upon download. Note that both CSS and JS libraries can be minified.
108
109 ## Insert Command
110 ### Usage
111
112 ```bash
113 $ nodefront insert [libraryPath] [file] [options]
114 ```
115
116 The insert command will insert the CSS or JS library, given by the path [libraryPath], into the HTML or Jade file specified by [file] as either a link or script tag. If [libraryPath] ends in '.css', a link tag will be appended to the head of the document. In like manner, if [libraryPath] ends in '.js', a script tag will be inserted in the footer prior to the end of the body (see head option for inserting into the head).
117
118 ### Examples
119 To insert a script tag containing jquery at the end of index.html, run:
120
121 ```bash
122 $ nodefront insert jquery-1.7.2.js index.html
123 ```
124
125 If, instead, you would like the script tag to be appended to the head tag, simply specify the head option, specified by `-h` or `--head`:
126
127 ```bash
128 $ nodefront insert jquery-1.7.2.js index.html -h
129 ```
130
131 Both of these will insert the tag `<script src="jquery-1.7.2.js"></script>` into index.html. For jade files, nodefront will insert `script(src='jquery-1.7.2.js')` instead. Note that nodefront will find the relative path between [libraryPath] and [file] and use that as the src attribute. If you would like an absolute path instead, use the absolute option, specified by `-a` or `--absolute`.
132
133 ```bash
134 $ nodefront insert jquery-1.7.2.js index.html -a
135 ```
136
137 To remove `jquery-1.7.2.js` from a file, add the delete option, specified by `-d` or `--delete`.
138
139 ```bash
140 $ nodefront insert jquery-1.7.2.js index.html -ad
141 ```
142
143 Make sure to maintain the absolute option if the original insertion used an absolute path.
144
145 ### Options
146 Help: `nodefront insert --help` outputs usage information about the insert command.
147
148 Head: `nodefront insert [libraryPath] [file] -h/--head` will append the given library to the head of the document. By default, CSS libraries are added to the head, as they cannot be added elsewhere, and JS libraries are added prior to the end body tag.
149
150 Absolute: `nodefront insert [libraryPath] [file] -a/--absolute` will use the absolute path of the given library, [libraryPath], as the value of the src/href attribute to the script/link tag that is inserted. By default, a relative path is used.
151
152 Tab Length: `nodefront insert [libraryPath] [file] -t/--tab-length [length]` will use the provided tab length, [length], when inserting the script/link tag. By default, the tab length is 4, representing four spaces. If you would prefer hard tabs (`'\t'` characters), simply specify -1 as the tab length.
153
154 Delete: `nodefront insert [libraryPath] [file] -d` will delete the library from the given file instead of inserting it. Make sure to maintain the absolute option (see above) if the original insertion used an absolute path for the src/href attribute.
155
156 ## Minify Command
157 ### Usage
158
159 ```bash
160 $ nodefront minify [fileRegex] [options]
161 ```
162
163 The minify command finds all file paths in the current directory, without recursing (see the recursive option), that match the given fileRegex. It then minifies the corresponding files, using UglifyJS for JS files, YUI (the JS implementation) for CSS, JPEGtran for JPEG, and OptiPNG for PNG. By default, the output file name is the original file name without its extension followed by '.min.' and the original file name's extension. For example, if the original file name is 'style.css', the new file name is 'style.min.css'.
164
165 ### Examples
166 To minify script.js in the current directory into script.min.js, run:
167
168 ```bash
169 $ nodefront minify -p script.js
170 ```
171
172 The plain option, specified by `-p` or `--plain`, changes [fileRegex] from a regular expression to just a plain text string.
173
174 To minify all CSS files in the current directory, simply use the CSS option, `-c` or `-css` with no [fileRegex] parameter:
175
176 ```bash
177 $ nodefront minify -c
178 ```
179
180 In like manner, the JS option, `-j` or `--js`, and the images option, `-i` or `--images`, minify JS files and optimize all images, respectively. You can mix and match these options as necessary. To minify all CSS, JS, and image files in the current directory, for example, run:
181
182 ```bash
183 $ nodefront minify -cji
184 ```
185
186 ### Options
187 Help: `nodefront minify --help` outputs usage information about the minify command.
188
189 Recursive: `nodefront minify [fileRegex] -r/--recursive` will minify all file paths in the current directory and in any sub-directories that match the regular expression [fileRegex].
190
191 Plain: `nodefront minify [fileRegex] -p/--plain` will change [fileRegex] from being a regular expression to just a normal text string. With this option enabled, you can pinpoint the exact file you would like to minify by setting [fileRegex] to its path.
192
193 Type: `nodefront minify [fileRegex] -t/--type [type]` will set the type of all the files that are being minified. Normally, the type of a given file is determined by its extension, with \*.css, \*.js, \*.png, and \*.jpg or \*.jpeg representing CSS, JS, PNG, and JPEG files, respectively. If you would like to minify a file without an extension or with one that does not match these defaults, this option will let you force nodefront to treat it as if it had the extension [type]. For example, running `nodefront minify -p script -t js` would minify script as if it was a JS file even though it lacks a .js extension.
194
195 Out: `nodefront minify [fileRegex] -o [file]` will minify all file paths in the current directory that match the regular expression [fileRegex] and put the output in the file named [file]. Include `{{ name }}` in [file] and it will be replaced by the name of the current file being minified without its extension. In like manner, include `{{ extension }}` in [file] and it will be replaced by the extension of the current file being minified. For example, assume you have the following directory structure:
196
197 .
198 |_ main-script.js
199 `_ main-style.css
200
201 If you run `nodefront minify main -o '{{ name }}-minified.{{ extension }}'`, main-script.js will be minified to main-script-minified.js and main-style.css will be minified to main-style-minified.css, leaving you with the following new directory structure:
202
203 .
204 |_ main-script.js
205 |_ main-script-minified.js
206 |_ main-style.css
207 `_ main-style-minified.js
208
209 This option defaults to `{{ name }}.min.{{ extension }}` if not provided.
210
211 Overwrite: `nodefront minify [fileRegex] -w/--overwrite` will overwrite files will their minified versions instead of writing to `{{ name }}.min.{{ extension }}` (see out option). This is a shortcut to specifying `{{ name }}.{{ extension }}` for the out option.
212
213 CSS: `nodefront minify -c/-css` will minify all CSS files in the current directory. This is a shortcut to `nodefront minify \.css$`.
214
215 JS: `nodefront minify -j/-js` will minify all JS files in the current directory. This is a shortcut to `nodefront minify \.js$`.
216
217 Images: `nodefront minify --i/--images` will minify all JPEG and PNG images in the current directory. This is a shortcut to `nodefront minify \.(jpg|jpeg|png)$`.
218
19a67398 »
2012-07-20 Improve README and add LICENSE.
219 Note that the last three options can be mix and matched as necessary to, for example, minify all CSS and JS, but no images, like so:
220
221 ```bash
222 $ nodefront minify -cj
223 ```
e82bce7e »
2012-07-19 Add README and fix library not found message.
224
19a67398 »
2012-07-20 Improve README and add LICENSE.
225 ## Contributors
226 ### Karthik Viswanathan
227 - GitHub: [@karthikv](https://github.com/karthikv)
228 - Twitter: [@karthikvnet](https://twitter.com/karthikvnet)
229 - Website: [http://karthikv.net](http://karthikv.net)
230 - Email: me@karthikv.net
231
232 ## Questions?
233 If you have any questions, comments, concerns, or suggestions, please feel free to create a new issue on [GitHub](https://github.com/karthikv/nodefront/issues) or contact Karthik directly (see contributors section above).
234
235 ## Inspiration
236 - [Volo](https://github.com/volojs/volo) - "A JavaScript dependency manager and project creation tool that favors GitHub for the package repository."
237 - [Yeoman](http://yeoman.io/) - "A robust and opinionated client-side stack, comprised of tools and frameworks that can help developers quickly build beautiful web applications."
238
239 ## License
240 (The MIT License)
241
242 Copyright (c) 2012 Karthik Viswanathan &lt;me@karthikv.net&gt;
243
244 Permission is hereby granted, free of charge, to any person obtaining
245 a copy of this software and associated documentation files (the
246 'Software'), to deal in the Software without restriction, including
247 without limitation the rights to use, copy, modify, merge, publish,
248 distribute, sublicense, and/or sell copies of the Software, and to
249 permit persons to whom the Software is furnished to do so, subject to
250 the following conditions:
251
252 The above copyright notice and this permission notice shall be
253 included in all copies or substantial portions of the Software.
254
255 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
256 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
257 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
258 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
259 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
260 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
261 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.