pyre

A highly opinionated application template and build system for ember applications running on express hosted in node.

Overview

As we work on multiple projects using the same pattern, we wanted to create a "universal" build system based on gulp and tailored to our specific application architecture. It provides the following features:

• An Application Template
  • Using the pods
  • Supporting multiple runtime environments and local development
• Gulp tasks for building our standard template
  • For web hosting and desktop applications
  • Use of file naming conventions to build output
  • Partial builds based on changes (when using --watch))

Installation

pyre is hosted as an NPM package.

npm install pyre

Quick Usage

New Template

Running the following command will create our application template in the current directory along with an example application. Windows:

node_modules\.bin\pyre

OSX:

node_modules/.bin/pyre

Then install all the dependencies using:

npm install

Building

In your gulpfile.js, require pyre and pass in an instance of gulp. If you created your application using the template above, this is already done for you.

var gulp = require('pyre')(require('gulp'));

To build the application, simply run the default gulp task:

gulp

// OR with a watch

gulp --watch

// OR using local data

gulp --data

// OR with a watch and local data

gulp --watch --data

Running

To run the application as a web host, run the following command:

gulp host

To run the application as a desktop application, run the following command:

gulp exe

Packaging

To package the application as an exe and zip it for deployment, run the following command:

gulp package

Publishing

To deploy the application to GitHub and/or NPM run the following command:

gulp publish

TODO: document environment variables required NPM_AUTH_TOKEN NPM_EMAIL GITHUB_USER GITHUB_TOKEN GITHUB_OWNER GITHUB_PROJECT

Documentation

Naming Conventions

pyre uses the following naming conventions to help to determine the format of the build output:

• Desktop output is placed in /.bin/desktop
• Server output is placed in /.bin/desktop
• Files used universally by the application should be placed in the /app folder
• Files used to override functionality for a given environment (i.e. desktop) should be placed in the /desktop or /server folder
• All *.js files in the app folder are combined and minified into one /.bin/index.js output
  • unless preceded by .api, .data, .ignore, or .resource
• All .less files are compiled and minified directly to /.bin/index.css in hieratical order
• All .hbs files are wrapped in javascript and compined directly to /.bin/templates.js
• All bower packages with *.js files are combined and minified into one /.bin/libraries.js output
• All .html, .eot, .svg, .ttf, .woff, .otf, .png, and .ico files are copied directly to /.bin
• Files proceeded by .api are copied directly to /.bin/desktop/api and /.bin/server/api to be loaded at runtime
• Files proceeded by .data are copied directly to /.bin/desktop/data and /.bin/server/data to be loaded for local development
• Files proceeded by .ignore are skiped during the build process but not by --watch
• Files proceeded by .resource are copied directly to /.bin/desktop and /.bin/server

What are "pods"?

Pods are a way of grouping files in a project by feature (ex: Task) rather than by type (ex: controllers). This has several advantages:

• Provides a simple mental model of the application through structure
• Promotes modular thinking
• Reduces code search to find a feature or concept

Type Based Structure

• app/controllers
  • task.js
  • user.js
• app/templates
  • task.hbs
  • user.hbs
• app/styles
  • task.less
  • user.less
• app/api
  • task.js
  • user.js
• app/data
  • task.js
  • user.js

In an application strucutre based on types with only two features (user and task), even this seems a bit complex to navitage. Now picture what this looks like with 10 or 20 different features.

Pods (modified)

• app/task
  • task.api.js
  • task.data.js
  • task.hbs
  • task.js
  • task.less
• app/user
  • user.api.js
  • user.data.js
  • user.hbs
  • user.js
  • user.less

In this case, as more and more features are added to our application, we are able to mentally focus our attention on just one feature (folder) at a time as all the code for that feature exists under one folder. Additionally, by looking at only the folder structure we can maintain a good mental model about what the application does.