Seed project for creating AngularJS Modules

This article shows you how to start creating a new AngularJS module with re-usable components, directives & Services using a starter/seed project. The seed project can be found here

Table of Contents

• Project Structure
  • package.json
  • bower.json
  • Gulp
    • build.conf.js
    • gulpfile.js
  • ESLint
  • .gitignore
  • README.md
  • your-project-name.js
• How do I start?
  • Goal
  • Pre-requisites
  • Steps
• Manual Method
• Automated Method
• Create GitHub Repository

Project Structure

The seed project is very simple and the structure is something like this:-

• seeder
  • file.js
  • metadata-updater.js
  • repo-creator.js
• src
  • your-project-name.js
• .eslintrc.js
• .gitignore
• bower.json
• build.conf.js
• gulpfile.js
• init.js
• package.json
• README.md
• update-metadata.js

Let us take a look at the various files in the project.

package.json

This is your main project file for a NodeJS project. You can think of it being analogous to a .csprojfile or .vbprojcreated with Visual Studio. The main properties here are:-

• name– This is where you specify the name of the project. I prefer the kebaberizenaming convention here.
• private– If you don’t intend to publish your package on node, set this to true.
• version– This is the version of your package. A lot of people like to start from 0.x.y. But, I prefer to start from 1.0.0
• description– This is the description of your project. Keep it simple but meaningful so that most folks can understand it.
• repository– This is the URL to your repository. Remember, this is the URL to the actual Git (or even SVN) repository. It should not point to an HTML page of your project.
• license– The type of License for your project. Here’s the full listof all license types.
• devDependencies– This node packages are needed during the development & build stages only. Here’s the list of node packages we are going to use for the seed project.
  • bower – For using frontend JavaScript packages
  • gulp – This is our task runner that automates various painful tasks that need to be done everytime during the build process.
  • gulp- See the Gulpsection below for a list of Gulp plugins which are the actual task runners.
  • case – This is used by the metadata-updater.jsscript to create the angular project name in proper casing.
• scripts– You can run various scriptsduring the lifecycle of your package. In our case, we use the postinstallstage to install bower packages and run various tasks using Gulp.

For a full list of all properties available in package.json refer to this documentation.

bower.json

This is the manifest file for Bower where all the client side JavaScript libraries you want to use in your project must be defined. Here too you must declare the name & description for your project.

• name– This is where you specify the name of the project. I like to keep it the same as the one defined in package.json using Kebaberize naming convention.
• description– This is the description of your project. Again, same as what is in package.json.
• homepage– This should point to your project page in GitHub. Unlike the one in package.json this is not a reference to a Git repository
• main– This property is used to list the files primarily used in the project. This is what others will use in their projects when using your project as a dependency. As such, it points to our combined JS file in the dist folder (not the minified version though which is meant for production).

Gulp

Gulp helps automate various tasks needed during the build processes. It is extensible via plugins using which you can do all kinds of things using a pipelining model that is very efficient.

build.conf.js

This file contains all of the user settings for the gulp build process.

• srcJs– This refers to all the source JavaScript files that will be combined & compressed. Wildcards are supported here. Because this is a seed project for AngularJS, I have included patterns for services, components & directives directory. Along with this, the main module file should reside in the root src folder.
• buildFolder– This is the folder where the output JavaScript file will be written.
• buildJsFilename– This is the name of the output JavaScript file. All the source files found using the patterns in srcJs will be combined into this output file. Another version of this file which is minified will be generated and saved with the extension .min.js

gulpfile.js

This file contains Gulp tasks that can be run as part of the build process to perform various tasks such as combining & minifying the source JavaScript files.

It has two tasks:-

• clean– Clears the output folder.
• scripts– Combines & minifies the source JavaScript files for use in production.
• lint– Runs ESLint on our source JavaScript files to make sure that we are adhering to coding standards. Read the section on ESLintfor more information.

ESLint

The ESLint style we are going to use will extend from eslint:recommendedand because this is an AngularJS seed project – plugin:angular/johnpapa .

.gitignore

This file contains a list of all folders & files that are to be ignored by git for source control.

It has three entries:-

