Migrate Angular Universal API to @angular/platform-server

High Level Plan

Angular Universal consists of 1)API and 2)tools to do server side rendering of Angular apps. Currently both the Angular Universal API and tools live in angular/universal. The plan is to migrate the API part of Angular Universal to the core Angular project in angular/angular for the Angular 4.0 release and beyond.

We will design the API from ground up to be a core part of Angular and also refactor internals of Angular to better support Angular Universal. The aim is to build a strong foundation for the future development of Angular Universal. This also puts Angular Universal as a core part of Angular and will follow the same quality and release processes as the rest of Angular.

We will keep the API compatible with the current Express wrapper for Universal and make corresponding changes to it as needed. (We haven't scoped out the support for other Universal tools outside of the Express wrapper at this point)

There will be API docs and Dev Guide for Angular Universal. There will be a migration doc to help with migration from the current angular2-universal to the new Angular Universal API.

Use cases

The main use cases we are considering for this iteration of Universal are

• Initial rendering of Angular application on server for perceived faster loading of application
• SEO: Content in Angular application is indexed by crawlers
• Link Preview - Generate a preview of the angular application for link previews on different websites

API

Instead of having a separate Angular platform to support the Universal API we aim to augment the platformServer in @angular/platform-server which already provides the basic support for running Angular in Node.js environment.

Very roughly the usage of this API would look like -

import {platformServer} from '@angular/platform-server';
import {AppServerModuleNgFactory} from './server.ngfactory';
…
// Per Request to avoid cross-talk.
const platform = platformServer([
  {provide: INITIAL_CONFIG, useValue: {
    url: '...',
    document: '...',
  }}
]);

// Long-form rendering
platform
  .bootstrapModuleFactory(MyAppModuleFactory)
  .then((ref: ApplicationRef) => ref.isStable.filter(v => v).toPromise())
  .then(() => platform.injector.get(PlatformState).renderToString())
  .then(html => ...)
  .then(() => platform.destroy());

The two main options to be passed in are the document string which represents the whole document from what would be the index.html on the client side app and the current app URL. These are specified through the INITIAL_CONFIG provider on the platform.

There will be a convenient API for the most common use case of bootstrapping and rendering a single application -

Import {renderModuleFactory, renderModule} from '@angular/platform-server'

// Short-form rendering
renderModuleFactory(MyAppModuleFactory, {url: '...', document: '...', providers: [..]}).then(html => …);

The other main addition will be the ServerModule in @angular/platform-server that corresponds to the BrowserModule in the client side. We recommend that you have a separate top-level App Browser Module and an App Server Module where you specify your platform specific providers including BrowserModule and ServerModule respectively.

Any extra data to be passed in to the server application will be done through providers.

Implementation details

• Keep the current implementation of the renderer in platformServer and make changes to it as needed to support Universal use cases.

• Refactor Http module to be platform independent and move the platform dependent parts into platformBrowser and platformServer.

• Provide a server side Location service.

• Use the current Metatags service for any met tags manipulation required for link previews.

• We will make the server implementation of Http(most probably based on XHR2) on the server platform to be Zone aware. We will provide guidelines on how to make other asynchronous Node libraries Zone aware - so that the server side application knows when the rendering is actually complete.

• Provide a way to test Universal ready Components and Application. We already run all internal Angular tests in the Node environment. We will provide helper utilities to make it easier to test your Universal ready Components on both Node and browser.

• Update the Universal starter to use the new API

Thanks,
Vikram Subramanian and Alex Rickabaugh