Node Angular Starter

I created this as a base for any project that uses an AngularJS frontend and a Node.js / Express backend.

The main goal of this project is to employ a build process that functions elegantly in development without getting in the way and then smoothly transitions into a tightly packed and efficient production package.

The other goal of this project is to structure application source files in a logical and organized way.

I will discuss the means to these goals further in the sections below.

Setup

Initial Steps

Install Node.js.

Install Bower and Gulp globally:

$ sudo npm -g install bower gulp

Clone the Git repository and install the dependencies:

$ git clone git://github.com/kylepixel/node-angular-starter
$ cd node-angular-starter
$ npm install
$ bower install

Now everything's set up and ready to go. Read on for how to build the project and run the server.

Build Process

This project uses Gulp for its build process and has a number of Gulp tasks available.

The compile task will build the project for production. This means concatenating and minifying all source files into a single JS file and a single CSS file, as well as compressing image assets. The default Gulp task also runs the compile task and is exactly equivalent:

$ gulp compile

$ gulp

The build task will build the project for development. This means that all files will be kept separate (CSS is a special case and will be concatenated into a single file) and will remain untouched for a quick build and easy debugging and analysis:

$ gulp build

The watch task will run the build task and then watch the application files for changes. Whenever changes are made, the build files will be updated appropriately and live reload will be triggered:

$ gulp watch

The serve task will run the watch task. It will also start the server in development mode on the default port (defined in package.json) and then watch the server files for changes. Whenever changes are made, the server will restart itself and live reload will be triggered:

$ gulp serve [--port=<port>]

If the --port flag is included with a valid port number, the server will be started on the specified port. Otherwise, it will start on the default port which is defined in the config section of package.json.

Running the Server

The server can be started manually with the following command:

$ npm start [--dev] [--port=<port>]

If the --dev flag is included, the server will be started in development mode and will serve files generated by the gulp build command which are in the /build directory by default. If the flag is not included, the server will start in production mode and will serve files generated by the gulp compile command which are in the /dist directory by default.

If the --port flag is included with a valid port number, the server will be started on the specified port. Otherwise, it will start on the default port which is defined in the config section of package.json.

Live Reload

node-angular-starter also includes Live Reload. Download the addon for your browser at the following locations:

• Chrome - Chrome Webstore
• Firefox - Download from Live Reload
• Safari - Download from Live Reload
• Internet Explorer - N/A

When you load your page, click the Live Reload icon in your toolbar and everything should work.

Directory Structure

node-angular-starter/
  |- src/
  |  |- assets/
  |  |  |- <static files>
  |  |- components/
  |  |  |- <reusable code>
  |  |- states/
  |  |  |- <app logic>
  |  |- app.js
  |  |- app.less
  |  |- index.html
  |- server/
  |  |- server.js
  |- .jshintrc
  |- bower.json
  |- build.config.js
  |- gulpfile.js
  |- package.json

Making Changes

I'm going to outline some important concepts here for making changes to this project.

Build Configuration

The build.config.js file in the project root contains configurable properties that are used in the project's build process. These properties will be reviewed here.

vendor_dir: The directory to which Bower dependencies are downloaded. vendor_files: The specific vendor files that should be included in the build process (in order), the starting root of the filepath being the vendor_dir.

source_files: The source files for the application. You shouldn't need to touch these but they are there for your convenience.

build_dir: The directory to which the development version of the project should be built. compile_dir: The directory to which the production version of the project should be built.

Notes

If you want to add or remove a Bower dependency in the build, it must be updated in the vendor_files section of the build config.

By default, the only less file processed is source_files.less.entry in the build config. This defaults to src/app.less. I work by making sure all files are linked to this one by @import statements. This also helps reinforce the dependency structure established by the application's JS structure. Feel free to change this however you see fit so that it works for you.

All assets (i.e. images, video, etc.) should be placed in the src/assets folder. Feel free to organize them within this folder however you like. The folder structure will be preserved.

Never forget how important module dependencies are. If you add a state or a component, don't forget to add it to the module's dependencies.

I'll let you figure out some of the linking by looking at the example project that's in place. To link assets from the LESS, the URL should just be 'assets/file/path/here.jpg'. Template URLs for new states are the full path from 'src' (not including 'src').