Installing

npm install -g coffee-toaster

Scaffolding

There are two simple scaffolding routines bundled with CoffeeToaster for creating new projects structure from the scratch and also for creating the config toaster.coffee file for existent projects.

Initializing new app

CoffeeToaster suggests a very simple structure for initial projects, you can customize it as you like.

toaster -n mynewapp

You will be asked for some things:

source folder

Relative folderpath to your source folder, default is src.

release file

Relative filepath to your release file, default is www/js/app.js

http folder

The folderpath to reach your debug file through http, default is an empty string. Imagine that the www is your root web folder, and inside of it you have a js dir where you put your debug file. In this case you'd just need to inform 'js' as the http folder. It tells toaster how to reach your debug js file starting from the / on your server.

This property is only for debug, your release file will not be affected.

Result

Considering all the default values, you'll end up with a structure as such:

myawsomeapp/
├── src
├── vendors
├── www
    └── js
└── toaster.coffee

4 directories, 1 file

Initializing config file

You can also initialize an existing project with a config toaster.coffee file such as:

cd existing-project
toaster -i

Some of the same information (src, release and httpfolder) will be required, answer everything according to your project's structure and a config toaster.coffee file will be created inside of it.

Usage

Toaster help screen.

CoffeeToaster
  Minimalist build system for CoffeeScript

Usage:
  toaster [options] [path]

Examples:
  toaster -n myawsomeapp   (required)
  toaster -i [myawsomeapp] (optional)
  toaster -w [myawsomeapp] (optional)
  toaster -wd [myawsomeapp] (optional)

Options:
  -n, --new          Scaffold a very basic new App                   
  -i, --init         Create a config (toaster.coffee) file           
  -w, --watch        Start watching/compiling your project           
  -c, --compile      Compile the entire project, without watching it.
  -d, --debug        Debug mode (compile js files individually)      
  -a, --autorun      Execute the script in node.js after compilation
  -j, --config       Config file formatted as a json-string.           [string]
  -f, --config-file  Path to a different config file.                  [string]
  -v, --version                                                      
  -h, --help 

Import directive

The import directive is known by:

#<< app/views/user_view
#<< app/utils/*

By putting #<< app/views/user_view in your CoffeeScript file, you're telling CoffeeToaster that there's a dependency. It's like a require, except that you can't save a reference of the imported file to a variable. Instead, this directives shoud be put in the first lines of your files.

This is how you organically tells Toaster about the specific ordering options to be considered when all of your files get merged. Files imported this way will only be gracefully sorted out in your final output javascript so every file is always defined before it's needed.

Wild cards #<< app/utils/* are also accepted as a handy option.

If you're writing a class B that will extends the class A, you shoud first import the class A so it will be available for being extended by class B.

• src/app/a

class A
  constructor:->
    console.log 'Will be used as base class.'

• src/app/b

#<< app/a
class B extends A
  constructor:->
    console.log 'Using class A as base class'

Think of it as a glue that you use to chain all of your files appropriately.

Compile

Watch

Starts Toaster in watching'n'compiling mode:

cd existing-project
toaster -w

Any changes you make to your src files will trigger the compile action.

Debug

In debug mode option -d all files will be compiled individually inside a folder called toaster in the same directory you've pointed your debug file, aiming to ease the debugging process.

toaster -wd
toaster -cd

For example, if you have release/app-debug.js, a folder will be created at release/toaster and all your CoffeeScript files will be compiled to Javascript within.

Representative Structure

Bellow is a representative directory structure after compiling in debug mode.

/usage
|-- src
|   `-- app
|       |-- controllers
|       |   `-- users_controller.coffee
|       |-- models
|       |   `-- user_model.coffee
|       `-- views
|           `-- user_view.coffee
|-- www
|   `-- js
|       |-- app-debug.js
|       |-- app.js
|       `-- toaster
|           `-- app
|               |-- controllers
|               |   `-- users_controller.js
|               |-- models
|               |   `-- user_model.js
|               `-- views
|                   `-- user_view.js
`-- toaster.coffee

Every CoffeeScript file is compiled individually inside the www/js/toaster directory, so you can debug it sanely.

The debug file www/js/app-debug.js is the boot-loader responsible for loading all these individual compiled JS files into the right order.

Autorun

In autorun mode option -a the script is recompiled after each file change and it is executed in a node.js child process. It is possible to use autorun in combination with debug option -d to set the script breakpoint on the first line

toaster -a
toaster -da

of if you like the watch option

toaster -wa
toaster -wda

HTML inclusion

So in your .html you'll have two options:

1) Include your release file.

<script src="https://github.com/arboleya/coffee-toaster/raw/0.6.13/js/app.js"></script>

2) Include the toaster boot-loader (your debug mode).

<script src="https://github.com/arboleya/coffee-toaster/raw/0.6.13/js/app-debug.js"></script>

Advanced options

You can pass your own config file for toaster instead of the default one toaster.coffee, with the -f or --config-file option:

toaster -wdf config/mycustomconfig.coffee

NOTE: It's important that you always call this from your project base folder, otherwise the paths of your config can get messy. Remembers also that the paths in your config file shoud ideally be always relative to your project base folder.

Alternativelly, you can even pass the whole configuration as a JSON string, with the -j or --config option:

toaster -wdj '{"folders":{"src":""},"expose":"window","release":"app.js","debug":"app-debug.js"}'

NOTE: The same above.

Conlusion

Every time something changes, CoffeeToaster recompiles all of your application by:

• collecting all .coffee files and processing everything, adding namespace's declarations to class definitions based on the folder they are located
• reordering everything, always defining files and classes before they're needed
• merge all yours vendors in the given order
• declare root namespaces
• merge everything

VIM Users

Due to the way VIM handles files, you'll need to disable the creation of swap and backup files.

To do it, just put these three lines in your .vimrc:

" for coffee-toaster
set nobackup       " no backup files
set nowritebackup  " only in case you don't want a backup file while editing
set noswapfile     " no swap files

Config file

The toaster.coffee is the config file from where Toaster seek all information about your app, vendores, build options and so on. There are two main usages you can make of this file:

• 1) Single source folder:

When all your code is bellow one single source folder your set up the main toast call passing the folder path directly.

# src folder
toast 'src'

  # excluded items (will be used as a regex)
  exclude: ['folder/to/exclude', 'another/folder', '.DS_Store' ]

  # packaging vendors among the code
  vendors: ['vendors/x.js', 'vendors/y.js' ]

  # gereral options (all is optional, default values listed)
  bare: false
  packaging: true
  expose: '' # can be 'window', 'exports' etc
  minify: false

  # httpfolder (optional), release and debug (both required)
  httpfolder: 'js'
  release: 'www/js/app.js'
  debug: 'www/js/app-debug.js'

• 2) Multi source folder:

When your code is splitted between two or more source folders you can set the main toast call without any path, and inform your folders right bellow it.

toast
  folders:
    'src/my/app/folder': 'app'
    'src/my/lib/folder': 'lib'
    # ...

Config options

Let's take a closer look at all properties you can have in your toaster.coffee file and what each one of these is responsible of.

folders

Mandatory: no

Type: Object

Default: null

In case you have more than one src folder, you can set an object of objects containing setup information about all your source folders, in the format 'folderpath':'folderalias'.

The hash-key is the path of your folder, and the hash-value is the alias you want to prepend to all files under that.