Angular Universal

Universal (isomorphic) JavaScript support for Angular.

Table of Contents

• Introduction
• Packages
• Upgrading from Angular2-Universal
• Roadmap
• Getting Started with Universal
  • w/ NodeJS Server
  • w/ ASP.NET Core Server
• Universal "Gotchas"
• Preboot
• What's in a name?
• Universal Team
• License

Introduction

The Angular Universal project consists of the base platform API and the surrounding tools that enables developer to do server side rendering (or pre-rendering) of Angular applications. The platform API part has been merged into Angular core as of 4.0.

This repository will host the various tools like engines to integrate with various backends(NodeJS, ASP.NET etc.) and also extra modules and examples to help you started with server side rendering.

Packages

The packages from this repo are published as scoped packages under @nguniversal

• @nguniversal/express-engine
• @nguniversal/aspnetcore-engine
• @nguniversal/hapi-engine
• @nguniversal/module-map-ngfactory-loader (for handling lazy loaded modules on the server).

The 1.x packages work with Angular 4.x while the 5.x packages will work with Angular 5.x. We will match the major version with Angular starting from 5.0 to avoid confusion.

Upgrading from Angular2-Universal

If you're coming from the original angular2-universal (2.x) here are some helpful steps for porting your application to Angular 4 & platform-server.

Go here to find the guide

Roadmap

Completed

• Integrate the platform API into core
• Support Title and Meta services on the server
• Develop Express, ASP.NET Core, Hapi engines
• Angular CLI support for Universal
• Provide a DOM implementation on the server
• Hooks in renderModule* to do stuff just before rendering to string
• Generic state transfer API in the platform
• Http Transfer State Module that uses HTTP interceptors and state transfer API
• Material 2 works on Universal

In Progress

• Write documentation for core API
• Better internal performance and stress tests
• Make it easier to write unit tests for Universal components
• Support AppShell use cases
• Make it easier to support other 3rd part libraries like jQuery/d3 that aren't Universal aware

Planning

• Full client rehydration strategy that reuses DOM elements/CSS rendered on the server
• Provide a solution for Java backends
• Node.js bridge protocol to communicate with different language backends - Django, Go, PHP etc.

Getting Started

* NodeJS :: Example repo

• Minimal webpack & universal example with Angular 5.0

* ASP.NET Core :: Universal Starter repo

• Installation: Clone the above repo, npm i && dotnet restore (VStudio will run these automatically when opening the project)
• Launch files included for both VSCode & VStudio to run/debug automatically (press F5).

Universal "Gotchas"

When building Universal components in Angular there are a few things to keep in mind.

• window, document, navigator, and other browser types - do not exist on the server - so using them, or any library that uses them (jQuery for example) will not work. You do have some options, if you truly need some of this functionality:

  • If you need to use them, consider limiting them to only your client and wrapping them situationally. You can use the Object injected using the PLATFORM_ID token to check whether the current platform is browser or server.

   import { PLATFORM_ID } from '@angular/core';
   import { isPlatformBrowser, isPlatformServer } from '@angular/common';
   
   constructor(@Inject(PLATFORM_ID) private platformId: Object) { ... }
   
   ngOnInit() {
     if (isPlatformBrowser(this.platformId)) {
        // Client only code.
        ...
     }
     if (isPlatformServer(this.platformId)) {
       // Server only code.
       ...
     }
   }

  • Try to limit or avoid using setTimeout. It will slow down the server-side rendering process. Make sure to remove them in the ngOnDestroy method of your Components.
  • Also for RxJs timeouts, make sure to cancel their stream on success, for they can slow down rendering as well.

• Don't manipulate the nativeElement directly. Use the Renderer2. We do this to ensure that in any environment we're able to change our view.

constructor(element: ElementRef, renderer: Renderer2) {
  renderer.setStyle(element.nativeElement, 'font-size', 'x-large');
}

• The application runs XHR requests on the server & once again on the Client-side (when the application bootstraps)
  • Use a cache that's transferred from server to client (TODO: Point to the example)
• Know the difference between attributes and properties in relation to the DOM.
• Keep your directives stateless as much as possible. For stateful directives, you may need to provide an attribute that reflects the corresponding property with an initial string value such as url in img tag. For our native element the src attribute is reflected as the src property of the element type HTMLImageElement.

Preboot

Control server-rendered page and transfer state before client-side web app loads to the client-side-app. Repo

What's in a name?

We believe that using the word "universal" is correct when referring to a JavaScript Application that runs in more environments than the browser. (inspired by Universal JavaScript)

Universal Team

• PatrickJS and Jeff Whelpley - Founders of the Angular Universal project. (Universal rendering is also called PatrickJS-ing)
• Mark Pieszak - Contributor and Evangelist, ASP.NET Core Engine
• Jason Jean - Express engine and Universal support for CLI
• Wassim Chegham - Contributor and Evangelist, Hapi engine developer.
  • Angular for the rest of us
  • Angular outside the browser
• Jeff Cross - Evangelist and performance consultant
• Vikram Subramanian and Alex Rickabaugh - Angular Core API

The Universal project is driven by community contributions. Please send us your Pull Requests!

License