scroungejs

(c)Bumblehead, 2012,2013 MIT-license

OVERVIEW:

Scroungejs is a javascript program that processes .js and .css files. With it you may compress, concatenate and/or timestamp your files as part of a build process for your web site. It is made to be as flexible as possible and its features are selectively enabled as needed. Scroungejs concatenates files in an ordered way -each file appears after the files that it depends on.

Scroungejs provides advantages over other deployment tools:

• usable as a command line tool -no config file or framework.
• callable from a javascript file using node.js.
• it does not interfere with the node.js requirejs module system.
• compression and concatenation are enabled/disabled for each build.
• html files do not need unusual tags or attributes added to them.
• it works with almost any collection javascript files.
• by default, it does not add javascript to the files that it generates.
• it is packaged with an emacs config file.

Scroungejs relies on other packages, notably: css-clean and js-uglify.

Get Started with scroungejs to learn more.

INSTALL:

Scroungejs may be downloaded directly or installed through npm.

• npm

$ npm install scroungejs

• Direct Download

$ git clone https://github.com/iambumblehead/scroungejs.git
$ cd scroungejs && npm install

GET STARTED:

1. Before Starting...

* **shell**   

> `$ node ./scrounge.js \`  
> `  --inputPath=./getStarted \`   
> `  --isTimestamped=true \`  
> `  --isCompressed=true`   

* **javascript file**

> `var scroungejs = require('scroungejs');`  
>    
> `scroungejs.build({`  
>     `inputPath : './getStarted',`  
>     `isTimestamped : true,`  
>     `isComressed : true`  
> `}, function (err, res) {`  
>     `if (err) return console.log(err);`  
>     `console.log('finished!')`  
> `});`

The directory named 'getStarted' and its contents are provided with the Scrounge package.

3. Use compression and timestamping modifiers.

$ node ./scrounge.js -i ./getStarted \
--isTimestamped=true --isCompressed=true
[...] open: getStarted/fileB.js
[...] open: getStarted/fileA.js
[...] ugly: (1/2) getStarted/fileB.js
[...] write: getStarted/cmpr/fileB_2012.07.07-15:25:57.js
[...] ugly: (2/2) getStarted/fileA.js
[...] write: getStarted/cmpr/fileA_2012.07.07-15:25:46.js
[...] finish: 00:00:25 (mm:ss:ms)

4. Define a dependency in fileB.js.

scroungejs will concatenate dependency-related files. Dependencies are defined in .js and .css files using the 'Requires' property.

Open fileB.js and add the following line to the top: // Requires: fileA.js.

./getStarted/fileB.js:

// Requires: fileA.js

File properties are explained in section File Properties.

5. Concatenate files

Dependency-related files are recognized as a tree. A tree is composed of one file that depends on other files 'and so on. A file that begins a dependency is a tree source file. Here, fileB.js is a source file.

$ node ./scrounge.js -i ./getStarted --isConcatenation=true
[...] open: getStarted/fileB.js
[...] open: getStarted/fileA.js
[...] ugly: (fileB.js 1/2) getStarted/fileA.js
[...] ugly: (fileB.js 2/2) getStarted/fileB.js
[...] write: getStarted/cmpr/fileB.js
[...] finish: 00:00:27 (mm:ss:ms)

7. More File Properties.

Define a few more properties at the top of the file

./getStarted/fileB.js:

// Filename: fileB.js
// Timestamp: 2011.06.03
// Author(s): Bumblehead
// Requires: fileA.js

Add '// Requires: fileB.js' to a file to create a dependency on fileB.js.

File properties are explained in section File Properties.

6. Specify an Output Directory

If it does not exist, the output path is created.

$ node ./scrounge.js -i ./getStarted --isConcatenation=true \
--outputPath=./app/public/cmpr [...] open: getStarted/fileB.js
[...] open: getStarted/fileA.js
[...] ugly: (fileB.js 1/2) getStarted/fileA.js
[...] ugly: (fileB.js 2/2) getStarted/fileB.js
[...] write: app/public/cmpr/fileB.js
[...] finish: 00:00:27 (mm:ss:ms)

6. Build a larger tree found in ./getStarted/app/.

Multiple trees may be discovered and concatenated and .css files that associate with a tree are concatenated as well.

$ node ./scrounge.js -i ./getStarted/app --isConcatenation=true \
--outputPath=./app/public/cmpr --isRecursive=true
[...] open: getStarted/app/app.js
[...] open: getStarted/app/app2.js
[...] open: getStarted/app/controls/CtrlA.js
[...] open: getStarted/app/controls/CtrlB.js
[...] open: getStarted/app/controls/CtrlsAll.js
[...] open: getStarted/app/lib/library.js
[...] open: getStarted/app/models/ModelA.js
[...] open: getStarted/app/models/ModelB.js
[...] open: getStarted/app/views/ViewA.css
[...] open: getStarted/app/views/ViewA.js
[...] open: getStarted/app/views/ViewB.js
[...] open: getStarted/app/views/ViewsAll.js
[...] join: (app.js 1/9) getStarted/app/models/ModelB.js
[...] join: (app.js 2/9) getStarted/app/controls/CtrlB.js
[...] join: (app.js 3/9) getStarted/app/models/ModelA.js
[...] join: (app.js 4/9) getStarted/app/controls/CtrlA.js
[...] join: (app.js 5/9) getStarted/app/controls/CtrlsAll.js
[...] join: (app.js 6/9) getStarted/app/views/ViewB.js
[...] join: (app.js 7/9) getStarted/app/views/ViewA.js
[...] join: (app.js 8/9) getStarted/app/views/ViewsAll.js
[...] join: (app.js 9/9) getStarted/app/app.js
[...] write: app/public/cmpr/app.js
[...] join: (app2.js 1/1) getStarted/app/app2.js
[...] write: app/public/cmpr/app2.js
[...] join: (library.js 1/1) getStarted/app/lib/library.js
[...] write: app/public/cmpr/library.js
[...] join: (ViewA.css 1/1) getStarted/app/views/ViewA.css
[...] write: app/public/cmpr/ViewA.css
[...] finish: 00:00:13 (mm:ss:ms)

6. Define filters for the build process.

When --extensionType=js is given, files without a js extension are ignored by the build process.

$ node ./scrounge.js -i ./getStarted/app --isConcatenation=true \
--outputPath=./app/public/cmpr --isRecursive=true --extensionType=js
[...] open: getStarted/app/app.js
[...] open: getStarted/app/app2.js
[...] open: getStarted/app/controls/CtrlA.js
[...] open: getStarted/app/controls/CtrlB.js
[...] open: getStarted/app/controls/CtrlsAll.js
[...] open: getStarted/app/lib/library.js
[...] open: getStarted/app/models/ModelA.js
[...] open: getStarted/app/models/ModelB.js
[...] open: getStarted/app/views/ViewA.js
[...] open: getStarted/app/views/ViewB.js
[...] open: getStarted/app/views/ViewsAll.js
[...] join: (app.js 1/9) getStarted/app/models/ModelB.js
[...] join: (app.js 2/9) getStarted/app/controls/CtrlB.js
[...] join: (app.js 3/9) getStarted/app/models/ModelA.js
[...] join: (app.js 4/9) getStarted/app/controls/CtrlA.js
[...] join: (app.js 5/9) getStarted/app/controls/CtrlsAll.js
[...] join: (app.js 6/9) getStarted/app/views/ViewB.js
[...] join: (app.js 7/9) getStarted/app/views/ViewA.js
[...] join: (app.js 8/9) getStarted/app/views/ViewsAll.js
[...] join: (app.js 9/9) getStarted/app/app.js
[...] write: app/public/cmpr/app.js
[...] join: (app2.js 1/1) getStarted/app/app2.js
[...] write: app/public/cmpr/app2.js
[...] join: (library.js 1/1) getStarted/app/lib/library.js
[...] write: app/public/cmpr/library.js
[...] finish: 00:00:12 (mm:ss:ms)

Other modifiers are explained in section Modifiers.

8. Update index.mustache using scroungejs.

The index file contains a scrounge element.

 - *./getStarted/index.mustache* 

 > `<!doctype html>`  
 > `<html>`  
 > &nbsp;&nbsp;`<head>`  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<script src="/scr/libFile.js" type="text/javascript"></script>`  
 > &nbsp;&nbsp;`</head>`  
 > &nbsp;&nbsp;`<body>`  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<!-- <scrounge.js> -->`  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<!-- </scrounge> -->`  
 > &nbsp;&nbsp;`</body>`  
 > `</html>`  
 