• node_modules– For ignoring the NodeJS modules added as dependencies for this project.
• bower_components– For ignoring the Bower modules this project is dependent upon.
• dist– This is the output folder that contains the combined & minified JavaScript file. Some people do commit it and publish it to Bower. I am still not sure on what’s the best way for this. Committing the build outputs just does not seem right to me. I’ll think of the implications when I put everything on TeamCity. But, for now, I keep it ignored.

src/your-project-name.js

This is the JavaScript file in which your angular module is declared. It declares the name of your module “your-project” along with any dependencies inside the array [].

angular.module("your-project", []);

README.md

The readme file for the seed project with instructions on how to use it to create a new project

How do I Start?

Goal

Create a new AngularJS Module

Pre-requisites

1. NodeJS– This is a JavaScript project after all. So, install Node.JS.
2. Global Node Packages
   • Bower– Because we are going to be open source JavaScript projects

     npm install -g bower

   • Gulp– This is our task runner which will be doing things like bundling, minification, linting, etc.

     npm install -g gulp

   • ESLint– To maintain code quality we will use ESLint as our JavaScript linter.

     npm install -g eslint

   • mams– The seeder binary I created for AngularJS projects.

     npm install -g mams

   Make sure you have all of these packages installed globally by running:-

   npm list -g --depth=0

   The output should include the following packages:-

   +-- bower@1.8.2
   +-- eslint@4.18.1
   +-- gulp@3.9.1
   +-- mams@1.0.5

3. Project Name:mx-angular-notify
4. Project Description:AngularJS module for showing toast notifications
5. Output JavaScript Filename: angular-notify.js
6. GitHub Access Token: 72a8a3e2b8374bcb8acaf0d0f7f4a708 (This is just an example. You must generateyour own.)

Steps

1. Go to the directory which holds your project. mamswill create a directory for your project.

   cd C:\projects

2. Generate an Access Token so that the init script can create a GitHub repository for you. See the sectionbelow to see the steps on how to generate an access token

3. Initialize your project by giving it a suitable name, description, specifying the name of your compressed/minified JavaScript file and finally providing the access token you generated in the previous step

   mams -p mx-angular-notify -d "AngularJS module for showing toast notifications" -g -t 72a8a3e2b8374bcb8acaf0d0f7f4a708

Output

You should get an output like:-

Maxotek Angular Module Seeder v 1.0.5
Creating GitHub Repository
Listing repositories
Found: 31 repositories
Created project directory: mx-angular-notify
Seeder repository: https://github.com/maxotek/mx-angular-module-seed.git
Seeder repository cloned at: mx-angular-notify
Repository created at: https://github.com/maxotek/mx-angular-notify
Project: mx-angular-notify
Description: AngularJS module for showing toast notifications
Output File: mx-angular-notify.js
Project URL: https://github.com/maxotek/mx-angular-notify
HTTPS URL: https://github.com/maxotek/mx-angular-notify.git
SSH URL: git@github.com:maxotek/mx-angular-notify.git
mx-angular-notify/package.json updated
mx-angular-notify/bower.json updated
mx-angular-notify/build.conf.js updated
Renamed project file to: mx-angular-notify/src/mx-angular-notify.js
mx-angular-notify/src/mx-angular-notify.js updated
Updated project name in: mx-angular-notify/src/mx-angular-notify.js
mx-angular-notify/.git/config updated

So, now you have an AngularJS module project locally along with a remote GitHub repository that you will be pushing to. Open up that favorite IDE of yours and start building your AngularJS module.

That is it, your new project is ready for development. If you want to go start creating your new AngularJS module. Check out my article on how to Create an AngularJS Service.

Alternatively, you can continue reading the article and understand the nitty gritty details of what’s happening under the hood.

Manual Method

Clone this repository and then change the following entires.

package.json

1. name – This is the name of your project
2. description – Give your project a meaningful description
3. repository – The URL to your GitHub repository

bower.json

1. name – This is the name of your project
2. description – Give your project a meaningful description
3. homepage – The URL to your GitHub project

build.conf.js

1. buildJsFilename – The compressed & minified name of your output JavaScript file. This is what others will include using

• Share: