buddy - npm Package Compare versions
Comparing version 3.0.0-beta-9 to 3.0.0
| # Changelog | ||
| **3.0.0** - Aug 2x, 2015 | ||
| * simplify configuration by removing need to define targets by type | ||
| * greatly simplify configuration by removing need to define targets by type | ||
| * replace`--targets` subcommand with `--grep <pattern>` and `--invert` subcommands and `label` parameter to specify specific targets to run | ||
| * correctly handle all configuration formats for the `package.json > browser` field, including disabling with `false` | ||
| * prevent duplication by promoting all babel helpers to global scope (via `transfigure-babel@5.8.22-3` and higher) | ||
| * no longer exit server on build error during `buddy watch --serve` | ||
| * improve inlining of deeply nested json dependencies | ||
| * parse watch-only sources to allow for more acurate server restarts | ||
| * replace `alias` configuration parameter with `package.json > browser` field configuration | ||
| * remove `init`, `ls`, and `clean` commands | ||
| * remove `server` configuration parameter | ||
| * remove support for html template precompilation | ||
@@ -20,3 +30,3 @@ **2.3.0** - Feb 11, 2015 | ||
| * compile es6 js files to vanilla es5 (use file extension `.es6`) | ||
| * properly handle module aliasing in `package.json>browser` | ||
| * properly handle module aliasing in `package.json > browser` | ||
| * default source directory derived from `input` when no sources are specified | ||
@@ -23,0 +33,0 @@ * handle all dependencies correctly, including `inline` html assets and `require('*.json')` |
@@ -101,20 +101,22 @@ 'use strict'; | ||
| function File (id, filepath, type, options) { | ||
| this.options = options; | ||
| this.type = type; | ||
| this.id = id; | ||
| this.filepath = filepath; | ||
| this.relpath = truncate(path.relative(process.cwd(), filepath)); | ||
| this.extension = path.extname(this.filepath).slice(1); | ||
| this.name = path.basename(this.filepath); | ||
| this.content = ''; | ||
| this.fileContent = ''; | ||
| this.compiledContent = ''; | ||
| this.dependencies = []; | ||
| this.dependencyReferences = []; | ||
| this.workflow = []; | ||
| this.fileContent = ''; | ||
| this.filepath = filepath; | ||
| this.headerHelpers = ''; | ||
| this.id = id; | ||
| this.isBuddyBuilt = false; | ||
| this.isBuilt = false; | ||
| this.isDependency = false; | ||
| this.isLocked = false; | ||
| this.isBuddyBuilt = false; | ||
| this.isBuilt = false; | ||
| this.options = options; | ||
| this.type = type; | ||
| this.workflow = []; | ||
| this.extension = path.extname(this.filepath).slice(1); | ||
| this.relpath = truncate(path.relative(process.cwd(), filepath)); | ||
| this.name = path.basename(this.filepath); | ||
| debug('created File instance ' + strong(this.relpath), 3); | ||
@@ -476,6 +478,7 @@ } | ||
| if (options.includeHeader) { | ||
| var usedHelpers = transfigure.getHelpers(this.type); | ||
| // Cache for life of file instance (persist across watch builds) | ||
| if (!this.headerHelpers) this.headerHelpers = transfigure.getHelpers(this.type); | ||
| if (usedHelpers) { | ||
| this.content = usedHelpers | ||
| if (this.headerHelpers) { | ||
| this.content = this.headerHelpers | ||
| + '\n\n' | ||
@@ -482,0 +485,0 @@ + this.content; |
| { | ||
| "name": "buddy", | ||
| "description": "A fast, simple build tool for js/css/html projects.", | ||
| "version": "3.0.0-beta-9", | ||
| "version": "3.0.0", | ||
| "author": "popeindustries <alex@pope-industries.com>", | ||
@@ -21,3 +21,3 @@ "keywords": [ | ||
| "csso": "1.3.11", | ||
| "eslint": "1.1.0", | ||
| "eslint": "1.2.1", | ||
| "glob": "5.0.14", | ||
@@ -41,3 +41,3 @@ "identify-resource": "5.1.1", | ||
| "rimraf": "*", | ||
| "transfigure-babel": "5.8.22-2", | ||
| "transfigure-babel": "5.8.22-3", | ||
| "transfigure-coffeescript": "*", | ||
@@ -66,4 +66,4 @@ "transfigure-dust": "*", | ||
| "readmeFilename": "README.md", | ||
| "readme": "[](https://npmjs.org/package/buddy)\n[](https://travis-ci.org/popeindustries/buddy)\n\n# buddy\n\n**buddy** is a build tool for js/css/html projects. It compiles source code from higher order js/css/html languages (*CoffeeScript, es6, JSX, Handlebars, Dust, Nunjucks, Stylus, Less, Jade, Twig*), automatically wraps js files in module definitions, statically resolves js/css/html dependencies, and concatenates (and optionally compresses) all souces into bundles for more efficient delivery to the browser.\n\n## Features\n\n- Allows you to write js __modules__ without module boilerplate (similar to node.js)\n- Resolves js __dependencies__ automatically\n- Resolves all relative dependencies\n- Supports efficient ___lazy___ runtime evaluation by storing js modules as strings\n- __Compiles__ _CoffeeScript_, __es6__, _JSX_, _Handlebars_, _Dust_, _Nunjucks_, _Stylus_, _Less_, _Twig_, and _Jade_ source files\n- __Concatenates__ js modules into file bundles\n- Runs js and css code through __linters__ to check for syntax errors\n- __Watches__ for source changes and builds automatically\n- [Add-on] __Serves__ static files from specified directory on specified port\n- [Add-on] __Restarts__ custom server after each change\n- [Add-on] __Refreshes__ connected browsers after each change\n- __Inlines__ css `@imports` automatically\n- __Inlines__ html `<script>` and `<link>` tags when flagged with `inline` attributes\n- __Inlines__ json content with `require(\"path/to/my.json\")`\n- Supports execution of a ___script___ after each build\n- Supports execution of ___hook___ scripts `afterEach` file is processed, and `before` and `after` a target is built\n\n## Installation\n\nTo avoid running **buddy** directly as a global command, and thus avoid versioning problems across different projects, it is highly recommended that you install the separate [buddy-cli](https://github.com/popeindustries/buddy-cli) command line interface system-wide:\n\n```bash\n$ npm -g install buddy-cli\n```\n\n...create a *package.json* file for each project, locally installing **buddy** as a `devDependency`:\n\n```json\n{\n \"name\": \"myproject\",\n \"description\": \"This is my web project\",\n \"version\": \"1.0.0\",\n \"devDependencies\": {\n \"buddy\": \"2.0.0\"\n },\n \"buddy\": {\n ...\n }\n}\n```\n```bash\n$ cd path/to/project\n$ npm install\n```\n\n## Usage\n\n```text\nUsage: buddy [options] <command> [path/to/package.json\n || path/to/buddy.js\n || path/to/buddy.json]\n\nCommands:\n\n build [config] build js and css sources\n watch [config] watch js and css source files and build changes\n deploy [config] build compressed js and css sources\n ls list all previously created files and directories\n clean remove all previously created files and directories\n\nOptions:\n\n -h, --help output usage information\n -V, --version output the version number\n -t, --targets [types] optional comma separated list of target(s) to build\n [js,css,html]\n -c, --compress compress output for production deployment\n -l, --lint check output for syntax and logic errors\n -r, --reload reload all connected live-reload clients on file\n change during watch [ADD-ON buddy-server]\n -s, --serve create a webserver to serve static files\n during watch [ADD-ON buddy-server]\n -S, --script run script on build completion\n -L, --lazy convert js modules for lazy evaluation\n -v, --verbose print all messages for debugging\n```\n\n## Configuration\n\nPlease refer to the annotated [configuration](https://github.com/popeindustries/buddy/blob/master/docs/config.md) file for all possible settings.\n\n## Build concepts\n\n**Project Root**: The directory from which all paths resolve to. Determined by location of the configuration file.\n\n**Sources**: An array of additional directories from which referenced files may be retrieved from. The *Project Root* and *node_modules* directories are added by default. ***Note:*** A module's id is derived from it's relative path to it's source directory.\n\n**Targets**: Objects that specify the *input* and *output* files or directories for each build. Targets are built in sequence, allowing builds to be chained together. ***Note:*** A *js* target can also have nested child targets, ensuring that dependencies are not duplicated across related builds.\n\n**Target parameters**:\n\n- **input**: file, directory, glob/expansion pattern, or array of files to build.\n\n- **output**: file, directory, or array of files to output to. *Optional*: when omitted, input files are only watched for changes (during `watch` command).\n\n- **output_compressed**: an alternate file or directory to use for compressed output.\n\n- **targets**: a nested target that prevents the duplication of source code with it's parent target (js).\n\n- **alias**: one or more id/filepath pairs to manually specify a module's id and location (js).\n\n- **modular**: a flag to prevent files from being wrapped with a module definition (js).\n\n- **before**, **after**, **afterEach**: hooks for modifying the build process (see [hooks](https://github.com/popeindustries/buddy/blob/master/docs/hooks.md))\n\n- **boilerplate**: a flag to specify inclusion of [browser-require](https://github.com/popeindustries/browser-require) source code in the output file (js).\n\n- **bootstrap**: a flag to specify that the entry-point module be automatically `require`'d to force application startup (js).\n\n- **server**: a flag to force linkage of a target to the running development/application server. Ensures that changes during `watch --reload --serve` will force a server restart (see [server]()).\n\n### Hooks\n\nIt is possible to intervene in the build process through the use of *hooks*. Hooks are assigned to specific targets and defined in the target configuration. See [hooks](https://github.com/popeindustries/buddy/blob/master/docs/hooks.md) for more details.\n\n### Aliases\n\nSpecifying aliases allow you to override the default behaviour for automatically resolving js module ids. Aliases are defined in the target configuration:\n\n```json\n{\n \"buddy\": {\n \"js\": {\n \"targets\": [\n {\n \"input\": \"somefile.js\",\n \"output\": \"somedir\",\n \"alias\": {\n \"jquery\": \"./lib/js/jquery-custom-2.0.js\",\n \"dust\": \"./node_modules/dustjs-linkedin/dist/dust-core-1.2.3.js\"\n }\n }\n ]\n }\n }\n}\n```\n```javascript\nvar jquery = require('jquery')\n , dust = require('dust');\n```\n\n## Server\n\nWhen developing locally, the **buddy-server** add-on and `buddy watch --serve` command will start a simple webserver on `localhost` to test against. Adding the `--reload` flag will enable automatic reloading of connected browsers through a [livereload](http://livereload.com) plugin. Specifying a `file` path will start/restart a custom application server instead of the default development server.\n\nInstall the add-on alongside **buddy**, and see *[buddy-server](https://github.com/popeindustries/buddy-server)* for more details.\n\n```json\n{\n \"dependencies\": {\n \"buddy\": \"2.0.0\",\n \"buddy-server\": \"1.0.0\"\n },\n \"buddy\": {\n \"server\": {\n \"port\": 8000,\n \"file\": \"./index.js\",\n \"env\": {\n \"DEBUG\": \"*\"\n }\n }\n }\n}\n```\n```bash\n$ buddy watch --serve --reload\n```\n\n## Working with JS\n\nEach JS file is wrapped in a module declaration based on the file's location. Dependencies are determined by the use of `require()` statements:\n\n```javascript\nvar lib = require('./my/lib'); // in current package\nvar SomeClass = require('../SomeClass'); // in parent package\nvar util = require('utils/util'); // from root package\nvar module = require('module'); // from node_modules\n\nlib.doSomething();\nvar something = new SomeClass();\nutil.log('hey');\n```\n\nSpecifying a module's public behaviour is achieved by decorating an `exports` object:\n\n```javascript\nvar myModuleVar = 'my module';\n\nexports.myModuleMethod = function() {\n return myModuleVar;\n};\n```\n\n...or overwriting the `exports` object completely:\n\n```javascript\nfunction MyModule() {\n this.myVar = 'my instance var';\n};\n\nMyModule.prototype.myMethod = function() {\n return this.myVar;\n};\n\nmodule.exports = MyModule;\n```\n\nEach module is provided with a `module`, `exports`, and `require` reference.\n\nWhen `require()`-ing a module, keep in mind that the module id is resolved based on the following rules:\n\n * packages begin at the root folder specified in *build > js > sources*: `'Users/alex/project/src/package/main.js' > 'package/main'`\n * ids are case-sensitive: `'package/MyClass.js' > 'package/MyClass'` (depends on platform)\n\nSee [node.js modules](http://nodejs.org/api/modules.html) for more info on modules.\n\n***NOTE***: `require()` boilerplate needs to be included in the browser to enable module loading. It's recommended to `install` a library like [browser-require](https://github.com/popeindustries/browser-require) (npm: simple-browser-require), or set the `boilerplate` target flag to have it included automatically.\n\n#### PRECOMPILED TEMPLATES\n\n*dust*, *handlebars*, *nunjucks*, and *jade* support the precompilation of templates for efficient use in the browser. See [precompiled](https://github.com/popeindustries/buddy/blob/master/docs/precompiled.md) for more details.\n\n#### \"LAZY\" MODULES\n\nWhen run with the `--lazy` flag, **buddy** supports storing js modules as strings which are only evaluated on first `require('module')` call. This can significantly speed up application startup time for large bundles, especially on mobile devices.\n\n### EXAMPLES\n\nGenerate `www/main.js` by concatenating and modularizing all dependencies in `src/js` or `libs/js` referenced in `src/js/main.js`, including modules installed via npm (under `node_modules` directory):\n\n```json\n{\n \"name\": \"myproject\",\n \"description\": \"This is my web project\",\n \"version\": \"0.1.0\",\n \"devDependencies\": {\n \"buddy\": \"2.0.0\"\n },\n \"buddy\": {\n \"build\": {\n \"js\": {\n \"sources\": [\"src/js\", \"libs/js\"],\n \"targets\": [\n {\n \"input\": \"src/js/main.js\",\n \"output\": \"www/main.js\"\n }\n ]\n }\n }\n }\n}\n```\n```javascript\n// src/main.js\nvar lodash = require('lodash') // npm module (node_modules/lodash)\n , view = require('./views/view') // src module (src/views/view.js)\n , util = require('utils/util'); // src module (libs/js/utils/util);\n```\n\nGenerate `www/main.js` and an additional widget `www/widget.js` using shared sources (avoid duplicating dependencies):\n\n```json\n{\n \"buddy\": {\n \"build\": {\n \"js\": {\n \"sources\": [\"src/js\", \"libs/js\"],\n \"targets\": [\n {\n \"input\": \"src/js/main.js\",\n \"output\": \"www/main.js\",\n \"targets\": [\n {\n \"input\": \"src/js/widget.js\",\n \"output\": \"www/widget.js\"\n }\n ]\n }\n ]\n }\n }\n }\n}\n```\n\nCompile a directory of CoffeeScript files for Node.js, skipping module wrapping and concatenation:\n\n```json\n{\n \"buddy\": {\n \"build\": {\n \"js\": {\n \"sources\": [\"src/coffee\"],\n \"targets\": [\n {\n \"input\": \"src/coffee\",\n \"output\": \"js\",\n \"modular\": false\n }\n ]\n }\n }\n }\n}\n```\n\nAlias a custom build of *jquery*:\n\n```json\n{\n \"buddy\": {\n \"build\": {\n \"js\": {\n \"sources\": [\"src/js\"],\n \"targets\": [\n {\n \"input\": \"src/js/main.js\",\n \"output\": \"www/main.js\",\n \"alias\": {\n \"jquery\": \"./lib/js/jquery-custom-2.0.js\"\n }\n }\n ]\n }\n }\n }\n}\n```\n```javascript\nvar jquery = require('jquery');\n```\n\nGenerate `www/main.js` by including `require()` boilerplate and automatically bootstraping (`require('main')`) the application:\n\n```json\n{\n \"buddy\": {\n \"build\": {\n \"js\": {\n \"sources\": [\"src/js\"],\n \"targets\": [\n {\n \"input\": \"src/js/main.js\",\n \"output\": \"www/main.js\",\n \"boilerplate\": true,\n \"bootstrap\": true\n }\n ]\n }\n }\n }\n}\n```\n\n## Working with CSS\n\nLike js modules, css dependencies are automatically resolved through parsing and inlining of `@import` directives.\n\n### Examples\n\nGenerate `www/main.css` by concatenating all dependencies in `src/css` referenced in `src/css/main.css`:\n\n```json\n{\n \"buddy\": {\n \"build\": {\n \"css\": {\n \"sources\": [\"src/css\"],\n \"targets\": [\n {\n \"input\": \"src/css/main.css\",\n \"output\": \"www/main.css\"\n }\n ]\n }\n }\n }\n}\n```\n\n## Working with HTML\n\nWhen working with *dust*, *handlebars*, *nunjucks*, or *jade* templates, dependencies (partials, includes) are automatically resolved and registered before source files are compiled to html. In addition, html files are parsed for inlineable js and css sources.\n\n### Examples\n\nResolve template partials:\n\n```html\n<!-- layout.handlebars depends on header.handlebars -->\n{{> header}}\n<body>\n ...\n <!-- ...and footer.handlebars -->\n {{> footer}}\n</body>\n```\n\nInline JS and CSS source files with `inline` attribute (see [inline-source](https://github.com/popeindustries/inline-source)):\n\n```html\n<!-- project/src/html/index.html -->\n<!DOCTYPE html>\n<html>\n<head>\n <!-- inline project/src/js/inlineScript.js -->\n <script inline src=\"../js/inlineScript.js\"></script>\n <!-- inline project/scripts/inlineScript.js -->\n <script inline src=\"/scripts/inlineScript.js\"></script>\n <!-- inline project/src/css/inlineStyle.css -->\n <link inline rel=\"../css/inlineStyle.css\"></link>\n</head>\n</html>\n```\n\n## License\n\n(The MIT License)\n\nCopyright (c) 2011-2015 Pope-Industries <alex@pope-industries.com>\n\nPermission 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:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE 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.\n", | ||
| "readme": "[](https://npmjs.org/package/buddy)\n[](https://travis-ci.org/popeindustries/buddy)\n\n# buddy\n\n**buddy** is a fast and simple build tool for js/css/html projects. It compiles source code from higher order js/css/html languages (*CoffeeScript, es6, JSX, Handlebars, Dust, Nunjucks, Stylus, Less, Jade, Twig*), automatically wraps js files in module definitions, statically resolves js/css/html dependencies, and concatenates (and optionally compresses) all souces into bundles for more efficient delivery to the browser.\n\n## Features\n\n- Allows you to write js __modules__ without module boilerplate (similar to _node.js_)\n- Resolves js __dependencies__ automatically (including those installed with `npm`)\n- Supports efficient ___lazy___ runtime evaluation by storing js modules as strings\n- __Compiles__ _CoffeeScript_, _es6_, _JSX_, _Handlebars_, _Dust_, _Nunjucks_, _Stylus_, _Less_, _Twig_, and _Jade_ source files (or others via custom __plugins__)\n- __Concatenates__ js modules into file bundles\n- Runs js and css code through __linters__ to check for syntax errors\n- __Watches__ for source changes and builds automatically\n- [Add-on] __Serves__ static files from specified directory on specified port\n- [Add-on] __Restarts__ custom server after each change\n- [Add-on] __Refreshes__ connected browsers after each change\n- __Inlines__ css `@imports` automatically\n- __Inlines__ html `<script>`, `<link>`, and `<img>` tags when flagged with an `inline` attribute\n- __Inlines__ json content with `require(\"path/to/my.json\")`\n- Supports execution of a custom ___script___ after each build\n- Supports extension via execution of ___hook___ scripts `afterEach` file is processed, and `before` and `after` a target is built\n- Supports output of unique file names\n\n## Installation\n\nTo avoid running **buddy** directly as a global command, and thus avoid versioning problems across different projects, it is recommended that you install the separate [buddy-cli](https://github.com/popeindustries/buddy-cli) command line interface system-wide:\n\n```bash\n$ npm -g install buddy-cli\n```\n\n...create a *package.json* file for each project, locally installing **buddy** as a `devDependency`:\n\n```json\n{\n \"name\": \"myproject\",\n \"description\": \"This is my web project\",\n \"version\": \"1.0.0\",\n \"devDependencies\": {\n \"buddy\": \"^3.0.0\"\n },\n \"buddy\": {\n ...\n }\n}\n```\n```bash\n$ cd path/to/project\n$ npm install\n```\n\n## Usage\n\n```text\nUsage: buddy [options] <command> [path-to-config]\n\n Commands:\n\n build [config] build js, css, and html sources\n watch [config] watch js, css, html source files and build changes\n deploy [config] build compressed js, css, and html sources\n\n Options:\n\n -h, --help output usage information\n -V, --version output the version number\n -c, --compress compress output for production deployment\n -g, --grep <pattern> only run build targets matching <pattern>\n -i, --invert inverts grep matches\n -L, --lazy convert js modules for lazy evaluation\n -l, --lint check output for syntax and logic errors\n -r, --reload reload all connected live-reload clients on file change during watch [ADD-ON buddy-server]\n -s, --serve create a webserver to serve static files during watch [ADD-ON buddy-server]\n -S, --script run script on build completion\n -v, --verbose print all messages for debugging\n```\n\n## Configuration\n\nPlease refer to the annotated [configuration](https://github.com/popeindustries/buddy/blob/master/docs/config.md) file for all possible settings, and **note that the configuration format has changed considerably as of version 3**.\n\n## Build concepts\n\n**Project Root**: The directory from which all paths resolve to. Determined by location of the configuration file.\n\n**Sources**: An array of additional directories from which referenced files may be retrieved from. The *Project Root* and *node_modules* directories are added by default. ***Note:*** A module's id is derived from it's relative path to it's source directory.\n\n**Targets**: Objects that specify the *input* and *output* files or directories for each build. Targets are built in sequence, allowing builds to be chained together. ***Note:*** A *js* target can also have nested child targets, ensuring that dependencies are not duplicated across related builds.\n\n**Target parameters**:\n\n- **input**: file, directory, glob/expansion pattern, or array of files to build.\n\n- **output**: file, directory, or array of files to output to. *Optional*: when omitted, input files are only watched for changes (during `watch` command).\n\n- **output_compressed**: an alternate file or directory to use for compressed output.\n\n- **targets**: a nested target that prevents the duplication of .js source code with it's parent target.\n\n- **modular**: a flag to prevent .js files from being wrapped with a module definition.\n\n- **before**, **after**, **afterEach**: hooks for modifying the build process\n\n- **boilerplate**: a flag to specify inclusion of [simpler-browser-require](https://github.com/popeindustries/simpler-browser-require) source code in the .js output file.\n\n- **bootstrap**: a flag to specify that the entry-point .js module be automatically `require`'d to force application startup.\n\n- **label**: an arbitrary name to use for matching when using the `--grep` subcommand\n\n### Hooks\n\nIt is possible to intervene in the build process through the use of *hooks*. Hooks are assigned to specific targets and defined in the target configuration. There are three types available:\n\n- **before**: executed before a *target* is built\n\n- **after**: executed after a *target* is built\n\n- **afterEach**: executed after an output *file* is processed, but before it is written to disk\n\nHooks can be written as inline JavaScript, or loaded from a file if a path is specified:\n\n```json\n{\n \"buddy\": {\n \"targets\": [\n {\n \"input\": \"somefile.js\",\n \"output\": \"somedir\",\n \"before\": \"console.log('before hook'); done();\",\n \"after\": \"path/to/afterHook.js\"\n }\n ]\n }\n}\n```\n\nAll hooks are passed the following arguments:\n\n- **context**: the `target` (before and after) or `file` (afterEach) instance\n\n- **options**: the runtime options used to execute buddy (`compress`, `lazy`, `reload`, `watch`, `deploy`, etc)\n\n- **done**: a callback function that accepts an optional `error`. **MUST** be called in order to return control back to the program.\n\n### Aliases\n\nWhen writing universal modules for use in both server and browser environments, it is sometimes desirable to specify an alternative entrypoint for inclusion in the browser. The alternative to the `main` *package.json* parameter is `browser`:\n\n```json\n{\n \"name\": \"myModule\",\n \"version\": \"1.0.0\",\n \"main\": \"lib/server.js\",\n \"browser\": \"lib/browser.js\"\n}\n```\n\n**buddy** correctly handles this remapping when resolving npm dependencies that use the `browser` parameter. In addition, it is possible to employ more advanced uses to alias files and modules directly in your project:\n\n```json\n{\n \"browser\": {\n \"someModule\": \"node_modules/someModule/dist/someModule-with-addons.js\"\n }\n}\n```\n\n...or even disable a module completely when bundling for the browser:\n\n```json\n{\n \"browser\": {\n \"someModule\": false\n }\n}\n```\n\nRead more about the uses of `browser` [here](https://gist.github.com/defunctzombie/4339901).\n\n### Unique filenames\n\nUnique filenames can be automatically generated by including one of two types of token in the output filename:\n\n- **%date%**: inserts the current timestamp at the time of build\n- **%hash%**: inserts a hash of the file's content\n\n```json\n{\n \"buddy\": {\n \"targets\": [\n {\n \"input\": \"somefile.js\",\n \"output\": \"somefile-%hash%.js\"\n },\n {\n \"input\": \"somefile.css\",\n \"output\": \"somefile-%date%.css\"\n }\n ]\n }\n}\n```\n\n## Server\n\nWhen developing locally, the **buddy-server** add-on and `buddy watch --serve` command will start a simple webserver on `localhost` to test against. Adding the `--reload` flag will enable automatic reloading of connected browsers through a [livereload](http://livereload.com) plugin. Specifying a `file` path will start/restart a custom application server instead of the default development server.\n\nInstall the add-on alongside **buddy**, and see *[buddy-server](https://github.com/popeindustries/buddy-server)* for more details.\n\n```json\n{\n \"dependencies\": {\n \"buddy\": \"^3.0.0\",\n \"buddy-server\": \"^1.0.0\"\n },\n \"buddy\": {\n \"server\": {\n \"port\": 8000,\n \"file\": \"./index.js\",\n \"env\": {\n \"DEBUG\": \"*\"\n }\n }\n }\n}\n```\n```bash\n$ buddy watch --serve --reload\n```\n\n## Working with JS\n\nEach JS file is wrapped in a module declaration based on the file's location. Dependencies are determined by the use of `require()` statements:\n\n```javascript\nvar lib = require('./my/lib'); // in current package\nvar SomeClass = require('../SomeClass'); // in parent package\nvar module = require('module'); // from node_modules\n\nlib.doSomething();\nvar something = new SomeClass();\nutil.log('hey');\n```\n\nSpecifying a module's public behaviour is achieved by decorating an `exports` object:\n\n```javascript\nvar myModuleVar = 'my module';\n\nexports.myModuleMethod = function() {\n return myModuleVar;\n};\n```\n\n...or overwriting the `exports` object completely:\n\n```javascript\nfunction MyModule() {\n this.myVar = 'my instance var';\n};\n\nMyModule.prototype.myMethod = function() {\n return this.myVar;\n};\n\nmodule.exports = MyModule;\n```\n\nEach module is provided with a `module`, `exports`, and `require` reference.\n\nWhen `require()`-ing a module, keep in mind that the module id is resolved based on the following rules:\n\n * packages begin at the root project directory, or those specified in *build > sources*: `'Users/alex/project/src/package/main.js' > 'src/package/main'`\n * ids are case-sensitive: `'package/MyClass.js' > 'package/MyClass'` (depends on platform)\n\nSee [node.js modules](http://nodejs.org/api/modules.html) for more info on modules.\n\n***NOTE***: `require` boilerplate needs to be present as a browser global property to enable runtime module initialization. It is necessary to include a copy of [simpler-browser-require](https://github.com/popeindustries/simpler-browser-require) (npm: simpler-browser-require), or set the `boilerplate` target flag to have it included automatically.\n\n#### \"LAZY\" MODULES\n\nWhen run with the `--lazy` flag, **buddy** supports storing js modules as strings which are only evaluated on first `require('module')` call. This can significantly speed up application startup time for large bundles, especially on mobile devices.\n\n### EXAMPLES\n\nGenerate `www/main.js` by concatenating and modularizing all dependencies referenced by `src/js/main.js`, including modules installed via npm (from the `node_modules` directory):\n\n```json\n{\n \"name\": \"myProject\",\n \"version\": \"1.0.0\",\n \"devDependencies\": {\n \"buddy\": \"^3.0.0\"\n },\n \"buddy\": {\n \"build\": {\n \"targets\": [\n {\n \"input\": \"src/js/main.js\",\n \"output\": \"www\"\n }\n ]\n }\n }\n}\n```\n```javascript\n// src/main.js\nvar lodash = require('lodash') // npm module (node_modules/lodash)\n , view = require('./views/view') // src module (src/views/view.js);\n```\n\nGenerate `www/main.js` and an additional widget `www/widget.js` using shared sources (avoiding duplicate dependencies):\n\n```json\n{\n \"buddy\": {\n \"build\": {\n \"targets\": [\n {\n \"input\": \"src/js/main.js\",\n \"output\": \"www\",\n \"targets\": [\n {\n \"input\": \"src/js/widget.js\",\n \"output\": \"www\"\n }\n ]\n }\n ]\n }\n }\n}\n```\n\nCompile a directory of ES6 files for Node.js, skipping module wrapping and concatenation:\n\n```json\n{\n \"buddy\": {\n \"build\": {\n \"targets\": [\n {\n \"input\": \"src/es6\",\n \"output\": \"js\",\n \"modular\": false\n }\n ]\n }\n }\n}\n```\n\nAlias a custom build of *jquery*:\n\n```json\n{\n \"browser\": {\n \"jquery\": \"libs/js/jquery-custom.js\"\n },\n \"buddy\": {\n \"build\": {\n \"targets\": [\n {\n \"input\": \"src/js/main.js\",\n \"output\": \"www\"\n }\n ]\n }\n }\n}\n```\n```javascript\nvar jquery = require('jquery');\n```\n\nGenerate `www/main.js` by including `require()` boilerplate and automatically bootstraping (`require('main')`) the application:\n\n```json\n{\n \"buddy\": {\n \"build\": {\n \"targets\": [\n {\n \"input\": \"src/js/main.js\",\n \"output\": \"www\",\n \"boilerplate\": true,\n \"bootstrap\": true\n }\n ]\n }\n }\n}\n```\n\n## Working with CSS\n\nLike .js modules, .css dependencies are automatically resolved through parsing and inlining of `@import` directives. ***NOTE***: unlike .js dependencies, .css dependencies are inlined, and may be inlined more than once if several `@import` directives point to the same file.\n\n### Examples\n\nGenerate `www/main.css` by concatenating all dependencies referenced in `src/css/main.css`:\n\n```json\n{\n \"buddy\": {\n \"build\": {\n \"targets\": [\n {\n \"input\": \"src/css/main.css\",\n \"output\": \"www\"\n }\n ]\n }\n }\n}\n```\n\n## Working with HTML\n\nWhen working with html or html templating languages (*dust*, *handlebars*, *nunjucks*, *jade*, etc), dependencies (partials, includes) are automatically resolved and registered before source files are compiled. In addition, files are parsed for inlineable js and css sources (those with an `inline` attribute).\n\n### Examples\n\nResolve template includes when compiling a handlebars template:\n\n```html\n<!-- layout.handlebars depends on header.handlebars -->\n{{> header}}\n<body>\n ...\n <!-- ...and footer.handlebars -->\n {{> footer}}\n</body>\n```\n\nInline .js and .css source files with `inline` attribute (see [inline-source](https://github.com/popeindustries/inline-source)):\n\n```html\n<!-- project/src/html/index.html -->\n<!DOCTYPE html>\n<html>\n<head>\n <!-- inline project/src/js/inlineScript.js -->\n <script inline src=\"../js/inlineScript.js\"></script>\n <!-- inline project/src/css/inlineStyle.css -->\n <link inline rel=\"../css/inlineStyle.css\"></link>\n</head>\n</html>\n```\n\n## License\n\n(The MIT License)\n\nCopyright (c) 2011-2015 Pope-Industries <alex@pope-industries.com>\n\nPermission 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:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE 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.\n", | ||
| "license": "MIT" | ||
| } |
@@ -6,7 +6,7 @@ [](https://npmjs.org/package/buddy) | ||
| **buddy** is a simple build tool for js/css/html projects. It compiles source code from higher order js/css/html languages (*CoffeeScript, es6, JSX, Handlebars, Dust, Nunjucks, Stylus, Less, Jade, Twig*), automatically wraps js files in module definitions, statically resolves js/css/html dependencies, and concatenates (and optionally compresses) all souces into bundles for more efficient delivery to the browser. | ||
| **buddy** is a fast and simple build tool for js/css/html projects. It compiles source code from higher order js/css/html languages (*CoffeeScript, es6, JSX, Handlebars, Dust, Nunjucks, Stylus, Less, Jade, Twig*), automatically wraps js files in module definitions, statically resolves js/css/html dependencies, and concatenates (and optionally compresses) all souces into bundles for more efficient delivery to the browser. | ||
| ## Features | ||
| - Allows you to write js __modules__ without module boilerplate (similar to node.js) | ||
| - Allows you to write js __modules__ without module boilerplate (similar to _node.js_) | ||
| - Resolves js __dependencies__ automatically (including those installed with `npm`) | ||
@@ -84,3 +84,3 @@ - Supports efficient ___lazy___ runtime evaluation by storing js modules as strings | ||
| Please refer to the annotated [configuration](https://github.com/popeindustries/buddy/blob/master/docs/config.md) file for all possible settings. | ||
| Please refer to the annotated [configuration](https://github.com/popeindustries/buddy/blob/master/docs/config.md) file for all possible settings, and **note that the configuration format has changed considerably as of version 3**. | ||
@@ -107,5 +107,5 @@ ## Build concepts | ||
| - **before**, **after**, **afterEach**: hooks for modifying the build process (see [hooks](https://github.com/popeindustries/buddy/blob/master/docs/hooks.md)) | ||
| - **before**, **after**, **afterEach**: hooks for modifying the build process | ||
| - **boilerplate**: a flag to specify inclusion of [browser-require](https://github.com/popeindustries/simpler-browser-require) source code in the .js output file. | ||
| - **boilerplate**: a flag to specify inclusion of [simpler-browser-require](https://github.com/popeindustries/simpler-browser-require) source code in the .js output file. | ||
@@ -118,4 +118,35 @@ - **bootstrap**: a flag to specify that the entry-point .js module be automatically `require`'d to force application startup. | ||
| It is possible to intervene in the build process through the use of *hooks*. Hooks are assigned to specific targets and defined in the target configuration. See [hooks](https://github.com/popeindustries/buddy/blob/master/docs/hooks.md) for more details. | ||
| It is possible to intervene in the build process through the use of *hooks*. Hooks are assigned to specific targets and defined in the target configuration. There are three types available: | ||
| - **before**: executed before a *target* is built | ||
| - **after**: executed after a *target* is built | ||
| - **afterEach**: executed after an output *file* is processed, but before it is written to disk | ||
| Hooks can be written as inline JavaScript, or loaded from a file if a path is specified: | ||
| ```json | ||
| { | ||
| "buddy": { | ||
| "targets": [ | ||
| { | ||
| "input": "somefile.js", | ||
| "output": "somedir", | ||
| "before": "console.log('before hook'); done();", | ||
| "after": "path/to/afterHook.js" | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| ``` | ||
| All hooks are passed the following arguments: | ||
| - **context**: the `target` (before and after) or `file` (afterEach) instance | ||
| - **options**: the runtime options used to execute buddy (`compress`, `lazy`, `reload`, `watch`, `deploy`, etc) | ||
| - **done**: a callback function that accepts an optional `error`. **MUST** be called in order to return control back to the program. | ||
| ### Aliases | ||
@@ -154,4 +185,28 @@ | ||
| Read more about the uses of `browser` [here](https://gist.github.com/defunctzombie/4339901). | ||
| ### Unique filenames | ||
| Unique filenames can be automatically generated by including one of two types of token in the output filename: | ||
| - **%date%**: inserts the current timestamp at the time of build | ||
| - **%hash%**: inserts a hash of the file's content | ||
| ```json | ||
| { | ||
| "buddy": { | ||
| "targets": [ | ||
| { | ||
| "input": "somefile.js", | ||
| "output": "somefile-%hash%.js" | ||
| }, | ||
| { | ||
| "input": "somefile.css", | ||
| "output": "somefile-%date%.css" | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| ``` | ||
| ## Server | ||
@@ -226,3 +281,3 @@ | ||
| * packages begin at the root folder specified in *build > js > sources*: `'Users/alex/project/src/package/main.js' > 'package/main'` | ||
| * packages begin at the root project directory, or those specified in *build > sources*: `'Users/alex/project/src/package/main.js' > 'src/package/main'` | ||
| * ids are case-sensitive: `'package/MyClass.js' > 'package/MyClass'` (depends on platform) | ||
@@ -232,3 +287,3 @@ | ||
| ***NOTE***: `require` boilerplate needs to be present as a browser global property to enable runtime module loading. It is necessary to include a copy of [simpler-browser-require](https://github.com/popeindustries/simpler-browser-require) (npm: simpler-browser-require), or set the `boilerplate` target flag to have it included automatically. | ||
| ***NOTE***: `require` boilerplate needs to be present as a browser global property to enable runtime module initialization. It is necessary to include a copy of [simpler-browser-require](https://github.com/popeindustries/simpler-browser-require) (npm: simpler-browser-require), or set the `boilerplate` target flag to have it included automatically. | ||
@@ -246,3 +301,3 @@ #### "LAZY" MODULES | ||
| "name": "myProject", | ||
| "version": "0.1.0", | ||
| "version": "1.0.0", | ||
| "devDependencies": { | ||
@@ -354,3 +409,3 @@ "buddy": "^3.0.0" | ||
| Like .js modules, .css dependencies are automatically resolved through parsing and inlining of `@import` directives. | ||
| Like .js modules, .css dependencies are automatically resolved through parsing and inlining of `@import` directives. ***NOTE***: unlike .js dependencies, .css dependencies are inlined, and may be inlined more than once if several `@import` directives point to the same file. | ||
@@ -378,3 +433,3 @@ ### Examples | ||
| When working with html or html templating languages (*dust*, *handlebars*, *nunjucks*, *jade*, etc), dependencies (partials, includes) are automatically resolved and registered before source files are compiled. In addition, files are parsed for inlineable js and css sources. | ||
| When working with html or html templating languages (*dust*, *handlebars*, *nunjucks*, *jade*, etc), dependencies (partials, includes) are automatically resolved and registered before source files are compiled. In addition, files are parsed for inlineable js and css sources (those with an `inline` attribute). | ||
@@ -381,0 +436,0 @@ ### Examples |
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
No v1
QualityPackage is not semver >=1. This means it is not stable and does not support ^ ranges.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by1.69%
118997
- Lines of code
- increased by0.08%
2425
- Number of low quality alerts
- decreased by-50%
1
- Number of lines in readme file
- increased by13.38%
466
Worsened metrics
- Number of package files
- decreased by-3.12%
31
Dependency changes
+ Addedeslint@1.2.1(transitive)
+ Addedis-resolvable@1.1.0(transitive)
- Removedeslint@1.1.0(transitive)
Updatedeslint@1.2.1