Skip to content
This repository has been archived by the owner on Nov 8, 2022. It is now read-only.

Commit

Permalink
update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@popeindustries
popeindustries committed Dec 10, 2014
1 parent f9bba77 commit c3873e5
Show file tree
Hide file tree
Showing 6 changed files with 142 additions and 141 deletions.
4 changes: 1 addition & 3 deletions CHANGELOG.md
View file
@@ -1,7 +1,6 @@
# Changelog

**2.0.0** - xx, 2014
* internal re-write for node v0.12
* default source directory derived from `input` when no sources are specified
* handle all dependencies correctly, including `inline` html assets and `require('*.json')`
* properly handle node_module dependencies with different versions
Expand All @@ -10,8 +9,7 @@
* launch application server if a path is specified in `server.file` when run with `buddy watch --serve`
* target `output` is now optional, reverting to watch functionality only when run with `buddy watch`
* target `input` and `output` accept arrays of files/directories
* target `input` can be glob pattern
* make sure that references to node_modules packages are case insensitive (`require('foo') === require('FOO')`)
* target `input` can be glob/expansion pattern
* don't lint/parse prebuilt buddy or browserify bundles
* add optional boolean `server` target property to force flagging a server target for shutdown/restart during `buddy watch --reload --serve` (in most cases this can be derived from `input`)