9. modify the basepage index.mustache with scroungejs

Call scroungejs without concatenation on the basepage.

using -s makes the output 'silent'

$ node ./scrounge.js -s -i ./getStarted/app \
--basepage=./getStarted/index.mustache --isRecursive=true \
--outputPath=./app/public/cmpr

 - *./getStarted/index.mustache* 

 > `<!doctype html>`  
 > `<html>`  
 > &nbsp;&nbsp;`<head>`  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<script src="/app/lib/library.js" type="text/javascript"></script>`  
 > &nbsp;&nbsp;`</head>`  
 > &nbsp;&nbsp;`<body>`  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<!-- <scrounge.js> -->`  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<script src="/app/public/cmpr/library.js" type="text/javascript"></script>`  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<script src="/app/public/cmpr/app2.js" type="text/javascript"></script>`  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<script src="/app/public/cmpr/ModelB.js" type="text/javascript"></script>`  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<script src="/app/public/cmpr/CtrlB.js" type="text/javascript"></script>`  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<script src="/app/public/cmpr/ModelA.js" type="text/javascript"></script>`  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<script src="/app/public/cmpr/CtrlA.js" type="text/javascript"></script>`  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<script src="/app/public/cmpr/CtrlsAll.js" type="text/javascript"></script>`  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<script src="/app/public/cmpr/ViewB.js" type="text/javascript"></script>`  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<script src="/app/public/cmpr/ViewA.js" type="text/javascript"></script>`  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<script src="/app/public/cmpr/ViewsAll.js" type="text/javascript"></script>`  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<script src="/app/public/cmpr/app.js" type="text/javascript"></script>     `  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<!-- </scrounge> -->`  
 > &nbsp;&nbsp;`</body>`  
 > `</html>`      
 

