UNPKG

8.56 kBMarkdownView Raw
1# Syrup
2
3A collection of shared UI utilities and libraries leveraged by [AI2](http://github.com/allenai) when developing interfaces.
4
5Specifically, syrup provides:
6
7* A series of [gulp](http://gulpjs.com) tasks for building a single-page client-side application.
8* A collection of [less](http://lesscss.org) styles. To see them in action, visit the [demo](http://allenai.github.io/syrup).
9
10## Requirements
11
12* [nodejs](http://nodejs.org) >= 0.12.7 is required.
13
14## Installation
15
16Install via [npm](http://npmjs.org):
17
18```shell
19npm install syrup
20```
21
22## Gulp
23
24Syrup includes a series of gulp tasks useful for building a single-page client-side application.
25
26The [gulp tasks](#gulp-tasks) provided by syrup can be initialized like so in your `gulpfile.js`:
27
28```javascript
29// gulpfile.js
30var gulp = require('gulp');
31var syrup = require('syrup');
32
33syrup.gulp.init(gulp);
34```
35
36A build can then be triggered from the terminal:
37
38```
39gulp build
40```
41
42Watch your project for changes dynamically and start a static HTTP server for previewing the result:
43
44```
45gulp watch-and-serve
46```
47
48Read about all of the available [gulp tasks](#gulp-tasks), the default [project structure](#project-structure) or the full API offered by the [`syrup.gulp.init()`](#gulp-init).
49
50## <a name="less"></a> LESS
51
52To include the all of the less styles provide by syrup, simply add the following line to your less stylesheet:
53
54```css
55@import '../../node_modules/syrup/less/syrup.less';
56```
57
58## <a name="gulp-tasks"></a> Gulp Tasks
59
60Syrup provides the following tasks:
61
62- `clean`
63 * Removes all build artifacts
64* `less`
65 * Compiles and minifies LESS files to CSS files.
66* `jslint`
67 * Lints JS files using [jshint](https://www.npmjs.com/package/gulp-jshint).
68* `js`
69 * Bundles, minifies and obfuscates `js` files using [browserify](http://browserify.org) into a single, bundled script. Uses [babel](https://babeljs.io/) to provide support for ECMA6 features and [ReactJS](http://reactjs.com).
70* `assets`
71 * Copies all assets into the build directory.
72* `html`
73 * Copies the `index.html` file into the build directory after running the `js`, `assets`, and `less` tasks.
74* `build`
75 * Builds the project by running the `assets`, `jslint`, `js`, `less`, and `html` tasks.
76* `watch`
77 * Watches the project for changes and rebuilds the affected components as they occur.
78* `serve`
79 * Runs an [express](http://expressjs.com) HTTP serving serving the application.
80* `watch-and-serve`
81 * Runs the `watch` and `serve` tasks.
82
83## <a name="project-structure"></a> Default Project Structure
84
85The following project structure is expected by default, but can be changed via the `paths` parameter
86of [`syrup.gulp.init()`](#gulp-init):
87
88```javascript
89{
90 // the location of your application's index.html file
91 html: 'app/index.html',
92 // the less files which will be watched for changes
93 allLess: 'app/**/*.less',
94 // the less entry-point
95 less: 'app/main.less',
96 // all js files to be linted using eslint
97 jsLint: 'app/**/*.js',
98 // the js entry-point
99 js: 'app/app.js',
100 // static assets (images, fonts, etc)
101 assets: 'app/assets/**/*',
102 // the location of build output
103 build: 'build'
104}
105```
106
107## <a name="gulp-init"></a> Gulp API
108
109```javascript
110/**
111 * Registers default gulp tasks.
112 *
113 * @param {object} gulp The gulp library.
114 * @param {object} [options] Optional object definining configuration
115 * parameters.
116 * @param {boolean} [options.compressJs=true] If true javascript will be minified.
117 * Defaults to true. This causes the build
118 * to become significantly slower.
119 * @param {boolean} [options.sourceMaps=true] Enables javascript source maps. Defaults
120 * to true.
121 * @param {boolean} [options.compressCss=true] If true styles will be compressed.
122 * Defaults to true.
123 * @param {boolean} [options.detectGlobals=true] Enables browserify global detection and
124 * inclusion. This is necessary for certain
125 * npm packages to work when bundled for
126 * front-end inclusion. Defaults to true.
127 * @param {boolean} [options.insertGlobals=false] Enables automatic insertion of node
128 * globals when preparing a javascript
129 * bundler. Faster alternative to
130 * detectGlobals. Causes an extra ~1000
131 * lines to be added to the bundled
132 * javascript. Defaults to false.
133 * @param {boolean} [options.disableJsLint=false] Disables javascript linter. Defaults to false.
134 * @param {boolean} [options.handleExceptions=false] If an exception is encountered while
135 * compiling less or bundling javascript,
136 * capture the associated error and output
137 * it cleanly. Defaults to false.
138 * @param {string} [options.jsOut] Overrides the default filename for the
139 * resulting javascript bundle. If not set
140 * the javascript file will be the same name
141 * as the entry point.
142 * @param {boolean} [options.disableBabel=false] Optionally disable babel, the es6 to es6
143 * (and react JSX) transpiler.
144 * See http://babeljs.io for more information.
145 * @param {boolean} [options.enableStringify=false] Optionally enable stringify, a browserify
146 * transform that allows HTML files to be
147 * included via require.
148 * @param {number} [options.port=4000] Optional port for the HTTP server started
149 * via the serve task. Defaults to 4000.
150 * @param {object} [configParameters] Optional map of configuration keys. If
151 * set each key is searched for in the built
152 * HTML and replaced with the corresponding
153 * value.
154 * @param {object} [paths] Optional object defining paths relevant
155 * to the project. Any specified paths are
156 * merged with the defaults where these paths
157 * take precedence.
158 * @param {string} paths.base The base directory of your project where
159 * the gulpfile lives. Defaults to the
160 * current processes working directory.
161 * @param {string} paths.html Path to the project's HTML files.
162 * @param {string} paths.jsLint Path to the javascript files which should
163 * be linted using eslint.
164 * @param {string} paths.js Javascript entry point.
165 * @param {string} paths.allLess Path matching all less files which should
166 * be watched for changes.
167 * @param {string} paths.less The less entry-point.
168 * @param {string} paths.assets Path to the project's static assets.
169 * @param {string} paths.build Output directory where the build artifacts
170 * should be placed.
171 *
172 * @returns {undefined}
173 */
174syrup.gulp.init(gulp, options, configParameters, paths)
175```