Expand Down
143 changes: 42 additions & 101 deletions README.md
View file
@@ -1,22 +1,22 @@
[![Build Status](https://travis-ci.org/popeindustries/buddy.png)](https://travis-ci.org/popeindustries/buddy)
[![NPM Version](https://img.shields.io/npm/v/buddy.svg?style=flat)](https://npmjs.org/package/buddy)
[![Build Status](https://img.shields.io/travis/popeindustries/buddy.svg?style=flat)](https://travis-ci.org/popeindustries/buddy)

# buddy(1)
# buddy

**buddy(1)** is a build tool for js/css/html projects. It helps you manage third-party dependencies (optional add-on), compiles source code from higher order js/css/html languages (CoffeeScript/Handlebars/Dust/Stylus/Less/Jade/Twig), automatically wraps js files in module definitions, statically resolves module dependencies, and concatenates (and optionally compresses) all souces into a single file for more efficient delivery to the browser.

**Current version:** 1.3.3 *[See [Change Log](https://github.com/popeindustries/buddy/blob/master/CHANGELOG.md) for more details]*
**buddy** is a build tool for js/css/html projects. It compiles source code from higher order js/css/html languages (*CoffeeScript, 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 the module boilerplate (similar to Node.js)
- Resolves js module __dependencies__ automatically
- Supports efficient ___lazy___ runtime evaluation by storing js modules as strings
- Allows you to write js __modules__ without module boilerplate (similar to node.js)
- Resolves js __dependencies__ automatically
- Resolves all relative dependencies
- __Compiles__ _CoffeeScript_, _Handlebars_, _Dust_, _Stylus_, _Less_, _Twig_, and _Jade_ source files
- __Concatenates__ js modules into a single file
- Supports efficient ___lazy___ runtime evaluation by storing js modules as strings
- __Compiles__ _CoffeeScript_, _JSX_, _Handlebars_, _Dust_, _Nunjucks_, _Stylus_, _Less_, _Twig_, and _Jade_ source files
- __Concatenates__ js modules into file bundles
- Runs js and css code through __linters__ to check for syntax errors
- __Watches__ for source changes and builds automatically
- [Add-on] __Serves__ static files from specified directory on specified port
- [Add-on] __Restarts__ custom server after each change
- [Add-on] __Refreshes__ connected browsers after each change
- __Inlines__ css `@imports` automatically
- __Inlines__ html `<script>` and `<link>` tags when flagged with `inline` attributes
Expand All @@ -26,21 +26,21 @@

## Installation

To avoid running **buddy(1)** directly as a global command, and thus avoid versioning problems across different projects, it is highly recommended that you instead install the separate [buddy-cli](https://github.com/popeindustries/buddy-cli) command line interface system-wide:
To 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:

```bash
$ npm -g install buddy-cli
```

...run `buddy init` or manually create a *package.json* file for each project, locally installing **buddy** as a devDependency:
...run `buddy init` or manually create a *package.json* file for each project, locally installing **buddy** as a `devDependency`:

```json
{
"name": "myproject",
"description": "This is my web project",
"version": "0.1.0",
"version": "1.0.0",
"devDependencies": {
"buddy": "1.2.0"
"buddy": "2.0.0"
},
"buddy": {
...
Expand All @@ -60,7 +60,6 @@ Usage: buddy [options] <command> [path/to/package.json || path/to/buddy.js || pa
Commands:
init set up a basic buddy project
install [config] install dependencies [ADD-ON buddy-dependencies]
build [config] build js and css sources
watch [config] watch js and css source files and build changes
deploy [config] build compressed js and css sources
Expand All @@ -83,77 +82,45 @@ Options:

## Configuration

Please refer to the annotated [buddy.js](https://github.com/popeindustries/buddy/blob/master/docs/buddy.js) configuration file for all possible configuration settings.
Please refer to the annotated [configuration](https://github.com/popeindustries/buddy/blob/master/docs/config.md) file for all possible settings.

## Build concepts

**Project Root**: The directory from which all paths resolve to. Determined by location of the configuration file.

**Sources**: An array of directories from which all referenced files are retrieved from. ***Note:*** A *js* module's id is derived from it's relative path to it's source directory.
**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.

**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.

**Target parameters**:

- **input**: file or directory to build. If js (or equivalent) file, all dependencies referenced will be concatenated together for output.
If directory, all compileable files will be compiled, wrapped in module definitions (js), and output to individual js/css files.

- **output**: file or directory to output to.
- **input**: file, directory, glob/expansion pattern, or array of files to build.

- **targets**: a nested target that prevents the duplication of source code with it's parent target.

- **modular**: a flag to prevent js files from being wrapped with a module definition.
- **output**: file, directory, or array of files to output to. *Optional*: when omitted, input files are only watched for changes (during `watch` command).

- **output_compressed**: an alternate file or directory to use for compressed output.

- **before**, **after**, **afterEach**: hooks for modifying the build process (see [hooks](https://github.com/popeindustries/buddy/#hooks))

- **boilerplate**: a flag to specify inclusion of [browser-require](https://github.com/popeindustries/browser-require) source code in the output file
- **targets**: a nested target that prevents the duplication of source code with it's parent target (js).

- **bootstrap**: a flag to specify that the entry-point module be automatically `require`'d to force application startup

### Hooks
- **alias**: one or more id/filepath pairs to manually specify a module's id and location (js).

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:
- **modular**: a flag to prevent files from being wrapped with a module definition (js).

- **before**: executed before a *target* is built
- **before**, **after**, **afterEach**: hooks for modifying the build process (see [hooks](https://github.com/popeindustries/buddy/blob/master/docs/hooks.md))

- **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": {
"js": {
"targets": [
{
"input": "somefile.js",
"output": "somedir",
"before": "console.log('before hook'); done(null);",
"after": "path/to/afterHook.js"
}
]
}
}
...
}
```
- **boilerplate**: a flag to specify inclusion of [browser-require](https://github.com/popeindustries/browser-require) source code in the output file (js).

All hooks are passed the following arguments:
- **bootstrap**: a flag to specify that the entry-point module be automatically `require`'d to force application startup (js).

- **context**: the `target` (before and after) or `file` (afterEach) instance
- **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]()).

- **options**: the runtime options used to execute buddy (`compress`, `lazy`, `reload`, `watch`, `deploy`, etc)
### Hooks

- **done**: a callback function that accepts an optional `error`. **MUST** be called in order to return control back to the program.
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.

### Aliases

Specifying aliases allow you to override the default behaviour for automatically resolving JS module ids. Aliases are defined in the target configuration:
Specifying aliases allow you to override the default behaviour for automatically resolving js module ids. Aliases are defined in the target configuration:

```json
{
Expand Down Expand Up @@ -181,21 +148,21 @@ var jquery = require('jquery')

## Server

When 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 take it further by enabling automatic reloading of connected browsers through a [livereload](http://livereload.com) plugin.
When 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 take it further by enabling 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.

Install the add-on alongside **buddy**, and see *[buddy-server](https://github.com/popeindustries/buddy-server)* for more info.

```json
{
"dependencies": {
"buddy": "1.2.0",
"buddy-server": "0.4.3"
"buddy": "2.0.0",
"buddy-server": "1.0.0"
},
...
"buddy": {
"server": {
"port": 8000,
"directory": "www"
"file": "./index.js"
}
...
}
Expand Down Expand Up @@ -249,41 +216,15 @@ Each module is provided with a `module`, `exports`, and `require` reference.
When `require()`-ing a module, keep in mind that the module id is resolved based on the following rules:

* packages begin at the root folder specified in *build > js > sources*: `'Users/alex/project/src/package/main.js' > 'package/main'`
* ids are case-sensitive: `'package/MyClass.js' > 'package/MyClass'`
* ids are case-sensitive: `'package/MyClass.js' > 'package/MyClass'` (depends on platform)

See [node.js modules](http://nodejs.org/api/modules.html) for more info on modules.

***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` flag to have it included automatically.
***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.

#### PRECOMPILED TEMPLATES

*dust*, *handlebars*, and *jade* support the precompilation of templates for efficient use in the browser. **buddy** precompiles the template source, wraps the content in a module definition, and exposes a `render()` method:

```html
<!-- src/js/template.dust -->
{title}
<ul>
{#names}
<li>{name}</li>
{/names}
</ul>
```
```javascript
// src/js/main.js
var template = require('./template')
, data = {
title: 'Friends',
names: [
{name: 'Joe'},
{name: 'Bob'},
{name: 'Annie'}
]
};

template.render(data, function (err, html) {
// do something with html
});
```
*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.

#### "LAZY" MODULES

Expand All @@ -299,7 +240,7 @@ Generate `www/main.js` by concatenating and modularizing all dependencies in `sr
"description": "This is my web project",
"version": "0.1.0",
"devDependencies": {
"buddy": "1.2.0"
"buddy": "2.0.0"
},
"buddy": {
"build": {
Expand All @@ -320,7 +261,7 @@ Generate `www/main.js` by concatenating and modularizing all dependencies in `sr
// src/main.js
var lodash = require('lodash') // npm module (node_modules/lodash)
, view = require('./views/view') // src module (src/views/view.js)
, util = require('utils/util'); // src module (libs/js/utils/util)
, util = require('utils/util'); // src module (libs/js/utils/util);
```

Generate `www/main.js` and an additional widget `www/widget.js` using shared sources (avoid duplicating dependencies):
Expand Down Expand Up @@ -372,7 +313,7 @@ Compile a directory of CoffeeScript files for Node.js, skipping module wrapping
}
```

Alias a custom build of **jquery**:
Alias a custom build of *jquery*:

```json
{
Expand Down Expand Up @@ -424,7 +365,7 @@ Generate `www/main.js` by including `require()` boilerplate and automatically bo

## Working with CSS

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.

### Examples

Expand All @@ -451,7 +392,7 @@ Generate `www/main.css` by concatenating all dependencies in `src/css` reference

## Working with HTML

When working with *dust*, *handlebars*, 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.
When 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.

### Examples

Expand All @@ -467,7 +408,7 @@ Resolve template partials:
</body>
```

Inline JS and CSS source files with `inline` attribute:
Inline JS and CSS source files with `inline` attribute (see [inline-source](https://github.com/popeindustries/inline-source)):

```html
<!-- project/src/html/index.html -->
Expand All @@ -488,7 +429,7 @@ Inline JS and CSS source files with `inline` attribute:

(The MIT License)

Copyright (c) 2011-2014 Pope-Industries &lt;alex@pope-industries.com&gt;
Copyright (c) 2011-2015 Pope-Industries &lt;alex@pope-industries.com&gt;

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:

Expand Down

0 comments on commit c3873e5

Please sign in to comment.