Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/nickjanssen/angus

Declarative build tool for the web.
https://github.com/nickjanssen/angus

Last synced: about 1 month ago
JSON representation

Declarative build tool for the web.

Host: GitHub
URL: https://github.com/nickjanssen/angus
Owner: nickjanssen
Created: 2014-07-20T09:22:00.000Z (about 10 years ago)
Default Branch: master
Last Pushed: 2019-10-29T19:04:19.000Z (almost 5 years ago)
Last Synced: 2024-07-31T13:42:45.914Z (about 2 months ago)
Language: JavaScript
Homepage: http://slides.com/nickjanssen/declarative-build-configurations
Size: 581 KB
Stars: 211
Watchers: 11
Forks: 13
Open Issues: 10
Metadata Files:
- Readme: README.md

Awesome Lists containing this project

starred-awesome - angus - Declarative build tool for the web. (JavaScript)

README

Angus
=====

A declarative build tool for the web, favoring [convention over configuration](http://en.wikipedia.org/wiki/Convention_over_configuration).

![angus logo](http://i.imgur.com/NY8t6v2.jpg)

## Slides

Check out this [slides presentation](http://slides.com/nickjanssen/declarative-build-configurations) of what Angus is all about!

## Table Of Contents

* Introduction
* Features
* Quick Start
* Commands
* Bower
* App Structure
* Custom Tasks
* Migrating

## Introduction

Scaffolding tools such as Brunch and Yeoman are great, but are a headache when you need to build and maintain several apps. Web apps usually have the same requirements in terms of build tooling:

* Test the code
* Clean the build directory
* Copy source files to the build folder
* Do some magic tricks on your copied files, such as replacing variable names
* Compile Less or Sass files
* Dynamically generate script tags for your index.html
* Run a webserver to test out your app locally
* Watch for code changes and re-build

Having these build steps generated for you becomes a maintenance nightmare when you want to change something.

Angus solves these problems by turning the build process into something generic and reusable. It simplifies your build configuration by making it declarative, telling Angus how you'd like your sandwich instead of making the sandwich yourself. No more fiddling with Grunt/Gulpfiles!

## Features
* Pre-configured build system
* Super fast using streams
* Declarative build config
* Framework agnostic
* Easily define libraries your app is using
* Integrated connect server with pushState support
* Auto refresh when files change
* Soft CSS refresh
* Built-in unit testing (see `testRunner` config option)
* Auto-compile Sass or Less
* Automatically references scripts, templates and CSS in your `.html` files
* Easily make a production build using `angus prod` (minified and concatenated)
* Deploy directly to Amazon S3 using `angus s3`
* Serve static resources from a CDN on production
* Unique sounds on build success and break (No more boring system beeps!)
* CoffeeScript support
* Custom tasks

# Quick start
Install Angus globally with npm
```
npm install -g angus
```

Create an example app somewhere
```
angus create my-app
```

Enter the newly created app folder
```
cd my-app
```

Run the app
```
angus dev
```

Open your browser and navigate to
```
http://localhost:9000/
```

### Commands
Internally Angus uses GulpJS to do most of the work. The following commands can be invoked.
**These commands are to be run from the folder which contain your app sources.**
**Also, depending on your system, you may need to use `sudo` in front.**

### `angus create app-name [--example=example-name]`
Creates an app from one of the supplied examples (see `angus/apps/`). By default, it uses `hello-world-jquery`. You can pass in `--example=example-name` to copy from a different example app. Send in a Pull Request for more examples!

### `angus dev`
Builds and serves your app for **development**. Files will not be minified nor concatenated.

### `angus prod`
Builds and serves your app for **production**. Files will be minified and concatenated.

### `angus s3`
Builds and serves your app for **production** and **deploys it to S3**. Files will be minified and concatenated. See the `aws` object below in your `angus.config.js`.

### `angus sound on|off`
Configures Angus to use sounds on build success/failure. By default disabled.

The compiled files can be found inside the `dist/` folder.

## Bower

Bower is used to install and maintain frontend dependencies. Angus doesn't use any `bower.json` files. You should not manually use `bower` commands.

Instead, when you run the `angus dev` or `angus prod` command, Angus will tell Bower which libraries to install for your app, before starting the build.

You define Bower libraries inside your `angus.config.js` using the `bower.packages` array.

Most Bower packages contain different flavors of the actual library. These include a minified and/or production build, special feature builds as well libraries that are broken down into many smaller components, such as bootstrap. Using the `filesNeeded` array, you can define which files you actually need from the Bower packages you install.

## App structure

Apps that use Angus are structured this way:
```
hello-world/
bower_components/
src/
assets/
style/
_includes.scss <-- GENERATED
main.scss
core/
index.html
angus.config.js
```

### `angus.config.js`
This file is the heart of your app and defines what your app needs as well as a few build options. It is a `.js` and not a `.json` file on purpose so you can add comments.

It contains a few variables:
##### `bower.packages`
A list of bower dependencies this app will use. Each package will be installed using the command 'bower install [package]'.
Remember that you can also use git repo's, URL's and specify version and/or tags.
Please see the [Bower API docs](http://bower.io/docs/api/#install) for more info.
If you wish to use local library folders, please see `bower.localFolders` below.

##### `bower.filesNeeded`
An object that contains arrays of files your app will actually use from the bower packages you installed. Once Angus has installed the bower packages needed for your app, you need to define which files you will actually need from those packages. This way, Angus can automatically include them in your HTML files, generate CSS and do additional (optional) things such as AngularJS template caching.

Angus will look inside the bower_components folder for these files.
You can specify `.js`, `.css`, `.scss`, `.less` and `.html` files here. You can also specify asset files using an `assets` array. These assets will then be copied from the bower package into your `assets/` folder.

Note that you can use wildcards and exclamation marks (e.g. `my-app/**/*.js` and `!my-app/not-this-file.js`).

##### `bower.localFolders` (optional)
An array of folders in your root app directory. These folders will be symlinked to `bower_components/`, allowing you to specify additional local library files that need to be loaded using the `bower.filesNeeded` object.

For example, if you had a `customers/` folder with separate configuration JS files, you could simply add this folder `bower.localFolders = ['customers']` and then reference them inside `bower.filesNeeded.js` (e.g. `customers/disney/config.js`) so your app loads the file automatically in the order you specified.

##### `npm.packages` (optional, experimental)
A list of NPM packages this app will use. Each package will be installed using the command 'npm install [package]'.

##### `port` (optional)
The port your local server which will be listening to when running Angus. Defaults to `9000`

##### `cssCompiler` (optional)
Which CSS compiler to use. Can be `none`, `sass` or `less`.
Defaults to `sass`

##### `testRunner` (optional)
Which test runner to use. Can be `none` or `karma`.
Defaults to `karma`

##### `useJsHint` (optional)
Whether or not Angus should report JSHint errors. Angus will not break when errors are found, only warn you about them.
Defaults to `true`

##### `usesAngularJS` (optional)
When true, Angus will execute additional AngularJS specific tasks. These include `ng-annotate` and `html2js`.
Defaults to `false

##### `usesCoffeeScript` (optional)
When true, Angus will also compile `.coffee` files inside your `core/` folder.
Defaults to `false

##### `aws` (optional)
If you wish to be able to deploy to Amazon S3, you can add the `aws` object which contains these variables: `key`, `secret`, `bucket` and `region`. Run `angus s3` after you've set these up to deploy.

##### `staticServerUrl` (optional)
When given, angus will prepend all static resources with this URL on production. Common usecase is to upload your static files to a CDN (e.g. Amazon S3) and then add the URL of your bucket here.

Example `angus.config.js` file:
```
module.exports = {
bower: {
packages: [
'angular',
'bootstrap-sass-official'
],
filesNeeded: {
js: [
'angular/angular.js'
],
scss: [
// Core bootstrap variables and mixins
'bootstrap-sass-official/assets/stylesheets/bootstrap/_variables.scss',
'bootstrap-sass-official/assets/stylesheets/bootstrap/_mixins.scss'
]
}
},
port: 9001,
cssCompiler: 'sass',
testRunner: 'karma',
usesAngularJS: true
};
```

### `assets/`
Contains all images, videos, JSON files and other data which are static to your app.

### `core/`
All JavaScript files as well as additional SCSS and HTML templates go inside `src/core/` and you are free to structure them how you like (you can make sub folders). The reason this folder is called `core/` and not `js/` is that it allows you have a modular design. You can also place SASS files as well as html templates in the same folder as your javascript, to keep things organized. Sorting your app files by type (e.g. `js`, `scss`, `html`) is generally not recommended.

### `style/`
The folder for your css/sass/less files. If you're doing modular design (which you should), component specific files should be placed inside `core/` in their respective module e.g. `core/your-module/*.scss`.

One special note (Only for Sass/Less users): the `style/` folder also contains an `_includes` file which gets auto generated. This file contains a list of all Bower Sass/Less files you need specified inside `angus.config.js`.

## Custom Tasks

You can now add a `tasks/` folder in your app, to start custom tasks. These tasks are in the same format as tasks in the angus repository. Take a look at the current [angus tasks](https://github.com/nickjanssen/angus/tree/master/core/gulp) as reference. Once you add a file in your app's `tasks/` folder, they will be picked up by angus. You can then execute that task by its filename. For instance, if you added a file called `icedCoffee.js` you'd run the command `angus icedCoffee` to execute it.

Should your custom tasks require NPM dependencies, you can now make use of the `npm.packages` entry in `angus.config.js`. You may also use a conventional `package.json` file to manage your dependencies if you wish to execute `npm install` yourself.

Currently there is no way yet to integrate custom tasks into the normal angus build flow, as it's hard to tell angus when exactly to execute which tasks without making a complicated config file. If you can come up with an elegant solution please make an issue.

## Migrating
### 0.3.x → 0.4.x
Angus now uses GulpJS internally to do all its building.

Your Javascript files are now placed inside a folder `src/core/` of your app. This is done to keep your app more organised by separating style, assets and core files. It is also helpful for keeping a modular design, as you can place javascript, scss and html templates together in a folder of your choice. Please see the [Best Practice Recommendations for Angular App Structure](https://docs.google.com/document/d/1XXMvReO8-Awi1EZXAXS4PzDzdNvV6pGcuaF4Q9821Es/pub).

Html templates that are converted using the html2js plugin for AngularJS apps are now placed inside a `angus.templates.lib` module instead of `templates_lib`. Likewise, regular templates are placed inside `angus.templates.app` instead of `templates`. Please update your app dependencies accordingly. **Note that when you do not have any HTML templates or you did not include any library HTML templates, these modules will not be available.**

The `scss/` or `less/` folder inside your app was renamed to `style/`, to have a uniform folder name across different CSS compilers.

The `deploy_s3` command was renamed to `s3`.

In your `src/*.html` files (usually just `index.html`) the autoInclude syntax was changed to be consistent and easier to use:
```

```

JSHint will no longer break the build when errors when found, only warn you about them (now with helpful sounds!)

Angus will no longer re-install every bower package if it was already present inside `bower_components/`. This was done to have a faster build script. However, your dependencies may run out of date faster. Consider pruning your `bower_components` folder from time to time.

Angus now places your compiled css file inside `assets/`. This allows you to specify images without having to use `assets/` as a prefix. For example, if you had `assets/images/foo.png` this now becomes `images/foo.png`.

### 0.2.x → 0.3.x
The config file went through a drastic change. You can no longer specify which grunt tasks are ran manually. The idea is that the build config per app becomes declarative and as easy to use as possible. Instead, you now tell the `angus.config.js` which CSS compiler and test runner you'd like to use. You can also tell Angus whether you'd like to use JsHint and whether your app uses AngularJS for added functionality.

The main entry point for the CSS compiler, the main file which includes other Less/Sass files was changed from `app.scss` to `main.scss`.

(Applies to AngularJS users) The constants task was removed, as it is very easy to simply include a file where you define your constants in AngularJS. Angus will auto include this file.

### 0.1.x → 0.2.x
Angus is now installed globally via `npm`. You no longer need to clone this repository or build your apps inside its `apps/` directory. See Quick Start.

## License
MIT