https://github.com/shy2net/nodejs-angular-starter

A starter template to work with on NodeJS (typescript), Angular (with SSR), and shared models.
https://github.com/shy2net/nodejs-angular-starter

angular6 nodejs starter-template

Last synced: about 2 months ago
JSON representation

A starter template to work with on NodeJS (typescript), Angular (with SSR), and shared models.

• Host: GitHub
• URL: https://github.com/shy2net/nodejs-angular-starter
• Owner: shy2net
• Created: 2018-06-26T20:31:55.000Z (about 6 years ago)
• Default Branch: master
• Last Pushed: 2023-01-24T02:23:15.000Z (over 1 year ago)
• Last Synced: 2024-06-10T15:49:22.698Z (3 months ago)
• Topics: angular6, nodejs, starter-template
• Language: TypeScript
• Homepage: https://nemex-studios.com
• Size: 3.13 MB
• Stars: 15
• Watchers: 4
• Forks: 10
• Open Issues: 22
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
- [Important Note](#important-note)

- [Introduction](#introduction)

  - [Prerequisites](#prerequisites)

    - [All environments](#all-environments)

    - [On Windows](#on-windows)

    - [On Linux](#on-linux)

- [Starting with this template](#starting-with-this-template)

- [Template architecture](#template-architecture)

  - [Angular 10](#angular-10)

    - [Angular services & providers](#angular-services--providers)

    - [Angular components](#angular-components)

    - [Angular Universal (Server-Side-Rendering)](#angular-universal-server-side-rendering)

  - [NodeJS](#nodejs)

    - [How the API works](#how-the-api-works)

      - [Working with API params](#working-with-api-params)

      - [API middlewares](#api-middlewares)

    - [Database](#database)

    - [Logging using Ts.LogDebug](#logging-using-tslogdebug)

    - [SSL (https support)](#ssl-https-support)

    - [Authentication and roles](#authentication-and-roles)

      - [Social Authentication](#social-authentication)

    - [Environment configurations](#environment-configurations)

    - [Testing (Unit Tests\API Tests)](#testing-unit-testsapi-tests)

        - [Test database](#test-database)

        - [Running the tests](#running-the-tests)

  - [Sharing code (models, interfaces, etc)](#sharing-code-models-interfaces-etc)

  - [Form validations](#form-validations)

- [Running on production](#running-on-production)

  - [Running Angular and NodeJS on the same server](#running-angular-and-nodejs-on-the-same-server)

    - [Docker\Docker-Compose](#dockerdocker-compose)

      - [Docker-compose](#docker-compose)

      - [Docker image build](#docker-image-build)

    - [The build script (build.sh)](#the-build-script-buildsh)

  - [Seperating client and server](#seperating-client-and-server)

    - [Server as standalone](#server-as-standalone)

    - [Angular as standalone](#angular-as-standalone)

# Important Note

> This template is deprecated and will no longer be maintained. Please use the new [nest-angular-starter](https://github.com/shy2net/nestjs-angular-starter) instead. It has almost the same code-base except the server side which was refactored and is now based on NestJS.

> 

> **It is highly recommend to move to the new template instead, as this template is no longer maintained!**

# Introduction

This starter template comes with NodeJS (typescript) and Angular 10. It shares models between Angular

and NodeJS. Both of the NodeJS and and Angular 10 can run on the same webserver as the NodeJS exposes all of the

default routes to Angular and all of the known routes to the api.

Technologies used in this template:

- Angular 10 (with SSR) - including unit tests (based on Jasmine + Karma)

- NodeJS express typescript (with SSL support) based on [Ts.ED](https://tsed.io/) - for easier express setup using decorators

- Mocha + Chai for backend testing + API tests

- Mongoose (with basic user model)

- Logging (using [Ts.LogDebug](https://typedproject.github.io/ts-log-debug/#/))

- Bootstrap v4 and SCSS by default

- [JWT](https://jwt.io/) and token authentication built-in (including user roles)

- Social Authentication (Google and Facebook)

- Form validations using ([class-validator](https://www.npmjs.com/package/class-validator)), shared between server and client

- Docker support based on alpine and node 12

## Prerequisites

In order to start with this template you have to set up the environment you are working on to suit the needs.

### All environments

Because this template uses mongo-db by default, if you want to run it easily out-of-the-box you must install docker,

then run the following command:

```bash

docker-compose up -d db # Loads up an instance of mongo-db locally with root\root (user\pass) and 'admin' database

```

This will create a simple mongo database with a username\password of 'root' and database named 'admin'.

The mongo-db instance will create a volume mounted at: `~/web_mongo` (inside your user home directory)

Optionally, you can connect to your own mongo-db instance by configuring it (read the config section for more).

### On Windows

Make sure to install [git bash](https://git-scm.com/downloads), this allows you to run `bash` commands which are essential for the build process. You can use any other bash for windows, as long as it can run the scripts this template relays on (`./install_all.sh, predebug.sh, build.sh, test.sh`).

**Make sure to add bash to your system 'PATH'.**

### On Linux

After cloning this repository, make sure to run the following command:

 ```bash

 chmod +x ./install_all.sh && chmod +x ./predebug.sh && chmod +x ./build.sh && chmod +x ./test.sh

 ```

This will give permission to run all included required to work with this template.

# Starting with this template

To work with this template **locally (debug mode)**, follow these commands:

    npm run install:all # Install all dependencies required for both NodeJS and Angular

    npm run node # Run the NodeJS on debug mode

    npm run angular # Run Angular

We don't run the `npm start` command as it is reserved only for the compiled code to run on a production server.

In order to compile and build this template for your **production server** run the following:

    npm run install:all # Install all dependencies required for both NodeJS and Angular

    npm run build # Run the build.sh script to compile and NodeJS and Angular for production

    npm start

These list of commands will install, compile and run the output NodeJS.

# Template architecture

The template comes with a ready to go server and client integration, authentication and basic styling.

## Angular 10

Angular 10 comes with the following features:

- Bootstrap v4 with header and sticky footer.

- Built in SSR bundled with the api server.

- Built in toasty (ngx-toastr) which automatically pops up on HTTP errors obtained from the server API.

- Built in ngx-loading-bar (Youtube styled) when moving between routes.

- Built in auth-guard and authentication, saved on session cookie.

- Built in social authentication (Google and Facebook).

- Build in form validations using class-validator (https://github.com/typestack/class-validator) implemented using the `FormValidatorDirective`.

The code of Angular 10 is stored under the `angular-src` directory.

### Angular services & providers

This template comes with multiple services and proviers which can be used accross the template.

- `ApiService` - This service wraps the access to the server api. It should contain a 'mirror' of the functions that the server has.

- `AuthService` - This service exposes all of the authentication mechanisem and handles all of the login, including login to the api, obtaining the token and saving the token to a cookie for next refresh.

- `AuthGuardService` - An auth guard which used the `AuthService` to guard routes. It also comes with role checking by specifing the `typescript { roles: ['roleName'] }` data for your route.

- `AppHttpInterceptor` - This provider acts as an interceptor for all of the http requests ongoing. It adds the authentication token if provided by the `AuthService` to each request. Then it passes the request to the `RequestsService` to handle.

- `RequestsService` - This service handles all of the requests passing through using the `AppHttpInterceptor`. It shows an error toast if an error had occured in one of the requests.

- `AppService` - Holds information about the current user and app related data.

- `SocialLoginService` - This service is responsible for the whole social authentication (Google and Facebook), it uses `angularx-social-login` module to do so. This service can be found under `social-login` module which initializes all of the providers (which are the 3rd party social sites).

### Angular components

- `AppComponent` - The app component is the bootstrap component of this template. It contain the HTML of the app (such the header, router-oulet and footer). It contains logic to listen to routing changes and showing or hiding the slim loading bar (Youtube styled routing progress bar).

- `HeaderComponent` - The header part of the template. It shows a simple header based on bootstrap which is suitable for mobile as well.

- `FooterComponent` - A simple sticky footer that always appear at the bottom of the page.

- `LoginComponent` - A simple login with username and password which authenticates against the server.

- `UserPageComponent` - A simple page that shows information about the currently logged in user with option of logging out.

- `SocialLoginButton` - A simple container of social login buttons which also performs the social authentication itself.

### Angular Universal (Server-Side-Rendering)

By default this template comes ready with Angular Universal which allows search engines to crawl your website better.

It does this on the NodeJS side after running the `npm run build` command which bundles the angular code and create an angular universal express ready file called `out/src/dist/server.js` which our NodeJS simply imports and initializes in the `src/app.ts` file.

in the `src/app.ts` you have these two methods:

```typescript

  /**

   * Mounts angular using Server-Side-Rendering (Recommended for SEO)

   */

  private mountAngularSSR(): void {

    // The dist folder of compiled angular

    const DIST_FOLDER = path.join(__dirname, 'dist');

    // The compiled server file (angular-src/server.ts) path

    const ngApp = require(path.join(DIST_FOLDER, 'server/main'));

    // Init the ng-app using SSR

    ngApp.init(this.expressApp, path.join(DIST_FOLDER, '/browser'));

  }

  /**

   * Mounts angular as is with no SSR.

   */

  private mountAngular(): void {

    // Point static path to Angular 2 distribution

    this.express.use(express.static(path.join(__dirname, 'dist/browser')));

    // Deliever the Angular 2 distribution

    this.express.get('*', function(req, res) {

      res.sendFile(path.join(__dirname, 'dist/browser/index.html'));

    });

  }

```

By default the mountAngular is called in the init method of `src/app.ts`, simply change it into `mountAngularSSR` in order to enable

SSR, but be careful as SSR requires special treatments in your code on certain situations.

## NodeJS

Comes with built in typescript support and compilation.

It comes with the following features:

- [Ts.ED](https://tsed.io/) - Easier express with typescript using decorators

- Authentication (including middlewares and token generation)

- Angular routes support (redirect to index.html of compiled Angular code), this means you can run you Angular app and API on the same container!

- Configuration according to environment (using [config npm package](https://www.npmjs.com/package/config)).

- Logging (using [Ts.LogDebug](https://typedproject.github.io/ts-log-debug/#/)).

- Social Authentication, which basically gets an access token from the client that logged into a service and then creates a user associated with it.

- Unit testing using Mocha and Chai.

The code of NodeJS is stored under the `src` directory.

Output directory of the compiled typescript will be available in the `out` directory.

### How the API works

I would first recommend you to read the [Getting Started tutorial of Ts.ED](http://tsed.io/getting-started.html). As it will explain really good how

the decorators help make your express app easier to write, maintain and faster for development.

Within this template, NodeJS comes with three working examples of a working api called `test`, `errorTest` and `saySomething`,

which can be viewed under `src/api/api.controller`.

The way this template is built makes the whole code a-lot more readable, and easier for testing.

api.controller.ts:

```typescript

  @Get('/test') // This tells express to route on /api/test

  test() {

    return responses.getOkayResponse();

  }

```

The `responses.getOkayResponse(data?: any)` is just a simple method that returns a JSON response:

```typescript

export function getOkayResponse(data?: any) {

  return {

    status: 'ok',

    data: data

  } as ActionResponse;

}

```

ActionResponse objects are objects that specify a response to an action done on the server. You can provide

data which comes with the response. If the status of the ActionResponse is error, it will appear as toast

by default in the client.

You can test this api easily by running the express server:

> npm run node

Now simply access your server in this url:

> [http://localhost:3000/api/test](http://localhost:3000/api/test)

#### Working with API params

Let's review the working example of saySomething:

api.controller.ts:

```typescript

  @Get('/say-something') // Route on /api/say-something

  saySomething(@QueryParams('whatToSay') whatToSay: string) { // Setting the @QueryParams decorator tells express to extract the request.query['whatToSay'] into the whatToSay param.

    return responses.getOkayResponse(whatToSay);

  }

```

Now simple open up your browser to the api url with a 'what' param:

> http://localhost:3000/api/say-something?what=Hello

And you will get this output:

```json

{

  "status": "ok",

  "data": "Hello"

}

```

#### API middlewares

The api comes with some prepacked middlewares which can be found in the `src/middlewares` directory:

- `auth.middelware` - Authenticates the user against the stored credentials on the database (currently based on Mongoose).

- `cors.middleware`- Allows passing CORS using the config.CORS_OPTIONS.

### Database

This template uses mongoose as the backend server to store users. It has only one model called UserProfileModel which you can find in the `src/models` directory.

You can view the database code at the `src/db.ts` file, which basically is responible with the communication to the database.

In order to configure the database connection string, please review the `Environment configurations` part of this readme.

### Logging using Ts.LogDebug

This template comes ready with [Ts.LogDebug](https://typedproject.github.io/ts-log-debug/#/). By default it will save all of the error logs into the `logs` directory.

You can edit the logging configurations in the `server.ts` file:

```typescript

  /**

   * Returns the logger configurations.

   */

  private getLoggerConfigurations(settings: IServerSettings): Partial {

    // All logs are saved to the logs directory by default, you can specify custom directory in the associated configuration file ('LOGS_DIR')

    const logsDir = config.LOGS_DIR || path.join(__dirname, 'logs');

    // Add file appenders (app.log for all logs, error.log only for errors)

    $log.appenders.set('file-error-log', {

      type: 'file',

      filename: path.join(logsDir, `error.log`),

      levels: ['error']

    });

    // --> Uncomment this line if you want to log all data

    // .set('file-log', {

    //   type: 'file',

    //   filename: path.join(logsDir, `app.log`)

    // });

    return {

      ...settings.logger,

      debug: config.DEBUG_MODE,

      level: config.DEBUG_MODE ? 'debug' : 'info'

      /* --> Uncomment to add request logging

        requestFields: ['reqId', 'method', 'url', 'headers', 'body', 'query', 'params', 'duration'],

        logRequest: true

        */

    };

  }

```

### SSL (https support)

This template comes with SSL support right out of the box. The only things you need to configure in your configuration

file is the SSL_CERTIFICATE:

```typescript

  SSL_CERTIFICATE: {

    KEY: string;

    CERT: string;

    CA: string;

  };

```

Let's say we want to configure the production to enable HTTPS, simply open up the `src/config/production.json` file and configure it as followed:

```json

{

  ...

  "DB_URI": "production-mongo-uri",

  "CLIENT_URL": "http://yourwebsite.com",

  // You must create a certificate in order to enable SSL (you can use https://letsencrypt.org/ for a free certificate)

  "SSL": {

    "CA_PATH": "path/to/chain.pem",

    "PRIVATE_KEY_PATH": "path/to/privkey.pem",

    "CERTIFICATE_PATH": "path/to/cert.pem"

  }

  ...

}

```

Now when your server loads up, it will call this method in the `server.ts` file:

```typescript

  /**

   * Returns the SSL (https) if any configured for this environment.

   */

  getSSLConfigurations() {

    const sslConfig = config.SSL_CERTIFICATE;

    if (!sslConfig) return {};

    return {

      httpsPort: 443,

      httpsOptions: {

        key: sslConfig.KEY,

        cert: sslConfig.CERT,

        ca: sslConfig.CA

      }

    };

  }

```

### Authentication and roles

This template comes prepacked with JWT authentication and associated middlewares to authenticate users.

in the `src/auth.ts` file you will be able to see how the authentication is implemented.

Basically, when a login occurs, the user is being authenticated against a hased password using bcrypt, if the passwords match, a token is being generated containing the user data within.

When accessing guarded routes (using the authenticationMiddleware in the `auth.ts` file), the token will be decrypted and checked to see if it's valid. If so, the request will pass and a `req.user` property will be filled with currently logged on user.

For example, let's take a look at a guarded route, such as the `/api/profile`.

> TODO: Add correct information

In the `api.controller.ts` you can see the following code:

```typescript

  @Get('/profile')

  @UseBefore(AuthMiddleware)

  getProfile(@RequestUser() user: UserProfile): UserProfile {

    return user;

  }

```

The `UseBefore` decorator will call the `AuthMiddleware` to check if the user is authorized to login.

Simple isn't it? The token is being delivered in the Authorization header in the format of `Authorization: Bearer ${Token}`.

What about user roles? Each user profile has an array of `roles` which holds strings which contains the roles relevant for the user. For example, if you add the role `admin` to your user you should be able to access the `/api/admin_test` endpoint as it is guarded using the `AuthMiddleware`.

Let's see how it is implemented.

`api.controller.ts`:

```typescript

  @Get('/admin')

  @UseBefore(AuthMiddleware, { role: 'admin' })

  adminTest() {

    return this.test();

  }

```

#### Social Authentication

The procedure of social authentication takes place in the client side, after the client obtains an access token from the 3rd party (Google, Facebook), that access token

will be delieverd to the `social-login/provider` (replace provider with the 3rd party name), which will create a user from the token provided by accessing that specific

3rd party social network user profile information and map the user data into a data applicable for our website.

The authentication is implemented via the `passport` npm package with packages like `passport-facebook-token` and `passport-google-token`.

If A user with the provided email exists, it is returned with a new access token which is only relevant for our app (just like normal authentication).

Take a look at the `src/social-auth` implementation to see how the access token is being used.

### Environment configurations

This template is using the npm `config` package load configurations. You can read more about it here:

https://www.npmjs.com/package/config

All of the configurations are located at the `src/config` directory. The way it loads the configuration is by first loading the `default.json` files and then load the associated environment configuration (by default `development.json`).

In order to change the environment you must specify the `NODE_ENV` environment variable.

For example, if you run on production specify:

`NODE_ENV = production`.

There is a special configurations for the `test` environment as it starts up a test server on a different

port and different credentials.

### Testing (Unit Tests\API Tests)

This template comes with Mocha and Chai integrated.

There are tests for all of the following:

- API tests

- Tests for middlewares and services

- General tests

Each file that has a test has a corresponding `.spec` file with the same name.

For example, for the api tests:

`/src/controllers/api.controller.spec.ts` - you can find all api tests.

##### Test database

When the unit tests are running, they relay on a database connection, especially

the API tests, as these tests write mock data to the database before running the tests.

Before running the tests, you must setup the tests database.

You can do this easily using the following docker command:

> docker-compose up -d test-db

This will start a clean test database on a different port then the normal database.

##### Running the tests

In order to run the tests, enter the following commands:

```bash

# Start the test database before running the tests

docker-compose up -d test-db

### ---> Wait for the database to run (at least 30 seconds for the first time)

# Wait for the database to run, and then run the tests

npm test

```

All configurations will be taken from the `/src/config/test.json` file, which is configured by default

to connect a different port and a different user\password (test\test) in order to run the tests.

If you would like to run this in your own CI\CD tool, make sure write the following in the test run pipeline:

```bash

# Automatically sets up the database using docker-compose

export SETUP_DB=true

# Start the unit tests

npm test

```

This will automatically setup the test database and close it when the tests were finished.

## Sharing code (models, interfaces, etc)

You can use the `shared` directory in order for NodeJS and Angular to share the same code to be used on both sides

without the need of re-writing the models for each.

The already existing models are:

- ActionResponse - a simple response to a user action performed on the api. The server will send this response, and the client will read it.

- UserProfile - a simple user profile model to used for authentication.

## Form validations

This template comes with [class-validator](https://www.npmjs.com/package/class-validator) built in. Which makes it a-lot more easier to write form validations.

As this template shares code between Angular and NodeJS, validations will happen across both platforms.

Let's look at the `UserProfile` model for example:

```typescript

import { Form } from './forms';

import { UserProfile } from './user-profile';

import { IsEmail, MinLength } from 'class-validator';

export class UserProfileModel implements UserProfile {

  @IsEmail()

  email: string;

  @MinLength(1)

  firstName: string;

  @MinLength(1)

  lastName: string;

  @MinLength(6)

  password: string;

  roles?: string[];

}

```

The decorators you see like `@IsEmail`, `@MinLength` are class-validator decorators and allows us to easily force fields to pass certain validations.

For example, when registering a user validations takes place in this way:

- Angular - checks that all fields are valid using the `FormValidatorDirective`, each field on your form will automatically show if it is valid or invalid

  according to the validation set on it.

  The `FormValidatorDirective` is a directive set on a form which simply checks each input and according to it's name assigns the validations relative to it.

  Take a look at this example:

  `angular-src/src/app/components/register/register.component.html`:

  ```html

    ...

    

        


          


            


              


                Email

                

              


              


                Password

                

              


            

      ...

  ```


  See the `appFormValidator` directive? it associated with the `userProfile` object, which is an instance of `UserProfileModel`. This allows you to easily

  Forces validations on forms and errors to the user.

- NodeJS - on the server side validations are taken place in this way:

  `/src/controllers/api.controller.ts`:

  ```typescript

  @Post('/register')

  register(@BodyParams() userProfile: UserProfile): Promise {

    return registerForm.getHashedPassword().then(hashedPassword => {

      return UserProfileDbModel.create({

        ...registerForm,

        password: hashedPassword

      });

    });

  }

  ```

  The validation of class-validator will take place automatically using the class-validator, you can read about it here:

  [https://tsed.io/docs/validation.html#custom-validation](https://tsed.io/docs/validation.html#custom-validation).

  The pipes required for class-validator to take place, are already implemented at `/src/pipes`;

# Running on production

In order to run this code on production, you must first compile it.

There a few things to take into consideration:

## Running Angular and NodeJS on the same server

This template comes with Angular and NodeJS bundled together and can

be up and running together on the same NodeJS server. This takes place using the `build.sh` bash script

that knows how to compile them together and bundle them.

How does it work? Well it simply compiles each one seperatly and then copies the angular-src output dist directory

into the NodeJS src directory and delievers them in the `src/server.ts` like this:

```typescript

// Point static path to Angular 2 distribution

this.express.use(express.static(path.join(__dirname, 'dist')));

// Deliever the Angular 2 distribution

this.express.get('*', function(req, res) {

  res.sendFile(path.join(__dirname, 'dist/index.html'));

});

```

**Take into consideration that it will not work on debug mode.**

When building your image for production it should contain the following commands:

    npm run build # Call the build.sh script to start the build (it also installs the deps required if they do not exist)

And to run this code simple:

    npm start

### Docker\Docker-Compose

This template comes ready with Dockerfile based on node:12.18.1-alpine3.11 docker image.

It also comes with a ready out of the box docker-compose.yml file which can be used

to start-up the database and the web interface.

#### Docker-compose

You can fire-up the database and the web interface using the following command:

    # This will build web docker image automatically if it does not exist

    docker-compose up -d

You can also build the web image manually like this:

    docker-compose build web

The environment variable for communication using docker-compose is already included in the `.env` file.

This `.env` file contains the DB_URI of the database which the web will be able to to access.

#### Docker image build

In order to build the docker image without docker-compose, you can simply run the following command:

    docker build -t my-docker-image:0.0.0 .

And in order to run your docker on port 8080 simply run the following command:

    docker run -p 8080:3000 -itd my-docker-image:0.0.0

Or you can simply use docker compose:

    docker-compose up

This will run your container on port 3000.

### The build script (build.sh)

The build script called `build.sh` is a shell script provided with the template which by default will compile the typescript

NodeJS server side and Angular into one. This means when you run the server after the build you will have both on the same

node container.

Make sure to include the `NODE_ENV` environment variable (or else the build will be set to `development` environment) before calling this

script. The build will compile and copy all of the required configurations for the specified environment, and will generate the Angular

code according to that environment.

By default, when building to production, Server Side Rendering (SSR) is set to build as well:

```bash

# TODO: Remove this 'if' statment until the 'fi' if you don't want SSR at all

if [ $ENV == "production" ]; then

    echo "Building Angular app for SSR..."

    ./node_modules/.bin/ng run angular-src:server:production

    check_errcode "Failed to build Angular app for SSR! aborting script!"

else

    echo "Skipping build for SSR as environment is NOT production"

fi

```

You can remove this set of code if you don't want it to take place at all.

## Seperating client and server

### Server as standalone

In order to run the server as standalone, simply compile it:

    npm run build:node

The output will be projected into the `dist` directory.

### Angular as standalone

In order to run angular as a standalone, simply compile it:

    npm run build:angular

The output will be projected into the `angular-src/dist` directory.