1 | # Cogs
|
2 |
|
3 | The fast file transform pipeline.
|
4 |
|
5 | > George Jetson's workweek is typical of his era: an hour a day, two days a
|
6 | > week. His boss is Cosmo Spacely, the diminutive yet bombastic owner of Spacely
|
7 | > Space Sprockets. Spacely has a competitor, H. G. Cogswell, owner of the rival
|
8 | > company Cogswell Cogs (sometimes known as Cogswell's Cosmic Cogs).
|
9 |
|
10 | ## Install
|
11 |
|
12 |
|
13 | ```bash
|
14 | npm install cogs
|
15 | ```
|
16 |
|
17 | ## Usage
|
18 |
|
19 | Cogs leverages a simple command line interface paired with a powerful
|
20 | declarative config file.
|
21 |
|
22 | ```
|
23 | Usage: cogs [options]
|
24 |
|
25 | The fast file transform pipeline.
|
26 |
|
27 |
|
28 | Options:
|
29 |
|
30 | -V, --version output the version number
|
31 | -c, --config-path [path] load config from [path] (default: cogs.js)
|
32 | -d, --debounce [seconds] trigger a build at most every [seconds] seconds (default: 0.1)
|
33 | -w, --watch-paths [path] rebuild if [path] changes, can be specified multiple times
|
34 | -p, --use-polling use stat polling instead of fsevents when watching
|
35 | -s, --silent do not output build information, only errors
|
36 | -C, --no-color disable colored output
|
37 | -h, --help output usage information
|
38 | ```
|
39 |
|
40 | ## Config
|
41 |
|
42 | Every good project needs a Cogs config file. This file can be JavaScript or
|
43 | JSON, as long as `require`ing the file returns the config object. Here's an
|
44 | example in JavaScript:
|
45 |
|
46 | ```js
|
47 | export default {
|
48 |
|
49 | // Define the transformer pipeline here.
|
50 | transformers: [
|
51 | {
|
52 | // This is the name of the transformer to use for this piece of the
|
53 | // pipeline. It can be shorthand like this, or the fully-qualified package
|
54 | // name like 'cogs-transformer-babel'.
|
55 | name: 'babel',
|
56 |
|
57 | // The "only" key can be used to define a glob or array of globs, one of
|
58 | // which must be matched for the file to go through this transformer.
|
59 | only: 'src/**/*.js',
|
60 |
|
61 | // "except" is the opposite of only. Paths that match these globs will not
|
62 | // go through the transformer.
|
63 | except: [
|
64 | 'src/some/outlier/file.js',
|
65 | 'src/more/outliers/**/*.js'
|
66 | ],
|
67 |
|
68 | // "options" will be passed directly to the transformer.
|
69 | options: {
|
70 | presets: ['stage-0', 'es2015', 'react']
|
71 | }
|
72 | },
|
73 |
|
74 | // Impromptu transformers are as easy as specifying a function.
|
75 | {
|
76 | fn: ({file: {buffer}, options}) => ({buffer: Buffer.from(`${buffer}!`)),
|
77 | only: '**/*.exciting'
|
78 | },
|
79 |
|
80 | // Some other examples...
|
81 | {
|
82 | name: 'uglify-js',
|
83 | only: '**/*.js',
|
84 | except: '**/*+(-|_|.)min.js'
|
85 | },
|
86 | {
|
87 | name: 'sass',
|
88 | only: 'src/**/*.scss'
|
89 | },
|
90 | {
|
91 | name: 'clean-css',
|
92 | only: '**/*.+(css|scss)'
|
93 | }
|
94 | ],
|
95 |
|
96 | // Define source globs and targets here. This is where you define what to
|
97 | // transform and where it should go.
|
98 | builds: {
|
99 | 'src/index.es6': {base: 'src', dir: 'public'},
|
100 |
|
101 | 'src/public/**/*': {base: 'src/public', dir: 'public'},
|
102 |
|
103 | // Save to public dir and rename .es6 files to .js and .scss files to .css
|
104 | 'src/foo/**/*': {
|
105 | base: 'src',
|
106 | dir: 'public',
|
107 | ext: {
|
108 | '.es6': '.js',
|
109 | '.scss': '.css'
|
110 | }
|
111 | }
|
112 | }
|
113 | };
|
114 | ```
|
115 |
|
116 | ## Transformers
|
117 |
|
118 | Transformers are generally node modules that can be downloaded from npm.
|
119 | Alternatively, you can create your own transformers for your projects and
|
120 | reference them in the transformers array.
|
121 |
|
122 | [Here are some transformers to get you started](https://github.com/search?q=cogs-transformer&type=Repositories)
|
123 |
|
124 | ## Develop
|
125 |
|
126 | ```bash
|
127 | git clone git@github.com:caseywebdev/cogs
|
128 | cd cogs
|
129 | npm install
|
130 | bin/watch-test
|
131 | ```
|