Skip to content

Commit caf4aaf

Browse files
gedinakovagedinakova
authored
Merge branch 'vnext' into thristodorova/fix-5998
2 parents e2993c6 + 82d1d22 commit caf4aaf

File tree

1 file changed

+21
-93
lines changed

1 file changed

+21
-93
lines changed

‎en/components/general/ssr-rendering.md‎

Lines changed: 21 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -1,145 +1,73 @@
11
---
2-
title: Server-side rendering | Angular Universal | Ignite UI for Angular | Infragistics
3-
_description: How to use Angular Universal rendering with Ignite UI for Angular.
4-
_keywords: Ignite UI for Angular, Universal, Server-side rendering
2+
title: Server-side rendering | Angular SSR | Ignite UI for Angular | Infragistics
3+
_description: How to use Angular Server-side rendering with Ignite UI for Angular.
4+
_keywords: Ignite UI for Angular, Angular SSR, Server-side rendering
55
---
66

7-
# Server-side Rendering with Angular Universal
7+
# Server-side Rendering with Angular SSR
88

99
This topic aims at describing what Server-side Rendering is and how to configure it within Ignite UI for Angular application.
1010

11-
## Angular Universal
11+
## Angular Server-side rendering
1212

13-
All Angular applications run in the client's browser and often this may result in a negative performance hit on the [First Meaningful Paint (FMP)](https://web.dev/first-meaningful-paint) i.e. when a browser first renders the primary content of a page. This is when [Angular Universal](https://angular.io/guide/universal) comes in handy, you can generate the full HTML for a page on the server. It renders a client-side page to HTML on the server that is later bootstrapped on the client. Okay, but how it works?
13+
All Angular applications run in the client's browser and often this may result in a negative performance hit on the [Largest Contentful Paint (LCP)](https://web.dev/articles/lcp) i.e. when a browser first renders the largest content of a page. This is when [Angular SSR](https://angular.dev/guide/ssr) comes in handy, you can generate the full HTML for a page on the server. It renders a client-side page to HTML on the server that is later bootstrapped on the client. Okay, but how it works?
1414

