From 4975a106dc304974e459777e03c739ab575586c0 Mon Sep 17 00:00:00 2001 From: Santosh Yadav Date: Mon, 31 May 2021 01:18:23 +0530 Subject: [PATCH] docs(platform-server): added commands for universal and add prerendering info (#36005) Fixes #36004 PR Close #36005 --- .pullapprove.yml | 1 + aio/content/guide/prerendering.md | 69 +++++++++++++++++++++++++++++++ aio/content/guide/universal.md | 24 +++++++++++ aio/content/navigation.json | 25 ++++++----- 4 files changed, 109 insertions(+), 10 deletions(-) create mode 100644 aio/content/guide/prerendering.md diff --git a/.pullapprove.yml b/.pullapprove.yml index 6b03a5d858..2130e2ae30 100644 --- a/.pullapprove.yml +++ b/.pullapprove.yml @@ -560,6 +560,7 @@ groups: - > contains_any_globs(files, [ 'packages/platform-server/**', + 'aio/content/guide/prerendering.md', 'aio/content/guide/universal.md', 'aio/content/examples/universal/**' ]) diff --git a/aio/content/guide/prerendering.md b/aio/content/guide/prerendering.md new file mode 100644 index 0000000000..563164dfac --- /dev/null +++ b/aio/content/guide/prerendering.md @@ -0,0 +1,69 @@ +# Prerendering static pages + +Angular Universal allows you to prerender the pages of your application. Prerendering is the process where a dynamic page is processed at build time generating static HTML. + +## How to prerender a page + +To prerender a static page make sure to add SSR capabilities to your application. +For more information see the [universal guide](guide/universal). +Once SSR is added, run the following command: + + +npm run prerender + + +### Build options for prerendering + +When you add prerendering to your application, the following build options are available: + +* `browserTarget`: Specify the target to build. +* `serverTarget`: Specify the Server target to use for prerendering the application. +* `routes`: Define an array of additional routes to prerender. +* `guessRoutes`: Whether builder should extract routes and guess which paths to render. Defaults to `true`. +* `routesFile`: Specify a file that contains a list of all routes to prerender, separated by newlines. This option is useful if you have a large number of routes. +* `numProcesses`: Specify the number of CPUs to be used while running the prerendering command. + +### Prerendering dynamic routes + +You can prerender dynamic routes. An example of a dynamic route is `product/:id`, where `id` is dynamically provided. + +To prerender dynamic routes, choose one from the following options: + * Provide additional routes in the command line + * Provide routes using a file + * Prerender specific routes + +#### Provide additional routes in the command line + +While running the prerender command, you can provide additional routes. For example: + + +ng run <app-name>:prerender --routes /product/1 /product/2 + + + +#### Providing additonal routes using a file + +You can provide routes using a file to generate static pages. This method is useful if you have a large number of routes to generate, such as product details for an e-commerce application, which may come from an external source (Database or CMS). + +To provide routes using a file, use the `--routes-file` option with the name of a `.txt` file containing the routes. + +For example, you could generate this file by using a script to extract IDs from a database and save them to a `routes.txt` file: + + + /products/1 + /products/555 + + +When your `.txt` file is ready, run the following command to prerender the static files with dynamic values: + + +ng run <app-name>:prerender --routes-file routes.txt + + +#### Prerendering specific routes + +You can also pass specific routes to the prerender command. If you choose this option, make sure to disable the `guessRoutes` option. + + +ng run <app-name>:prerender --no-guess-routes --routes /product/1 /product/1 + \ No newline at end of file diff --git a/aio/content/guide/universal.md b/aio/content/guide/universal.md index 75ce0e388b..5c72b7c32a 100644 --- a/aio/content/guide/universal.md +++ b/aio/content/guide/universal.md @@ -290,3 +290,27 @@ Here, "request URL" refers to the URL of the request as a response to which the For example, if the client requested `https://my-server.com/dashboard` and you are rendering the application on the server to respond to that request, `options.url` should be set to `https://my-server.com/dashboard`. Now, on every HTTP request made as part of rendering the application on the server, Angular can correctly resolve the request URL to an absolute URL, using the provided `options.url`. + +### Useful scripts + +- `npm run dev:ssr` + + This command is similar to [`ng serve`](cli/serve), which offers live reload during development, but uses server-side rendering. The application will run in watch mode and refresh the browser after every change. + This command is slower than the actual `ng serve` command. + +- `ng build && ng run app-name:server` + + This command builds both the server script and the application in production mode. + Use this command when you want to build the project for deployment. + +- `npm run serve:ssr` + + This command starts the server script for serving the application locally with server-side rendering. + It uses the build artifacts created by `ng run build:ssr`, so make sure you have run that command as well. + + Note that `serve:ssr` is not intended to be used to serve your application in production, but only for testing the server-side rendered application locally. + +- `npm run prerender` + + This script can be used to prerender an application's pages. + You can read more about prerendering [here](guide/prerendering). diff --git a/aio/content/navigation.json b/aio/content/navigation.json index 74ec5993c5..938c05ffc2 100644 --- a/aio/content/navigation.json +++ b/aio/content/navigation.json @@ -446,6 +446,21 @@ "tooltip": "Configuring service worker caching behavior." } ] + }, + { + "url": "guide/web-worker", + "title": "Web Workers", + "tooltip": "Using web workers for background processing." + }, + { + "url": "guide/universal", + "title": "Server-side Rendering", + "tooltip": "Render HTML server-side with Angular Universal." + }, + { + "url": "guide/prerendering", + "title": "Prerendering", + "tooltip": "Prerender HTML server-side with Angular Universal." } ] }, @@ -536,11 +551,6 @@ "title": "CLI Builders", "tooltip": "Using builders to customize Angular CLI." }, - { - "url": "guide/universal", - "title": "Server-side Rendering", - "tooltip": "Render HTML server-side with Angular Universal." - }, { "url": "guide/language-service", "title": "Language Service", @@ -629,11 +639,6 @@ "title": "Building a Template-driven Form", "tooltip": "Create a template-driven form using directives and Angular template syntax." }, - { - "url": "guide/web-worker", - "title": "Web Workers", - "tooltip": "Using web workers for background processing." - }, { "title": "Angular Libraries", "tooltip": "Extending Angular with shared libraries.",