Universal (isomorphic) javascript support for Angular2
TypeScript JavaScript
Pull request Compare This branch is even with angular:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Current Status: Merging Universal into Angular core

Build Status npm version Join the chat at https://gitter.im/angular/universal Issue Stats Issue Stats

Universal Angular 2

Universal Angular 2

Universal (isomorphic) JavaScript support for Angular 2.

Table of Contents


Universal Documentation & Guide

  • Featuring an overview, installation process, and key concepts for creating Universal Angular applications.
  • For those intersted in how it all got started, and the goals of Universal check out the Original Design Doc (from 2015)

Getting Started

* NodeJS :: Universal Starter repo

  • Minimal webpack angular2 & universal starter
  • Installation: Clone the above repo, npm i && npm start to fire it up.

* 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).

* Angular Universal CLI repo

  • Universal-CLI is fork from Angular-CLI. It is a separate package because the Core-CLI team is not able to maintain non-core functionality.
  • npm install -g universal-cli and once installed: ung new PROJECT_NAME
  • Useage instructions here

Universal "Gotchas"

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

  • To use templateUrl or styleUrls you must use angular2-template-loader in your TS loaders.
    • This is already setup within this starter repo. Look at the webpack.config file here for details & implementation.
  • 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 main.client and wrapping them situationally with the imported isBrowser / isNode features from Universal. import { isBrowser, isNode } from 'angular2-universal';
    • Another option is using DOM from "@angular/platform-browser"
  • Try to limit or avoid using setTimeout. It will slow down the server-side rendering process. Make sure to remove them ngOnDestroy in 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 Renderer. We do this to ensure that in any environment we're able to change our view.
constructor(element: ElementRef, renderer: Renderer) {
  renderer.setElementStyle(element.nativeElement, 'font-size', 'x-large');
  • The application runs XHR requests on the server & once again on the Client-side (when the application bootstraps)
  • 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.



Manage your application lifecycle and serialize changes while on the server to be sent to the client.


Angular 2 Universal Patterns - ng-conf, May 2016
Angular 2 Universal Patterns

Angular Universal Source Code - ReadTheSource, January 2016
Angular Universal Source Code

Full Stack Angular 2 - AngularConnect, Oct 2015
Full Stack Angular 2

Angular 2 Server Rendering - Angular U, July 2015
Angular 2 Server Rendering


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

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)


MIT License