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

Modern app seed for legacy Angular apps (1.x)
Table of Contents
What is this
- Includes following
- Application specified stuff
Installation, configure and usage
Getting started
Usage advice
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:

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

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:

POST _your_backend_url/auth/getToken

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

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": "arnold@administrator.com",
  "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:

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)

Keep modules small - if module is too big, maybe it should be few modules
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
Group related resources by folders
Name files with suffixes .directive, .controller, .component, .factory, .service, .provider, etc.
Use .test suffix for test file names

Directives

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

Author

Tarmo Leppänen

License

The MIT License (MIT)

tarlepp/angular-material-webpack-seed