Unleash awesomeness. Private packages, team management tools, and powerful integrations. Get started with npm Orgs »


7.0.0 • Public • Published


This is a Hapiness Engine for running Angular Apps on the server for server side rendering.

Integrating NG-Universal into existing CLI Applications

This story will show you how to set up Universal bundling for an existing @angular/cli.

We support actually @angular @7.0.1 and next so you must upgrade all packages inside your project.

We use yarn as package manager.

Table of contents

Install Dependencies

Install @angular/platform-server into your project. Make sure you use the same version as the other @angular packages in your project.

Install Hapiness modules into your project: @hapiness/core, @hapiness/ng-universal and @hapiness/ng-universal-transfer-http.

You also need :

  • ts-loader and webpack, webpack-cli for your webpack build we'll show later and it's only in devDependencies.
  • @nguniversal/module-map-ngfactory-loader, as it's used to handle lazy-loading in the context of a server-render. (by loading the chunks right away)
$ yarn add --dev ts-loader webpack webpack-cli
$ yarn add @angular/platform-server @nguniversal/module-map-ngfactory-loader @hapiness/core @hapiness/ng-universal @hapiness/ng-universal-transfer-http rxjs-compat

Step 1: Prepare your App for Universal rendering

The first thing you need to do is make your AppModule compatible with Universal by adding .withServerTransition() and an application ID to your BrowserModule import.

TransferHttpCacheModule installs a Http interceptor that avoids duplicate HttpClient requests on the client, for requests that were already made when the application was rendered on the server side.

When the module is installed in the application NgModule, it will intercept HttpClient requests on the server and store the response in the TransferState key-value store. This is transferred to the client, which then uses it to respond to the same HttpClient requests on the client.

To use the TransferHttpCacheModule just install it as part of the top-level App module.


