-
-This is a **preview guide**.
-The Angular CLI is adding support for universal apps and
-we will realign this guide with the CLI as soon as possible.
-
-
-
A normal Angular application executes in the _browser_, rendering pages in the DOM in response to user actions.
**Angular Universal** generates _static_ application pages on the _server_
@@ -19,7 +11,7 @@ It can generate and serve those pages in response to requests from browsers.
It can also pre-generate pages as HTML files that you serve later.
This guide describes a Universal sample application that launches quickly as a server-rendered page.
-Meanwhile, the browser downloads the full client version and switches to it automatically after the code loads.
+Meanwhile, the browser downloads the full client version and switches to it automatically after the code loads.
@@ -35,21 +27,21 @@ which runs in a [node express](https://expressjs.com/) server.
There are three main reasons to create a Universal version of your app.
1. Facilitate web crawlers (SEO)
-1. Improve performance on mobile and low-powered devices
+1. Improve performance on mobile and low-powered devices
1. Show the first page quickly
{@a seo}
{@a web-crawlers}
#### Facilitate web crawlers
-Google, Bing, Facebook, Twitter and other social media sites rely on web crawlers to index your application content and make that content searchable on the web.
+Google, Bing, Facebook, Twitter and other social media sites rely on web crawlers to index your application content and make that content searchable on the web.
These web crawlers may be unable to navigate and index your highly-interactive, Angular application as a human user could do.
-Angular Universal can generate a static version of your app that is easy searchable, linkable, and navigable without JavaScript.
+Angular Universal can generate a static version of your app that is easily searchable, linkable, and navigable without JavaScript.
It also makes a site preview available since each URL returns a fully-rendered page.
-Enabling web crawlers is often referred to as
+Enabling web crawlers is often referred to as
[Search Engine Optimization (SEO)](https://static.googleusercontent.com/media/www.google.com/en//webmasters/docs/search-engine-optimization-starter-guide.pdf).
{@a no-javascript}
@@ -58,14 +50,14 @@ Enabling web crawlers is often referred to as
Some devices don't support JavaScript or execute JavaScript so poorly that the user experience is unacceptable.
For these cases, you may require a server-rendered, no-JavaScript version of the app.
-This version, however limited, may be the only practical alternative for
+This version, however limited, may be the only practical alternative for
people who otherwise would not be able to use the app at all.
{@a startup-performance}
#### Show the first page quickly
-Displaying the first page quickly can be critical for user engagement.
+Displaying the first page quickly can be critical for user engagement.
[53% of mobile site visits are abandoned](https://www.doubleclickbygoogle.com/articles/mobile-speed-matters/) if pages take longer than 3 seconds to load.
Your app may have to launch faster to engage these users before they decide to do something else.
@@ -89,10 +81,10 @@ You compile the client application with the `platform-server` module instead of
and run the resulting Universal app on a web server.
The server (a [Node Express](https://expressjs.com/) server in _this_ guide's example)
-passes client requests for application pages to Universal's `renderModuleFactory` function.
+passes client requests for application pages to Universal's `renderModuleFactory` function.
-The `renderModuleFactory` function takes as inputs a *template* HTML page (usually `index.html`),
-an Angular *module* containing components,
+The `renderModuleFactory` function takes as inputs a *template* HTML page (usually `index.html`),
+an Angular *module* containing components,
and a *route* that determines which components to display.
The route comes from the client's request to the server.
@@ -109,11 +101,11 @@ Because a Universal `platform-server` app doesn't execute in the browser, you ma
You won't be able reference browser-only native objects such as `window`, `document`, `navigator` or `location`.
If you don't need them on the server-rendered page, side-step them with conditional logic.
-Alternatively, look for an injectable Angular abstraction over the object you need such as `Location` or `Document`;
+Alternatively, look for an injectable Angular abstraction over the object you need such as `Location` or `Document`;
it may substitute adequately for the specific API that you're calling.
If Angular doesn't provide it, you may be able to write your own abstraction that delegates to the browser API while in the browser and to a satisfactory alternative implementation while on the server.
-Without mouse or keyboard events, a universal app can't rely on a user clicking a button to show a component.
+Without mouse or keyboard events, a universal app can't rely on a user clicking a button to show a component.
A universal app should determine what to render based solely on the incoming client request.
This is a good argument for making the app [routeable](guide/router).
@@ -129,45 +121,35 @@ The _Tour of Heroes_ tutorial is the foundation for the Universal sample describ
The core application files are mostly untouched, with a few exceptions described below.
You'll add more files to support building and serving with Universal.
-In this example, Webpack tools compile and bundle the Universal version of the app with the
+In this example, the Angular CLI compiles and bundles the Universal version of the app with the
[AOT (Ahead-of-Time) compiler](guide/aot-compiler).
A node/express web server turns client requests into the HTML pages rendered by Universal.
You will create:
* a server-side app module, `app.server.module.ts`
- * a Universal app renderer, `universal-engine.ts`
+ * an entry point for the server-side, `main.server.ts`
* an express web server to handle requests, `server.ts`
- * a TypeScript config file, `tsconfig.universal.json`
- * a Webpack config file, `webpack.config.universal.js`
+ * a TypeScript config file, `tsconfig.server.json`
+ * a Webpack config file for the server, `webpack.server.config.js`
When you're done, the folder structure will look like this:
-src/
+src/
index.html app web page
- index-universal.html * universal app web page template
main.ts bootstrapper for client app
+ main.server.ts * bootstrapper for server app
+ tsconfig.app.json TypeScript client configuration
+ tsconfig.server.json * TypeScript server configuration
+ tsconfig.spec.json TypeScript spec configuration
style.css styles for the app
- systemjs.config.js SystemJS client configuration
- systemjs-angular-loader.js SystemJS add-in
- tsconfig.json TypeScript client configuration
app/ ... application code
- dist/ * Post-build files
- client.js * AOT-compiled client bundle
- server.js * express server & universal app bundle
- index-universal.html * copy of the app web page template
- ... * copies of other asset files
- universal/ * folder for universal code
- app-server.module.ts * server-side application module
- server.ts * express web server
- universal-engine.ts * express template engine
-bs-config.json config file for lite server
+ app.server.module.ts * server-side application module
+server.ts * express web server
+tsconfig.json TypeScript client configuration
package.json npm configuration
-tsconfig.client.json * TypeScript client AOT configuration
-tsconfig.universal.json * TypeScript Universal configuration
-webpack.config.aot.js * Webpack client AOT configuration
-webpack.config.universal.js * Webpack Universal configuration
+webpack.server.config.js * Webpack server configuration
The files marked with `*` are new and not in the original tutorial sample.
@@ -177,26 +159,23 @@ This guide covers them in the sections below.
## Preparation
+Download the [Tour of Heroes](generated/zips/toh-pt6/toh-pt6.zip) project and install the dependencies from it.
+
{@a install-the-tools}
### Install the tools
-To get started, install these Universal and Webpack packages.
+To get started, install these packages.
- * `@angular/compiler-cli` - contains the AOT compiler.
* `@angular/platform-server` - Universal server-side components.
- * `webpack` - Webpack JavaScript bundler.
- * `@ngtools/webpack` - Webpack loader and plugin for bundling compiled applications.
- * `copy-webpack-plugin` - Webpack plugin to copy asset files to the output folder.
- * `raw-loader` - Webpack loader for text files.
- * `express` - node web server.
- * `@types/express` - TypeScript type definitions for express.
+ * `@nguniversal/module-map-ngfactory-loader` - For handling lazy-loading in the context of a server-render.
+ * `@nguniversal/express-engine` - An express engine for Universal applications.
+ * `ts-loader` - To transpile the server application
Install them with the following commands:
-npm install @angular/compiler-cli @angular/platform-server express --save
-npm install webpack @ngtools/webpack copy-webpack-plugin raw-loader @types/express --save-dev
+npm install --save @angular/platform-server @nguniversal/module-map-ngfactory-loader ts-loader @nguniversal/express-engine
{@a transition}
@@ -219,7 +198,7 @@ Replace that import with this one:
-Angular adds the `appId` value (which can be _any_ string) to the style-names of the server-rendered pages,
+Angular adds the `appId` value (which can be _any_ string) to the style-names of the server-rendered pages,
so that they can be identified and removed when the client app starts.
You can get runtime information about the current platform and the `appId` by injection.
@@ -234,7 +213,7 @@ You can get runtime information about the current platform and the `appId` by in
The tutorial's `HeroService` and `HeroSearchService` delegate to the Angular `Http` module to fetch application data.
These services send requests to _relative_ URLs such as `api/heroes`.
-In a Universal app, `Http` URLs must be _absolute_ (e.g., `https://my-server.com/api/heroes`)
+In a Universal app, `Http` URLs must be _absolute_ (e.g., `https://my-server.com/api/heroes`)
even when the Universal web server is capable of handling those requests.
You'll have to change the services to make requests with absolute URLs when running on the server
@@ -254,55 +233,17 @@ You don't provide `APP_BASE_HREF` in the browser version, so the `heroesUrl` rem
-You can ignore `APP_BASE_HREF` in the browser if you've specified `` in the `index.html`
+You can ignore `APP_BASE_HREF` in the browser if you've specified `` in the `index.html`
to satisfy the router's need for a base address, as the tutorial sample does.
-You will provide the `APP_BASE_HREF` in the universal version of the app (see how [below](#provide-origin)),
-so the `heroesUrl` becomes absolute.
-
-Do the same thing to the `HttpSearchService` constructor.
-You'll have to adjust the `http.get` call in the `search()` method as well.
-Here's the revised class.
-
-
-
-
-{@a build-client-app}
-
-#### Try locally first
-
-Open a terminal window and confirm that the client app still works in the browser.
-
-
-npm start
-
-
-When you are done, shut down the server with `ctrl-C`.
-
-
-
-If you get a "Cannot find module" error, see the explanation and resolution [below](#cannot-find-module)
-
-
-
-
-
{@a server-code}
## Server code
To run an Angular Universal application, you'll need a server that accepts client requests and returns rendered pages.
-Create a `universal/` folder as a sibling to the `app/` folder.
-
-Add to it the following three universal parts:
-
- 1. the [app server module](#app-server-module)
- 2. the [Universal engine](#universal-engine)
- 3. the [web server](#web-server)
-
{@a app-server-module}
### App server module
@@ -310,126 +251,90 @@ Add to it the following three universal parts:
The app server module class (conventionally named `AppServerModule`) is an Angular module that wraps the application's root module (`AppModule`) so that Universal can mediate between your application and the server.
`AppServerModule` also tells Angular how to bootstrap your application when running as a Universal app.
-Create an `app-server.module.ts` file in the `src/universal` directory with the following `AppServerModule` code:
+Create an `app.server.module.ts` file in the `src/app/` directory with the following `AppServerModule` code:
-
+
-Notice that it imports first the client app's `AppModule` and then Angular Universal's `ServerModule`.
+Notice that it imports first the client app's `AppModule`, the Angular Universal's `ServerModule` and the `ModuleMapLoaderModule`.
+
+The `ModuleMapLoaderModule` is a server-side module that allows lazy-loading of routes.
This is also the place to register providers that are specific to running your app under Universal.
-{@a universal-engine}
-
-### Universal template engine
-
-The Universal `renderModuleFactory` function turns a client's requests into server-rendered HTML pages.
-You'll call that function within a _template engine_ that's appropriate for your server stack.
-
-This guide's sample is written for [Node Express](https://expressjs.com/)
-so the engine takes the form of [Express template engine middleware](https://expressjs.com/en/guide/using-template-engines.html).
-
-Create a `universal-engine.ts` file in the `src/universal` directory with the following code.
-
-
-
-
-{@a render-module-factory}
-
-#### Rendering the page
-The call to Universal's `renderModuleFactory` is where the rendering magic happens.
-
-
-
-
-The first parameter is the `AppServerModule` that you wrote [earlier](#app-server-module).
-It's the bridge between the Universal server-side renderer and your application.
-
-The second parameter is an options object
-
-* `document` is the template for the page to render (typically `index.html`).
-
-
-* `url` is the application route (e.g., `/dashboard`), extracted from the client's request.
-Universal should render the appropriate page for that route.
-
-
-* `extraProviders` are optional Angular dependency injection providers, applicable when running on this server
-
-{@a provide-origin}
-
-You supply `extraProviders` when your app needs information that can only be determined by the currently running server instance.
-
-The required information in this case is the running server's origin, provided under the `APP_BASE_HREF` token, so that the app can [calculate absolute HTTP URLs](#http-urls).
-
-The `renderModuleFactory` function returns a _promise_ that resolves to the rendered page.
-
-It's up to your engine to decide what to do with that page.
-_This engine's_ promise callback returns the rendered page to the [web server](#web-server),
-which then forwards it to the client in the HTTP response.
-
{@a web-server}
### Universal web server
A _Universal_ web server responds to application _page_ requests with static HTML rendered by the [Universal template engine](#universal-engine).
-It receives and responds to HTTP requests from clients (usually browsers).
-It serves static assets such as scripts, css, and images.
+It receives and responds to HTTP requests from clients (usually browsers).
+It serves static assets such as scripts, css, and images.
It may respond to data requests, perhaps directly or as a proxy to a separate data server.
The sample web server for _this_ guide is based on the popular [Express](https://expressjs.com/) framework.
-_Any_ web server technology can serve a Universal app as long as it can call Universal's `renderModuleFactory`.
-The principles and decision points discussed below apply to any web server technology that you chose.
+ _Any_ web server technology can serve a Universal app as long as it can call Universal's `renderModuleFactory`.
+ The principles and decision points discussed below apply to any web server technology that you chose.
-Create a `server.ts` file in the `src/universal` directory and add the following code:
+Create a `server.ts` file in the root directory and add the following code:
-
+
-**This sample server is not secure!**
-Be sure to add middleware to authenticate and authorize users
-just as you would for a normal Angular application server.
+ **This sample server is not secure!**
+ Be sure to add middleware to authenticate and authorize users
+ just as you would for a normal Angular application server.
-{@a import-app-server-module-factory}
+{@a universal-engine}
+#### Universal template engine
-#### Import AppServerModule factory
+The important bit in this file is the `ngExpressEngine` function:
-Most of this server code is re-usable across many applications.
-The import of the `AppServerModule` couples it specifically to a single application.
-
-
+
-Your code editor may tell you that this import is incorrect.
-It refers to the source file for the `AppServerModule` factory which doesn't exist at design time.
+The `ngExpressEngine` is a wrapper around the universal's `renderModuleFactory` function that turns a client's requests into server-rendered HTML pages.
+You'll call that function within a _template engine_ that's appropriate for your server stack.
-That file _will exist_, briefly, during compilation. But it's never physically in the file system when you're editing `server.ts` and you must tell the compiler to generate this module factory file _before_ it compiles `server.ts`.
-[Learn how below](#universal-typescript-configuration).
+The first parameter is the `AppServerModule` that you wrote [earlier](#app-server-module).
+It's the bridge between the Universal server-side renderer and your application.
-#### Add the Universal template engine
+The second parameter is the `extraProviders`. It is an optional Angular dependency injection providers, applicable when running on this server.
-Express supports template engines such as the [Universal template engine](#universal-engine) you wrote earlier.
-You import that engine and register it with Express like this:
+{@a provide-origin}
-
-
+You supply `extraProviders` when your app needs information that can only be determined by the currently running server instance.
+
+The required information in this case is the running server's origin, provided under the `APP_BASE_HREF` token, so that the app can [calculate absolute HTTP URLs](#http-urls).
+
+The `ngExpressEngine` function returns a _promise_ that resolves to the rendered page.
+
+It's up to your engine to decide what to do with that page.
+_This engine's_ promise callback returns the rendered page to the [web server](#web-server),
+which then forwards it to the client in the HTTP response.
+
+
+
+ This wrappers are very useful to hide the complexity of the `renderModuleFactory`. There are more wrappers for different backend technologies
+ at the [Universal repository](https://github.com/angular/universal).
+
+
#### Filter request URLs
The web server must distinguish _app page requests_ from other kinds of requests.
It's not as simple as intercepting a request to the root address `/`.
-The browser could ask for one of the application routes such as `/dashboard`, `/heroes`, or `/detail:12`.
+The browser could ask for one of the application routes such as `/dashboard`, `/heroes`, or `/detail:12`.
In fact, if the app were _only_ rendered by the server, _every_ app link clicked would arrive at the server
as a navigation URL intended for the router.
@@ -447,9 +352,9 @@ So we can easily recognize the three types of requests and handle them different
An Express server is a pipeline of middleware that filters and processes URL requests one after the other.
-You configure the Express server pipeline with calls to `server.get()` like this one for data requests.
+You configure the Express server pipeline with calls to `app.get()` like this one for data requests.
-
+
@@ -478,12 +383,12 @@ If your server handles HTTP requests, you'll have to add your own security plumb
The following code filters for request URLs with no extensions and treats them as navigation requests.
-
+
#### Serve static files safely
-A single `server.use()` treats all other URLs as requests for static assets
+A single `app.use()` treats all other URLs as requests for static assets
such as JavaScript, image, and style files.
To ensure that clients can only download the files that they are _permitted_ to see, you will [put all client-facing asset files in the `/dist` folder](#universal-webpack-configuration)
@@ -491,118 +396,42 @@ and will only honor requests for files from the `/dist` folder.
The following express code routes all remaining requests to `/dist`; it returns a `404 - NOT FOUND` if the file is not found.
-
+
{@a universal-configuration}
## Configure for Universal
-The server application requires its own web page and its own build configuration.
-
-{@a index-universal}
-
-### Universal web page
-
-The universal app renders pages based on a host web page template.
-Simple universal apps make do with a slightly modified copy of the original `index.html`.
-
-
-
-If you build a production version of the client app with the CLI's `ng build --prod` command, you do not need a separate universal `index.html`.
-The CLI constructs a suitable `index.html` for you. You can skip this subsection and continue to [universal TypeScript configuration](#universal-typescript-configuration).
-
-Read on if you're building the app without the CLI.
-
-
-
-Create an `index-universal.html` as follows, shown next to the development `index.html` for comparison.
-
-
-
-
-
-
-
-
-
-
-
-The differences are few.
-
-* Load the minified versions of the `shim` and `zone` polyfills from the root (which will be `/dist`)
-
-* You won't use SystemJS for universal nor to load the client app.
-
-* Instead you'll load the [production version of the client app](#build-client), `client.js`, which is the result of AOT compilation, minification, and bundling.
-
-That's it for `index-universal.html`.
-Next you'll create two universal configuration files, one for TypeScript and one for Webpack.
+The server application requires its own build configuration.
{@a universal-typescript-configuration}
### Universal TypeScript configuration
-Create a `tsconfig.universal.json` file in the project root directory to configure TypeScript and AOT compilation of the universal app.
+Create a `tsconfig.server.json` file in the project root directory to configure TypeScript and AOT compilation of the universal app.
-
+
-Certain settings are noteworthy for their difference from the `tsconfig.json` in the `src/` folder.
-
-* The `module` property must be **es2015** because
- the transpiled JavaScript will use `import` statements instead of `require()` calls.
-
-
-* Point `"typeRoots"` to `"./node_modules/@types/"`
-
-
-* Set the `files` property (instead of `exclude`) to compile the `app-server.module` before the `universal-engine`,
- for the reason [explained above](#import-app-server-module-factory).
+This config extends from the root's `tsconfig.json` file. Certain settings are noteworthy for their differences.
+* The `module` property must be **commonjs** which can be require()'d into our server application.
* The `angularCompilerOptions` section guides the AOT compiler:
-
- * `genDir` - the temporary output directory for AOT compiled code.
- * `entryModule` - the root module of the client application, expressed as `path/to/file#ClassName`.
- * `skipMetadataEmit` - set `true` because you don't need metadata in the bundled application.
+ * `entryModule` - the root module of the server application, expressed as `path/to/file#ClassName`.
### Universal Webpack configuration
-Create a `webpack.config.universal.js` file in the project root directory with the following code.
+Universal applications doesn't need any extra Webpack configuration, the CLI takes care of that for you,
+but since the server is a typescript application, you will use Webpack to transpile it.
-
+Create a `webpack.server.config.js` file in the project root directory with the following code.
+
+
**Webpack configuration** is a rich topic beyond the scope of this guide.
-A few observations may clarify some of the choices.
-
-* Webpack walks the dependency graph from the two entry points to find all necessary universal application files.
-
-
-* The `@ngtools/webpack` loader loads and prepares the TypeScript files for compilation.
-
-
-* The `AotPlugin` runs the AOT compiler (`ngc`) over the prepared TypeScript, guided by the `tsconfig.universal.json` you created [above](#universal-typescript-configuration).
-
-
-* The `raw-loader` loads imported CSS and HTML files as strings.
-You may need additional loaders or configuration for other file types.
-
-
-* The compiled output is bundled into `dist/server.js`.
-
-
-* The `CopyWebpackPlugin` copies specific static files from their source locations into the `/dist` folder.
-These files include the universal app's web page template, `index-universal.html`,
-and the JavaScript and CSS files mentioned in it
-... with the notable exception of `client.js` [to be discussed below](#build-client).
-
-
-
-The `CopyWebpackPlugin` step is unnecessary if you [build the client](#build-client) with the CLI.
-
-
## Build and run with universal
@@ -613,8 +442,10 @@ First add the _build_ and _serve_ commands to the `scripts` section of the `pack
"scripts": {
...
- "build:uni": "webpack --config webpack.config.universal.js",
- "serve:uni": "node dist/server.js",
+ "build:universal": "npm run build:client-and-server-bundles && npm run webpack:server",
+ "serve:universal": "node dist/server.js",
+ "build:client-and-server-bundles": "ng build --prod && ng build --prod --app 1 --output-hashing=false",
+ "webpack:server": "webpack --config webpack.server.config.js --progress --colors"
...
}
@@ -626,32 +457,30 @@ First add the _build_ and _serve_ commands to the `scripts` section of the `pack
From the command prompt, type
-npm run build:uni
+npm run build:universal
-Webpack compiles and bundles the universal app into a single output file, `dist/server.js`, per the [configuration above](#universal-configuration).
-It also generates a [source map](https://webpack.js.org/configuration/devtool/), `dist/server.js.map` that correlates the bundle code to the source code.
-
-Source maps are primarily for the browser's [dev tools](https://developers.google.com/web/tools/chrome-devtools/javascript/source-maps), but on the server they help locate compilation errors in your components.
+The Angular CLI compiles and bundles the universal app into two different folders, `browser` and `server`.
+Webpack transpiles the `server.ts` file into Javascript.
{@a serve}
#### Serve
-After building the server bundle, start the server.
+After building the application, start the server.
-npm run serve:uni
+npm run serve:universal
-The console window should say
+The console window should say
-listening on port 3200...
+Node server listening on http://localhost:4000
## Universal in action
-Open a browser to http://localhost:3200/.
+Open a browser to http://localhost:4000/.
You should see the familiar Tour of Heroes dashboard page.
Navigation via `routerLinks` works correctly.
@@ -668,150 +497,24 @@ But clicks, mouse-moves, and keyboard entries are inert.
User events other than `routerLink` clicks aren't supported.
The user must wait for the full client app to arrive.
-It will never arrive until you compile the client app
+It will never arrive until you compile the client app
and move the output into the `dist/` folder,
a step you'll take in just a moment.
-#### Review the console log
-
-Open the browser's development tools.
-In the console window you should see output like the following:
-
-
-listening on port 3200...
-Running in the browser with appId=uni
-/styles.css
-/shim.min.js
-/zone.min.js
-/client.js
-Error: ENOENT: no such file or directory, stat '... dist/client.js' ...
-
-
-Most of the console log lines report requests for static files coming from the `` and `