Modern app seed for legacy Angular apps (1.x)

Table of Contents

• Modern app seed for legacy Angular apps (1.x)
• Table of Contents
• What is this
  • Includes following
  • Application specified stuff
• Installation, configure and usage
  • Preconditions
  • Installation
  • Configuration
  • Usage
• Getting started
• Usage advice
  • Directory layout
  • Backend
    • Endpoints / actions:
    • JWT handling
    • CORS support
    • Example backend
  • Angular specific conventions
  • Directives
• Author
• License

What is this

Modern seed for "legacy" Angular (1.x) applications. With seed this you can use ES2015 to write your frontend application.

Includes following

• webpack (modules, assets bundling)
• babel (ES2015 support)
• ng-annotate
• UI-Router
• Angular Material
• angular-jwt
• karma test runner configuration

Application specified stuff

• Blocks; Exception handling, Logger, Router
• Auth; Login, Authorization, User roles with routes
• Common; HTTP error interceptor,

Installation, configure and usage

Preconditions

First of all you have to install npm and node.js to your box - note that NodeJS 6+ is required. See following links to help you with installation:

• Installing Node.js via package manager
• Node Version Manager

Installation

Open your shell/terminal and navigate to root of application folder and run following command:

npm install

Configuration

Copy [./src/config/config.json_example](./src/config/config.json_example) file to ./src/config/config.json and make necessary changes to it.

Usage

Application contains following commands that you can use

• npm run dev-server => starts dev servers, open http://localhost:3000
• npm run lint => Lint your code under .src folder
• npm run test => Run unit tests
• npm run build => create build for production deployment, output will be generated to dist folder
• npm run build-dev => create build for development deployment, output will be generated to public folder

Getting started

• Angular Guide
• Angular Style Guide
• Angular 1.x styleguide (ES2015)
• Tutorial from BabelJS
• Exploring ES6: Upgrade to the next version of JavaScript by Dr. Axel Rauschmayer
• Airbnb JavaScript Style Guide
• webpack documentation

Usage advice

Directory layout

├── build                               # build stats
├── public                              # public folder (webroot for dev server)
│   ├── _assets                         # build results - assets packed by webpack
│   └── index.html                      # one of app entry points, for dev server
└── src                                 # app sources
    ├── blocks                          # generic helpers
    │   ├── exception                   # exception handler
    │   ├── logger                      # logger
    │   └── router                      # router helper
    ├── core                            # application core module
    │   ├── auth                        # core.auth module, contains all authentication / authorization related stuff
    │   ├── interceptors                # core.interceptors module, contains core interceptors
    │   ├── services                    # core.services module, contains core services
    │   ├── 404.html                    # not found page template
    │   ├── core.config.js              # core module configuration
    │   ├── core.module.js              # core module initialize
    │   └── core.routes.js              # core route definitions
    ├── dependencies                    # application dependencies module
    │   ├── dependencies.config.js      # module configuration, configure 3rd party libraries here
    │   └── dependencies.module.js      # module initialize, specify 3rd party libraries here 
    ├── layout                          # layout module for application
    │   ├── footer                      # footer module
    │   ├── header                      # header module
    │   └── sidenav                     # sidenav module
    ├── modules                         # Application modules, this is where you put your own modules
    │   └── about                       # Example about module
    ├── app.config.js                   # configuration for application, contains API URL and VERSION information
    ├── index.js                        # app entry module
    ├── index.scss                      # entry point for appliction SCSS rules 
    └── index.test.js                   # entry point for test karma

Backend

This application relies that your backend implements following functionality.

Endpoints / actions:

1. POST _your_backend_url/auth/getToken

• Request payload {"username": "some_username", "password": "some_password"}
• Response {"token": "JWT hash", "refresh_token": "Refresh token hash"}

2. GET _your_backend_url/auth/profile

JWT handling

Your backend must support JWT on authenticate and authorization. After successfully login each request will contain Authorization: Bearer JsonWebTokenHere header which your backend much validate.

Also note that actual JsonWebToken must contain roles attribute which is an array that contains user roles. These roles must match with userRoles.js definitions.

Example of decoded JsonWebToken:

{
  "exp": 1474307796,
  "username": "admin",
  "ip": "xxx.xxx.xxx.xxx",
  "agent": "Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/53.0.2785.113 Safari/537.36",
  "checksum": "8939095afa51a37861b8e0fb4812d3ad893af2aec7604a25e29afe836e588678640ebaa6e001062274b2d2a97f20528771a43b0022e37eaebdefb7d0caa28d5c",
  "roles": [
    "ROLE_ROOT",
    "ROLE_ADMIN",
    "ROLE_USER",
    "ROLE_LOGGED"
  ],
  "firstname": "Arnold",
  "surname": "Administrator",
  "email": "[email protected]",
  "iat": "1474221396"
}

CORS support

Your backend should have CORS enabled if you're going to host back- and frontend in different domains.

Example backend

You can find simple backend solution here which implements all required for this frontend application.

Angular specific conventions

Application organisation rules:

1. Split app into angular "modules"

• every module should have own folder, and should be defined in one file which will require all module components and will export module name
• module can have nested modules
• module can require other modules which are direct siblings of it or parent modules, or modules nested in it (if you need to require module that is nested in "sibling" - you you should move it up by hierarchy before requiring it)

2. Keep modules small - if module is too big, maybe it should be few modules
3. Every file should have only one entity inside it, for example if there is directive which has controller and template - there should be three files, plus likely two for unit tests
4. Group related resources by folders
5. Name files with suffixes .directive, .controller, .component, .factory, .service, .provider, etc.
6. Use .test suffix for test file names

Directives

1. Prefer to use isolated scopes
2. Use controllerAs syntax
3. Controller should act as ViewModel, use $scope only if you need it
4. All model layer (data fetching, business logic) should be in services

Author

Tarmo Leppänen

License

The MIT License (MIT)

Copyright (c) 2016 Tarmo Leppänen