11. modify the basepage index.mustache and use concatenation.

Call scroungejs with concatenation on this basepage. scroungejs correctly modifies the basepage for concatenated files.

$ node ./scrounge.js -s -i ./getStarted/app --isConcatenation=true \
--basepage=./getStarted/index.mustache --isRecursive=true \
--outputPath=./app/public/cmpr

 - *./getStarted/index.mustache* 

 > `<!doctype html>`  
 > `<html>`  
 > &nbsp;&nbsp;`<head>`  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<script src="/app/lib/library.js" type="text/javascript"></script>`  
 > &nbsp;&nbsp;`</head>`  
 > &nbsp;&nbsp;`<body>`  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<!-- <scrounge.js> -->`  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<script src="/app/public/cmpr/library.js" type="text/javascript"></script>`  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<script src="/app/public/cmpr/app2.js" type="text/javascript"></script>`  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<script src="/app/public/cmpr/app.js" type="text/javascript"></script>`  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<!-- </scrounge> -->`  
 > &nbsp;&nbsp;`</body>`  
 > `</html>`      

11. define a public path and update index.mustache.

This index page may reference a root web directory served from app/public. In this case, files copied to /app/public/cmpr/ should be accessed through the path /cmpr.

Scroungejs will modify a basepage to reference scripts from a publicPath.

$ node ./scrounge.js -s -i ./getStarted/app --isConcatenation=true \
--basepage=./getStarted/index.mustache --isRecursive=true \
--outputPath=./app/public/cmpr --publicPath=/cmpr

 - *./getStarted/index.mustache*  

 > `<!doctype html>`  
 > `<html>`  
 > &nbsp;&nbsp;`<head>`  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<script src="/app/lib/library.js" type="text/javascript"></script>`       
 > &nbsp;&nbsp;`</head>`  
 > &nbsp;&nbsp;`<body>`  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<!-- <scrounge.js> -->`  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<script src="/cmpr/library.js" type="text/javascript"></script>`   
 > &nbsp;&nbsp;&nbsp;&nbsp;`<script src="/cmpr/app.js" type="text/javascript"></script>`  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<script src="/cmpr/app2.js" type="text/javascript"></script>`  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<!-- </scrounge> -->`  
 > &nbsp;&nbsp;`</body>`  
 > `</html>`      

13. define tree attributes.

If a tree attribute is defined in a scrounge element, only the file or files that result from the named tree are added to the scrounge element.

Trees may be defined in a scrounge element attribute or by using the --trees modifier. When trees are defined, scrounge will output the defined trees only.

 - *./getStarted/index.mustache* 

 > `<!doctype html>`  
 > `<html>`  
 > &nbsp;&nbsp;`<head>`  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<script src="/app/lib/library.js" type="text/javascript"></script>`            
 > &nbsp;&nbsp;&nbsp;&nbsp;`<!-- <scrounge.css trees="app.js"> -->`       
 > &nbsp;&nbsp;&nbsp;&nbsp;`<!-- </scrounge> -->`       
 > &nbsp;&nbsp;`</head>`  
 > &nbsp;&nbsp;`<body>`  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<!-- <scrounge.js trees="app.js"> -->`  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<!-- </scrounge> -->`  
 > &nbsp;&nbsp;`</body>`  
 > `</html>`  
      