15-
> [FMP](https://web.dev/first-meaningful-paint) measures when the primary content of a page is visible to the user, as for [FCP](https://web.dev/first-contentful-paint) metric, it measures how long it takes the browser to render the first piece of DOM content after a user navigates to your page. See [Lighthouse performance scoring](https://web.dev/performance-scoring) for more information.
15+
> [LCP](https://web.dev/articles/lcp) measures when the largest content of a page is visible to the user, as for [FCP](https://web.dev/first-contentful-paint) metric, it measures how long it takes the browser to render the first piece of DOM content after a user navigates to your page. See [Lighthouse performance scoring](https://web.dev/performance-scoring) for more information.
1616
1717

1818

1919
## How it works?
2020

21-
With Angular Universal, you will serve a static version of your apps' landing page, while at the same time the full Angular application loads in the background. The landing page will be pure HTML and will be displayed even if the JavaScript is disabled. More about Server Rendering you can find [here](https://developers.google.com/web/updates/2019/02/rendering-on-the-web).
21+
With Angular SSR, you will serve a static version of your apps' landing page, while at the same time the full Angular application loads in the background. The landing page will be pure HTML and will be displayed even if the JavaScript is disabled. More about Server Rendering you can find [here](https://developers.google.com/web/updates/2019/02/rendering-on-the-web).
2222

2323
## Usage
2424

2525
Server-side rendering is one of the many techniques part of [Rendering on Web](https://developers.google.com/web/updates/2019/02/rendering-on-the-web) guidelines, that can:
2626
- Ease web crawlers to index your website higher in searches - will improve your Search Engine Optimization (SEO).
2727
- Show the first page quickly - slow initial page load is disengaging for the users (if it takes more than 3 seconds to load).
28-
- Improve your app performance - it will have a positive impact on both [First Meaningful Paint](https://web.dev/first-meaningful-paint) and [First Contentful Paint](https://web.dev/first-contentful-paint).
28+
- Improve your app performance - it will have a positive impact on both [First Contentful Paint](https://web.dev/first-contentful-paint) and [Largest Contentful Paint](https://web.dev/articles/lcp).
2929

3030
> It gives you full control over SEO and social-media previews, and it improves the overall perceived performance of your application by allowing users to see an initial painted view.
3131
3232
## Add SSR to existing Ignite UI application
3333

34-
### Step 1 - Add @nguniversal
34+
### Step 1 - Add @angular/ssr
3535
By using Angular CLI schematic we can run the following command:
3636

3737
```
38-
ng add @nguniversal/express-engine --clientProject ssr-example
38+
ng add @angular/ssr
3939
```
4040

41-
This schematic will perform several changes to your app client and server configurations, as well as npm commands and app.module updates.
42-
43-
### Step 2 - Define all browser-specific objects that are missing
44-
Since Universal apps run on the server and not in the browser, there are a few things you need to watch out for in your code. Browser-specific objects, such as `window`, `document`, or `location` are missing, so we recommend using of [domino](https://github.com/fgnass/domino#server-side-dom-implementation-based-on-mozillas-domjs) for Server-side DOM abstraction. Domino is a Server-side DOM implementation based on Mozilla's dom.js.
45-
46-
- install domino `npm install domino` - for server-side dom abstraction
47-
- install xmlhttprequest `npm i xmlhttprequest` - If using IgxIconService to register icons
48-
- Configure the "server.ts"
49-
50-
```typescript
51-
// server.ts
52-
const domino = require('domino');
53-
const fs = require('fs');
54-
const path = require('path');
55-
const template = fs
56-
.readFileSync(path.join('dist/browser', 'index.html'))
57-
.toString();
58-
const window = domino.createWindow(template);
59-
60-
// Ignite UI browser objects abstractions
61-
(global as any).window = window;
62-
(global as any).document = window.document;
63-
(global as any).Event = window.Event;
64-
(global as any).KeyboardEvent = window.KeyboardEvent;
65-
(global as any).MouseEvent = window.MouseEvent;
66-
(global as any).FocusEvent = window.FocusEvent;
67-
(global as any).PointerEvent = window.PointerEvent;
68-
(global as any).HTMLElement = window.HTMLElement;
69-
(global as any).HTMLElement.prototype.getBoundingClientRect = () => {
70-
return {
71-
left: '',
72-
right: '',
73-
top: '',
74-
bottom: ''
75-
};
76-
};
77-
78-
// If using IgxIconService to register icons
79-
(global as any).XMLHttpRequest = require('xmlhttprequest').XMLHttpRequest;
80-
81-
// Other optional depending on your application configuration
82-
(global as any).object = window.object;
83-
(global as any).navigator = window.navigator;
84-
(global as any).localStorage = window.localStorage;
85-
(global as any).DOMTokenList = window.DOMTokenList;
86-
```
41+
This schematic will perform several changes to your app client and server configurations, as well as add extra files to the project structure.
8742

88-
### Step 3 - Start your universal app
43+
### Step 2 - Start your Angular SSR app
8944
Run the following command:
9045

9146
```
92-
npm run build:ssr && npm run serve:ssr
47+
ng serve
9348
```
9449

95-
> As alternative to [Angular Express Engine](https://github.com/angular/universal/blob/master/modules/express-engine/README.md) you may use [ASP.NET Core Engine](https://github.com/angular/universal/tree/master/modules/aspnetcore-engine) for running Angular Apps with Server-side Rendering.
96-
9750
## Build a new application from scratch
9851

99-
1. Use `ng new` or the [Ignite UI CLI](./cli/getting-started-with-cli.md) `ig new` command.
52+
1. Use `ng new` or the [Ignite UI CLI](./cli/getting-started-with-cli.md) `ig new` command. Alternatively, use `ng new --ssr` to create a new Angular SSR project directly, skipping step 3.
10053
2. Execute `ng add igniteui-angular` which installs the library's npm packages to your workspace and configures the project in the current working directory to use that library.
101-
4. Add Angular Universal with `ng add @nguniversal/express-engine --clientProject ig-ssr-example`. "ig-ssr-example" is your project name.
102-
3. Add Ignite UI for Angular components - e.g. Grid, Calendar et
103-
4. Configure the "server.ts" file to define all needed browser-specific objects, such as "window", "document", or "location".
104-
- install domino `npm install domino` - for server-side dom abstraction
105-
- install xmlhttprequest `npm i xmlhttprequest` - If using IgxIconService to register icons
106-
107-
## Use starter project
108-
109-
Use the starter project that includes Ignite UI for Angular components. The project uses Angular CLI to quickly build a simple application with Angular Universal.
110-
111-
### Step 1 - Clone the starter repository
112-
113-
```
114-
git clone https://github.com/IgniteUI/ng-universal-example.git
115-
```
116-
117-
### Step 2 - Use NPM to install the needed dependencies
118-
119-
```
120-
npm install
121-
```
122-
123-
### Step 3 - Build and start the application by using:
124-
125-
```
126-
npm run build:ssr && npm run serve:ssr
127-
```
54+
3. Add Angular SSR with `ng add @angular/ssr`.
55+
4. Add Ignite UI for Angular components - e.g. Grid, Calendar
12856

12957
## Other considerations
13058

13159
- If your application is using other browser-specific objects, wrap their usage in a conditional statement, so that they’ll only be used by Angular on the browser. You can do this by importing the functions `isPlatformBrowser` and `isPlatformServer` from `@angular/common`, injecting the `PLATFORM_ID` token into your component, and running the imported functions to see whether you’re on the server or the browser.
13260
- If using ElementRef for HTML element handling, don’t use the nativeElement to manipulate attributes on the element. Instead, inject and use the [Renderer2 methods](https://alligator.io/angular/using-renderer2).
13361
- All URLs for server requests should be absolute, keep in mind that data requests from relative URLs will fail when running from the server.
134-
- For handling browser events the Angular team provides the [preboot](https://github.com/angular/preboot) library. This library buffers the events and replay them once the client-side script is loaded.
135-
- When using Angular Universal, the server will pre-render pages that will be visible to the users, however, interactions will be limited. Once the client-side app is loaded in the background, it will seamlessly switch from showing the server-rendered pages to the client-side app.
62+
- For handling browser events the Angular team provides the [withEventReplay()](https://angular.dev/guide/hydration#capturing-and-replaying-events) function. This feature allows to capture all events that happen before hydration and replay those events once hydration has completed.
63+
- If using IgxIconService to register icons please make sure that you have configured [provideHttpClient()](https://angular.dev/api/common/http/provideHttpClient) in your providers.
64+
- When using Angular SSR, the server will pre-render pages that will be visible to the users, however, interactions will be limited. Once the client-side app is loaded in the background, it will seamlessly switch from showing the server-rendered pages to the client-side app.
13665

13766
## Useful resources
13867

13968
<div class="divider--half"></div>
14069

141-
* [Angular Universal guide](https://angular.io/guide/universal)
142-
* [Ignite UI Starter Kit](https://github.com/IgniteUI/ng-universal-example)
70+
* [Angular SSR guide](https://angular.dev/guide/ssr)
14371
* [Server-side rendering terminology](https://developers.google.com/web/updates/2019/02/rendering-on-the-web)
14472
* [Getting started with Ignite UI for Angular](getting-started.md)
14573
* [Ignite UI CLI Guide](cli/step-by-step-guide-using-cli.md)

0 commit comments

Comments
 (0)