kesuskim / universal

Universal (isomorphic) javascript support for Angular2

<img src="https://cloud.githubusercontent.com/assets/1016365/10639063/138338bc-7806-11e5-8057-d34c75f3cafc.png" alt="Universal Angular 2" height="320"/>

Universal Angular 2

Universal (isomorphic) JavaScript support for Angular 2.

Table of Contents

• Documentation
• Getting Started with Universal
  • w/ NodeJS Server
  • w/ ASP.NET Core Server
• Universal "Gotchas"
• Modules
  • Universal
• What's in a name?
• License

---

Documentation

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

---

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 ondestroy 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)
  • Use a UniversalCache instead of regular Http, to save certain requests so they aren't re-ran again on the Client.
• 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.

Modules

Universal

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

Videos

Angular 2 Universal Patterns - ng-conf, May 2016

Angular Universal Source Code - ReadTheSource, January 2016

Full Stack Angular 2 - AngularConnect, Oct 2015

Angular 2 Server Rendering - Angular U, July 2015

preboot.js

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)

License