$ node ./scrounge.js -s -i ./getStarted/app \ --basepage=./getStarted/index.mustache --isRecursive=true --publicPath=/cmpr

 - *./getStarted/index.mustache* 

 > `<!doctype html>`  
 > `<html>`  
 > &nbsp;&nbsp;`<head>`  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<script src="/app/lib/library.js" type="text/javascript"></script>`                 
 > &nbsp;&nbsp;&nbsp;&nbsp;`<!-- <scrounge.css trees="app.js"> -->`       
 > &nbsp;&nbsp;&nbsp;&nbsp;`<script src="/cmpr/app.css" type="text/javascript"></script>`  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<!-- </scrounge> -->`       
 > &nbsp;&nbsp;`</head>`  
 > &nbsp;&nbsp;`<body>`  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<!-- <scrounge.js trees="app.js"> -->`  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<script src="/cmpr/app.js" type="text/javascript"></script>`  
 > &nbsp;&nbsp;&nbsp;&nbsp;`<!-- </scrounge> -->`  
 > &nbsp;&nbsp;`</body>`  
 > `</html>`       

15. You are now ready to use scroungejs.

FILE PROPERTIES:

Each file processed by scroungejs may affect the build process. This is done through information added to each file.

BASEPAGE:

scroungejs may add include elements for the js and css files it processes. Only a basepage that contains one or more scrounge elements will be modified.

MODIFIERS:

• --inputPath=inputpath, -i inputpath
  a systempath to a directory or file. the default inputpath value is './'.

• --outputPath=outputpath, -o outputpath
  a systempath to a directory or file. the default outpupath value is './cmpr'.

• --publicPath=public/path/to/files, -p public/path/to/files
  a path to the files created by scrounge.

  a valid public path is discoverable on the full system path to the file. for example, /cmpr is found on the path ./getStarted/app/cmpr/app.js.

  this file's full public path would be /cmpr/app.js.

  a public path is not useful without a -basepage argument as it affects only paths generated for the specified basepage.

• --isBasepageSourcePaths=bool
  basepage include tags will reference scripts in source directory. disables compression, concatenation and copying of files. uses publicPath

  ex.

  $ node scrounge.js -l --isRecursive=true --isBasepageSourcePaths=true \
--basepage=~/Software/kuaweb/sources/index.html \
--inputPath=~/Software/kuaweb/sources/appSrc --publicPath=/appSrc

• --isCompressed=bool
  compress all files and trees before writing them to disk.

• --isRecursive=bool
  discover files in nested directories on the given path.

• --isWarning=bool
  raise warnings around trace statements.

• --isLines=bool
  each compressed script on its own line.

• --isClosure=bool
  compressed js code will added in the body of anonymous self-calling function.

• --isSilent=bool, -s
  supress console messages.

• --isMintFilter=bool
  only process files that include _mint in their filename. this should only be used for the special case when a build directory has many files that should not be included in the build process. _mint distinguishes a file that should be included in the build process from a file that should not be included in the build process.

• --isTimestamped=bool
  add a timestamp to name of the output files.

• --isRemoveRequires=bool
  remove 'requires' statements from javascript files. true by default.

• --isRemoveConsole=bool
  remove 'console' statements from javascript files. false by default.

• --isUpdateOnly=bool
  modify include tags in a basepage only. do not build scrounge elements.

• --extensionType=type, -t type
  process files of one type only, js or css.

• --forceConcatenateTrees=tree1,tree2
  force the concatenation of specified trees.

• --forceConcatenateTypes=type1,type2
  force the concatenation of js and/or css files.

• --forceTimestamp=timestamp
  all timestamped files will use the given timestamp.

• --basepage=basepage, -b basepage
  update scrounge tags in the defined basepage.

  scroungejs will not modify or process a file that does not contain scrounge tags.

License:

Copyright (c) 2012 Bumblehead chris@bumblehead.com

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.