angular-gulp-boilerplate

Why this?

There are surely many different tools and frameworks for making modern web applications. The disadvantage in my opinion is that many of these also enforce a backend and generates a lot of code that is tied to a specific backend. I also feel that the workflow itself on frontend, managing different environments and dependencies, less precompilation (less / sass) as well as packaging everything together for deployment in production (using a cdn) is lacking. This project is thus in many ways just a summary of my best practices and experiences over the last couple of years. I wanted to make this as a completely backend-agnostic project, focusing on making a boilerplate that suits highly custom and advanced single page applications, "Bring your own backend"-style.

What can this project do?

Live-reloading development server with all source files available unminified for easy debug that the workflow itself on frontend, managing different environments dependencies
Create different enviroment configurations (typicallly api, websocket endpoints etc)
Package everything into a production ready configuration - one css file, one js file and one html file, all compressed / minified
Inject CDN urls to css / html files if you use S3 or similar (Will probably add support for uploading assets to S3 as well if requested)

Why gulp, and not grunt?

To be honest, this project is mainly a result of frustration over grunt as well as my everlasting need to never stop learning new things. I have been using grunt for a long time and it is a very good tool. However, it can be slow and sequential in the execution. There is also the issue of having to use many temporary files and folders, writingand reading a lot to the file system that is expensive. With gulp, files can be retrieved and processed using streams. This means that you can apply operations all in memory, just piping the output of one operation to the next. This is very powerful and fast. Therefore, I decided to port my existing knowledge to gulp and see if it worked as expected. One advantage is that gulp is more code-oriented and is essentially just node.js scripts, making them more flexible.

Quick start

make sure that node / npm is installed (brew install node on mac, pretty simple on *nix in general)
make sure that bower is installed globally (npm install -g bower)
make sure that gulp-cli is installed globally (npm install -g bower, this will automatically use the gulp version specified in the package.json when run)
run npm install and then bower install to install all dependencies
then run gulp to package everything and start a development server

Introduction

This repository contains a pretty agnostic (although slightly opininonated) setup to create Angular.js-based single page applications (SPAs) for browsers. It is based on my work in the last years in different startups, academic work and hackatons. It provides the basic tools for developing, testing, staging and deploying single page applications.

Using angular.js enables advanced capabilities such as routing (HTML5 or hashbang), easy integrations with REST backends as well as real-time features such as websockets.

HTML5 Routing has implications for both server-side routing (what happens when you enter directly or update a link that is not /, but a link that has been generated by the javascript HTML5 History API, but does not really exist as a real endpoint?) and SEO, for handling this have a look at http://senior-java-developer.com/html5angularjsnginx-crawlable-application/ or https://github.com/meanjs/mean-seo. The basics of this is that the frontend is handling the routing, not the backend server. The semantics is then that the server will return any file requested if this exists - else it should fall back to serve the index.html file. This must also include the tag in the head to let the browser know how to change the urls accordingly. The setup is in general pretty straight forward to implement in either nginx, apache or node, whatever you prefer.

The angular UI router will handle fallback in case the browser does not support HTML5 routing to regular hashbang routing. For setups where the API is hosted on the same exact domain, there are some more config, but it should be pretty easy. I usually assume that you have one dedicated API server. This means that the web app will live at www.example.com and the API will live at api.example.com, also being consumed by mobile apps and other services.

Final note: If you take it to the extreme in terms of hosting, you can actually deploy it directly on Amazon S3 if you don't care about html5 routing and are ok with using hashbang links.

Dependency management

For handling dependencies, I have chosen to use bower, as it pretty much serves as the reference dependency management solution for frontend / web development.

Less / Css

Currently, it has been setup to use twitter bootstrap with the paper bootswatch theme (and also includes all themes from bootswatch) via bower, and using Less to handle stylesheets with gulp-autoprefixer to do browser vendor prefixing where necessary.

Module structure for angular

This is probably the most opinionated part. As a seasoned Django developer (this also goes for web applications, and usually systems in general), the notion of "apps" as components, or modules in a bigger system also makes a lot of sense for frontend development. In the src/modules folder, there are different apps, each with their specific services, routes, controllers as well as less files for styling (albeit some modules might be pure data providers without a visible user-facing frontend). Currently and example is provided.

As you can see, there is a very explicit way of defining angular modules and injecting dependencies. Although there is a bit more code to do this, it is minification safe and also allows for using namespacing of modules and their services, etc. It also seems cleaner to first define the service / config etc, then define dependencies, and later inject them into the function. There are different tools that handles minification for Angular, so if you want to use Angular's own dependency injection by parameter names, you may want to look into this.

In angular, a module must always be defined before adding services, controllers, etc to it. This is done by calling

angular.module('example', [
    'angularCharts',
    'angular-ladda',
    'chart.js',
    'mgcrea.ngStrap',
    'ui.bootstrap',
    'ui.router',
    'ui.utils'
  ])

Like this (note the squarebrackets after the module name). By convention, this file with the module definition must always be in the top level folder of each module. This is because of the import order by the includeSources that includes these files before any other module files. There are probably gulp plugins that can find the dependency graph and import the modules in correct order, but this works pretty well as far as I have seen.

The index.html file and autowiring of bower / application dependencies

The index.html file might seem a bit cryptic, and especially there are no explicit file includes. Bower components (css / js) are injected by wiredep, and includeSource is used to include the custom modules javascript and genereated css that we create.

Development mode

The main goal when developing is verbosity. This means that no minification, concatination or scrambling of source files should take place, but rather, when something goes wrong we should be able to inspect the faulty file immediately. This is exactly what the development mode does. Further, there is also live reloading using browserSync. When changing less files, the browser will actually not reload, but rather it will inject the css file. This might be useful when in deeply nested views that require some navigation to reach. For cases such as adding / deleting less, a full reload is performed because includeSource needs to update the index.html to include the added / removed css. For javascript changes, a reload is always performed. There are surely some room for improvement here, but they are mainly nice to have. I have though laid down some work in minimizing the redundant work that is done on file changes to less (i.e. only compile and inject the changed file instead of the entire bootstrap less file + custom application less). This is working pretty well.

Environments

You can make different enviroments. By running gulp environment: with the environmentName.js file, there will be generated an environmment config file for this environment. This is useful when handling local dev, staging and production.

Testing

Currently, there are only unit / functional testing using jasmine / karma, and not end-to-end tests using selenium / protractor. Run gulp test to run the tests in PhantomJS. To run karma in continous integration mode (meaning)

Building a production version

Run gulp dist. This will create a folder with all static assets such as fonts (from bootstrap and font-awesome), images, favicon.ico as well as minified / concatinated / compressed css, js and html where all the angular templates are inlined into the index file for faster retrieval and fewer requests. It will also include the CDN url specified in settings to css / html to allow you to upload static assets to a CDN.

martinsahlen / angular-gulp-boilerplate Goto Github PK