NeptuneCoffee

What is it?

  • opinionated javascript-AMD-module generator

Purpose

  • make working with javascript AMD modules easier
  • minimize refactoring complexity
  • minimize the amount of code you have to write
  • integrate easily with javascript or coffeescript projects

If you are working with dozens or hundreds of Javascript files, wouldn't you like some way to easily organize them into modules?

NeptuneCoffee is an opinionated module generator. Modules and namespaces are automatically generated based on the project's directory names and structure.

NeptuneCoffee generates the .js files to define your AMD modules.

Opinionated?

NeptuneCoffee has an opinion about how you should organize your javascript for AMD modules. It is:

  • Directories are AMD modules
  • Directory's name defines the AMD module's name
  • Directory names should be snake_case
  • module js files return classes to be attached to their directory's namespace
  • generated AMD module names will be CamelCase
  • require "foo/bar" includes all files in the module defined by the directory "foo/bar"
  • Defines a hierachical namespace based on module names and directory structure nesting

Benefit

Refactoring module structure is as simple as renaming and moving directories and files. Often you won't have to change a line of code.

What does it do?

For every $subdir, NeptuneCoffee generates:

$subdir/namespace.js  // defines $subdir's namespace object
$subdir.js            // loads all .js files in $subdir recursively
                      // all three files return $subdir's namespace object

How to Use

Install neptune_coffee (see below). Then, whenever your directory structure changes or you move/add/rename/delete files, run:

neptune_coffee -r source/root
  • Client should require: $subdir.js for the AMD module source/root/$subdir
  • Source files in source/root/$subdir/ should require: ./namespace.js

Example

Given this directory structure and files:

geometry/solids/cone.js
geometry/box.js
geometry/circle.js

NeptuneCoffee generates:

geometry.js
geometry/namespace.js
geometry/solids.js
geometry/solids/namespace.js

geometry.js might look like:

// Generated by NeptuneCoffee 0.2.0
define([
  './geometry/namespace',
  './geometry/box',
  './geometry/circle',
  './geometry/solids'
], function(Geometry, Box, Circle) {
  Geometry.Box = Box; Box.namespace = Geometry;
  Geometry.Circle = Circle; Circle.namespace = Geometry;
  return Geometry;
});

See examples for a complete and current before & after example.

Installation

Add this line to your application's Gemfile:

gem 'neptune_coffee'

And then execute:

$ bundle

Or install it yourself as:

$ gem install neptune_coffee

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request