import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { TransferHttpCacheModule } from '@hapiness/ng-universal-transfer-http';
import { AppComponent } from './app.component';
  declarations: [
  imports: [
    // Add .withServerTransition() to support Universal rendering.
    // The application ID can be any identifier which is unique on
    // the page.
    BrowserModule.withServerTransition({ appId: 'ng-universal-example' }),
    // Add TransferHttpCacheModule to install a Http interceptor
  providers: [],
  bootstrap: [AppComponent]
export class AppModule {

Next, create a module specifically for your application when running on the server. It's recommended to call this module AppServerModule.

This example places it alongside app.module.ts in a file named app.server.module.ts:


import { NgModule } from '@angular/core';
import { ServerModule, ServerTransferStateModule } from '@angular/platform-server';
import { ModuleMapLoaderModule } from '@nguniversal/module-map-ngfactory-loader';
import { AppModule } from './app.module';
import { AppComponent } from './app.component';
  imports: [
    // The AppServerModule should import your AppModule followed
    // by the ServerModule from @angular/platform-server.
  // Since the bootstrapped component is not inherited from your
  // imported AppModule, it needs to be repeated here.
  bootstrap: [AppComponent]
export class AppServerModule {

Then, you must set an event on DOMContentLoaded to be sure TransferState will be passed between server and client.


import { enableProdMode } from '@angular/core';
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { AppModule } from './app/app.module';
import { environment } from './environments/environment';
if (environment.production) {
document.addEventListener('DOMContentLoaded', () => {
    .catch(err => console.log(err));

back to top

Step 2: Create a server "main" file and tsconfig to build it

Create a main file for your Universal bundle. This file only needs to export your AppServerModule. It can go in src. This example calls this file main.server.ts:


export { AppServerModule } from './app/app.server.module';

Copy tsconfig.app.json to tsconfig.server.json and change it to build with a "module" target of "commonjs".

Add a section for "angularCompilerOptions" and set "entryModule" to your AppServerModule, specified as a path to the import with a hash (#) containing the symbol name. In this example, this would be app/app.server.module#AppServerModule.


  "extends": "../tsconfig.json",
  "compilerOptions": {
    "outDir": "../out-tsc/app",
    "baseUrl": "./",
    // Set the module format to "commonjs":
    "module": "commonjs",
    "types": []
  "exclude": [
  // Add "angularCompilerOptions" with the AppServerModule you wrote
  // set as the "entryModule".
  "angularCompilerOptions": {
    "entryModule": "app/app.server.module#AppServerModule"

back to top

Step 3: Create a new target in angular.json

In angular.json locate the architect property inside your project, and add a new server target.

In build target, adapt options.outputPath to dist/browser.


  "architect": {
    "build": {
      "builder": "@angular-devkit/build-angular:browser",
      "options: {
        "outputPath": "dist/browser",
    "server": {
      "builder": "@angular-devkit/build-angular:server",
      "options": {
        "outputPath": "dist/server",
        "main": "src/main.server.ts",
        "tsConfig": "src/tsconfig.server.json",
        "fileReplacements": [
            "replace": "src/environments/environment.ts",
            "with": "src/environments/environment.prod.ts"
        "optimization": true,
        "sourceMap": false

Building the bundle:

With these steps complete, you should be able to build a server bundle for your application:

# This builds the client application in dist/browser/ 
$ ng build --prod
# This builds the server bundle in dist/server/ 
$ ng run your-project-name:server
# outputs: 
Date: 2017-10-21T21:54:49.240Z                                                       
Hash: 3034f2772435757f234a
Time: 3689ms
chunk {0} main.js (main) 9.2 kB [entry] [rendered]
chunk {1} styles.css (styles) 0 bytes [entry] [rendered]

back to top

Step 4: Setting up a Hapiness Application to run our Universal bundles

Now that we have everything set up to -make- the bundles, how we get everything running?

We'll use Hapiness application and @hapiness/ng-universal module.

Below we can see a TypeScript implementation of a -very- simple Hapiness application to fire everything up.


This is a very bare bones Hapiness application, and is just for demonstrations sake.

In a real production environment, you'd want to make sure you have other authentication and security things setup here as well.

This is just meant just to show the specific things needed that are relevant to Universal itself. The rest is up to you!

At the ROOT level of your project (where package.json / etc are), created a file named: server.ts

server.ts (root project level):

// These are important and needed before anything else
import 'zone.js/dist/zone-node';
import 'reflect-metadata';
// * NOTE :: leave this until @hapiness/core will be migrated to rxjs v6 - This library is installed automatically
import 'rxjs-compat';
import { enableProdMode } from '@angular/core';
import { Hapiness, HapinessModule, HttpServerExt, HttpServerService, OnError, OnStart } from '@hapiness/core';
import { NgUniversalModule } from '@hapiness/ng-universal';
import { join } from 'path';
const BROWSER_FOLDER = join(process.cwd(), 'dist', 'browser');
// Faster server renders w/ Prod mode (dev mode never needed)
// * NOTE :: leave this as require() since this file is built Dynamically from webpack
const { AppServerModuleNgFactory, LAZY_MODULE_MAP } = require('./dist/server/main');
// Create our Hapiness application
  version: '1.0.0',
  imports: [
      bootstrap: AppServerModuleNgFactory,
      lazyModuleMap: LAZY_MODULE_MAP,
      staticContent: {
        indexFile: 'index.html',
        rootPath: BROWSER_FOLDER
  providers: [
class HapinessApplication implements OnStart, OnError {
   * Class constructor
   * @param {HttpServerService} _httpServer DI for HttpServerService to provide .instance() method to give original Hapi.js server
  constructor(private _httpServer: HttpServerService) {
   * OnStart process
  onStart(): void {
    console.log(`Node server listening on ${this._httpServer.instance().info.uri}`);
   * OnError process
  onError(error: Error): void {
// Boostrap Hapiness application
Hapiness.bootstrap(HapinessApplication, [
    host: '',
    port: 4000

Extra Providers:

Extra Providers can be provided either on engine setup

  bootstrap: AppServerModuleNgFactory,
  lazyModuleMap: LAZY_MODULE_MAP,
  staticContent: {
    indexFile: 'index.html',
    rootPath: BROWSER_FOLDER
  providers: [

Using the Request and Response:

The Request and Response objects are injected into the app via injection tokens. You can access them by @Inject

import { Request, REQUEST } from '@hapiness/ng-universal';
export class RequestService {
  constructor(@Inject(REQUEST) private _request: Request) {}

If your app runs on the client side too, you will have to provide your own versions of these in the client app.

back to top

Step 5: Setup a webpack config to handle this Node server.ts file and serve your application!

Now that we have our Hapiness application setup, we need to pack it and serve it!

Create a file named webpack.server.config.js at the ROOT of your application.

This file basically takes that server.ts file, and takes it and compiles it and every dependency it has into dist/server.js.

./webpack.server.config.js (root project level):

const path = require('path');
const webpack = require('webpack');
module.exports = {
  // Temporary fix for issue: https://github.com/angular/angular-cli/issues/10787#issuecomment-388512231
  mode: 'none',
  entry: {  server: './server.ts' },
  target: 'node',
  resolve: { extensions: ['.ts', '.js'] },
  optimization: {
    minimize: false
  // this makes sure we include node_modules and other 3rd party libraries
  externals: [/(node_modules)/],
  output: {
    path: path.join(__dirname, 'dist'),
    filename: '[name].js'
  module: {
    rules: [
      { test: /\.ts$/, loader: 'ts-loader' },
        // Mark files inside `@angular/core` as using SystemJS style dynamic imports.
        // Removing this will cause deprecation warnings to appear.
        test: /(\\|\/)@angular(\\|\/)core(\\|\/).+\.js$/,
        parser: { system: true },
  plugins: [
    // Temporary Fix for issue: https://github.com/angular/angular/issues/11580
    // for "WARNING Critical dependency: the request of a dependency is an expression"
    new webpack.ContextReplacementPlugin(
      path.join(__dirname, 'src'), // location of your src
      {} // a map of your routes
    new webpack.ContextReplacementPlugin(
      path.join(__dirname, 'src'),
    new webpack.ContextReplacementPlugin(
      path.join(__dirname, 'src'),
  stats: {
    warnings: false

Now, you can build your server file:

$ webpack --config webpack.server.config.js --progress --colors

Almost there:

Now let's see what our resulting structure should look like, if we open up our /dist/ folder we should see:


To fire up the application, in your terminal enter

$ node dist/server.js

Now lets create a few handy scripts to help us do all of this in the future.

"scripts": {

  // These will be your common scripts
  "build:dynamic": "yarn run build:client-and-server-bundles && yarn run webpack:server",
  "serve:dynamic": "node dist/server.js",

  // Helpers for the above scripts
  "build:client-and-server-bundles": "ng build --prod && ng run your-project-name:server",
  "webpack:server": "webpack --config webpack.server.config.js --progress --colors"

In the future when you want to see a Production build of your app with Universal (locally), you can simply run:

$ yarn run build:dynamic && yarn run serve:dynamic


Once again to see a working version of everything, check out the universal-starter.

back to top


To set up your development environment:

  1. clone the repo to your workspace,
  2. in the shell cd to the main folder,
  3. hit npm or yarn install,
  4. run npm or yarn run test.
    • It will lint the code and execute all tests.
    • The test coverage report can be viewed from ./coverage/lcov-report/index.html.

Back to top

Change History

  • v7.0.0 (2018-10-31)
    • Angular v7.0.1+
    • Migrate tests to jest and ts-jest
    • Code refactoring
    • Documentation
  • v6.2.0 (2018-09-24)
    • Angular v6.1.8+
    • Latest packages' versions
    • Install automatically rxj-compat@6.2.2 to be compatible with all Hapiness extensions
    • Update doc of webpack.server.config.ts to match with latest version of Angular Universal story
    • Documentation
  • v6.1.0 (2018-07-26)
    • Angular v6.1.0+
    • Documentation
  • v6.0.1 (2018-05-25)
    • Angular v6.0.3+
    • RxJS v6.2.0+
    • Documentation
  • v6.0.0 (2018-05-11)
    • Angular v6.0.1+
    • RxJS v6.1.0+
    • Documentation

Back to top


Julien Fauville Antoine Gomez Sébastien Ritz Nicolas Jessel Mathieu Jeanmougin

Back to top


Copyright (c) 2018 Hapiness Licensed under the MIT license.

Back to top


npm i @hapiness/ng-universal

Downloadsweekly downloads





SEE LICENSE IN https://github.com/hapinessjs/ng-universal-module/blob/master/LICENSE.md





last publish


  • avatar
Report a vulnerability