docs: update universal doc#36005
Conversation
gkalpak
left a comment
There was a problem hiding this comment.
Thx, @santoshyadav198613!
I see you mentioned v9 in the guide. If it is a requirement, then this PR should probably wait for #34374 (which will upgrade the docs examples to use v9 and Ivy). I will also be updating the universal example to match the guide as part of #34374, so it is good idea to wait for that anyway.
Keep in mind that we should make sure that the commands/code shown in the guide should directly apply to the example app we offer for download (which is derived from the universal example).
Yes my plan was to update the sample as well, but than I found your PR, we should wait til your PR is merged to avoid the mismatch. |
|
@santoshyadav198613, thanks for this. I’ll try to review it in the coming days! |
|
Hi @kapunahelewong , |
|
Please do not merge this before the |
|
I'll try to review this in the coming days, but since it was blocked I didn't give this priority. |
|
FYI, here is the PR that this needs to be merged after: #36483 |
3475c35 to
23ae32c
Compare
|
Hi @gkalpak, @alan-agius4, |
There was a problem hiding this comment.
I think the entire section needs to be updated a bit more, for a couple of reasons.
- The guide is titled
Server-side rendering (SSR) with Angular Universal. Prerendering is not a sub topic of SSR, but rather a different strategy. Maybe, we can split this guide in multiple sections?. - We need to explain what is the different between SSR and Prerendering, as otherwise how will developers know which strategy is best for them?
There was a problem hiding this comment.
Can we explain what each of the above commands do?
Useful Scripts
npm run dev:ssr
Runs the browser and server applications in the development mode. The applications will run in watch mode, when doing changes the browser will refresh and the server will be restarted.
npm run build:ssr
Builds the browser and server applications in production mode. Shortcut for: ng build --prod && ng run app-name:server:production
npm run serve:ssr
Launches the Node.js server and runs the server application.
Note: phases can be improved, just a short example.
There was a problem hiding this comment.
Providing all routes via file, the title here is confusion. Because when using the routeFile option, you don't need to provide all the routes. Since routes will be merged with the once provided via the routes option and those which are guessed via the parser.
I think it may be best to explain each builder option. Example, from the doc, I don't understand how can I opt out of route guessing etc..., as while these options are used for dynamic routes, they can be used for other use cases.
So my suggestion would be to explain the options, and than have a separate sub section for dynamic routes.
There was a problem hiding this comment.
Providing manual routes -> Providing additional routes
Clarify when the --routes can be used, even outside of dynamic routes concept.
There was a problem hiding this comment.
This is actually not a feature of Angular 9, but rather of Angular Universal version 9.
|
Thanks @alan-agius4 , |
23ae32c to
f597fed
Compare
There was a problem hiding this comment.
| To create production build Angular Universal provides commands to build and test before deployment | |
| To create a production build, use commands provided in Angular Universal to build and test before deployment. |
There was a problem hiding this comment.
| Just run the below command to Run and Test your Universal Application locally: | |
| Run the following command to run and test your universal application locally: |
There was a problem hiding this comment.
| With release of Angular 9 it is possible to prerender the static pages as part of the build, it uses the guess parser to prerender the static pages. | |
| As of of Angular Universal version 9, you can now pre-render the static pages as part of the build using the guess parser. |
There was a problem hiding this comment.
| You can run the below command to prerender static page: | |
| To pre-render a static page, run the following command: |
There was a problem hiding this comment.
| ### Prerendering Dynamic Routes | |
| ### Pre-rendering Dynamic Routes |
There was a problem hiding this comment.
| The above option is good where we have limited number of parameters, but what in case we have many records and in database and we want to generate static pages, this is where the second option fits in. | |
| Provide routes in a file to generate static pages if you have many more parameters, such as multiple records in a database. |
There was a problem hiding this comment.
| #### Providing all routes via file | |
| #### Providing all routes in a file |
There was a problem hiding this comment.
| You can pass a `.txt` file with list of `id` with `--routeFile` option with `prerender` command. | |
| To pass a `.txt` file with a list of IDs, use the `--routeFile` option with the `prerender` command. |
There was a problem hiding this comment.
| You can fetch list of ids using nodejs and create a `routes.txt` file with values like: | |
| You can fetch list of IDs using Node.js, and create a `routes.txt` file with values such as the following: |
There was a problem hiding this comment.
| and once txt file is ready, run the below command to prerender the static files with dynamic values: | |
| When your `.txt` file is ready, run the following command to pre-render the static files with dynamic values: |
f597fed to
5f5eb70
Compare
gkalpak
left a comment
There was a problem hiding this comment.
Thx for making the changes, @santoshyadavdev 🏅
I have left a few more (mostly minor) comments/suggestions. PTAL
There was a problem hiding this comment.
| Angular Universal allows you to prerender the pages, prerendering is a process where your page is processed as static page at the build time. | |
| Angular Universal allows you to prerender the pages. Prerendering is processing your page as a static page at build time. |
Suggested for clarity.
There was a problem hiding this comment.
| * `serverTarget`: Specify the Server target to use for prerenering the application. | |
| * `serverTarget`: Specify the Server target to use for prerendering the application. |
Fixed spello
There was a problem hiding this comment.
| * `numProcesses`: Specify the number of CPUs to be used while running prerendering command. | |
| * `numProcesses`: Specify the number of CPUs to be used while running the prerendering command. |
Word missing.
There was a problem hiding this comment.
| ## Command to Prerender a static page | |
| ## Command to prerender a static page |
Per style guide: Use sentence case for headings and titles.
There was a problem hiding this comment.
| # Prerendering Static Pages | |
| # Prerendering static pages |
Developer documentation style guide says: Use sentence case for headings and titles.
There was a problem hiding this comment.
| #### Provide additional routes in the command-line | |
| #### Provide additional routes in the command line |
Not hyphenated when used as a noun.
There was a problem hiding this comment.
Should newlines be one or two words?
There was a problem hiding this comment.
| To prerender dynamic routes, you can choose one from the following options: | |
| To prerender dynamic routes, choose one from the following options: |
Edited for clarity. Does this edit keep your meaning?
There was a problem hiding this comment.
| You can provide routes using a file to generate static pages. This method is useful if you have a large number of routes to be generate, such as product details for an ecommerce application, which may come from a external source (Database or CMS). | |
| 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 ecommerce application, which may come from an external source (Database or CMS). |
There was a problem hiding this comment.
| This script can be used to prerender the pages you can read more about prerendering [here](guide/prerendering) | |
| This script can be used to prerender the pages. You can read more about prerendering [here](guide/prerendering) |
From the style guide: apply the following guidelines when you write link text:
When you write a complete sentence that refers the reader to another topic, introduce the link with the phrase For more information, see... or For more information about..., see. Also, write unique, descriptive link text that makes sense without the surrounding text. Don't use phrases like click here or this document. They're bad for accessibility and scannability.
|
Standard editing pass complete with a few comments.
…On Tue, May 25, 2021 at 4:00 AM George Kalpakas ***@***.***> wrote:
***@***.**** requested changes on this pull request.
Thx for making the changes, @santoshyadavdev
<https://github.com/santoshyadavdev> 🏅
I have left a few more (mostly minor) comments/suggestions. PTAL
------------------------------
In aio/content/guide/universal.md
<#36005 (comment)>:
> @@ -284,3 +284,21 @@ 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` <https://my-server.com/dashboard> and you are rendering the app on the server to respond to that request, `options.url` should be set to `https://my-server.com/dashboard` <https://my-server.com/dashboard>.
Now, on every HTTP request made as part of rendering the app 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`
+
+Note that this command is intended to be used for testing the server-side rendered application locally.
I think it would be helpful to mention what this command does (in addition
to what it is good for). I would also add that this command assumes you
have already run build:ssr (i.e. that it uses the build artifacts created
by build:ssr).
What about something like:
⬇️ Suggested change
-Note that this command is intended to be used for testing the server-side rendered application locally.
+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 app in production, but only for testing the server-side rendered application locally.
------------------------------
In aio/content/guide/universal.md
<#36005 (comment)>:
> +
+- `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`
+
+Note that this command is intended to be used for testing the server-side rendered application locally.
+
+- `npm run prerender`
+
+This script can be used to prerender the pages you can read more about prerendering [here](guide/prerendering)
⬇️ Suggested change
-This script can be used to prerender the pages you can read more about prerendering [here](guide/prerendering)
+This script can be used to prerender an application's pages. You can read more about prerendering [here](guide/prerendering).
------------------------------
In aio/content/guide/prerendering.md
<#36005 (comment)>:
> @@ -0,0 +1,67 @@
+# Prerendering Static Pages
+
+Angular Universal allows you to prerender the pages, prerendering is a process where your page is processed as static page at the build time.
Minor suggestion:
⬇️ Suggested change
-Angular Universal allows you to prerender the pages, prerendering is a process where your page is processed as static page at the build time.
+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.
------------------------------
In aio/content/guide/prerendering.md
<#36005 (comment)>:
> @@ -0,0 +1,67 @@
+# Prerendering Static Pages
+
+Angular Universal allows you to prerender the pages, prerendering is a process where your page is processed as static page at the build time.
+
+## Command to Prerender a static page
I would suggest:
⬇️ Suggested change
-## Command to Prerender a static page
+## How to prerender a page
------------------------------
In aio/content/guide/prerendering.md
<#36005 (comment)>:
> @@ -0,0 +1,67 @@
+# Prerendering Static Pages
+
+Angular Universal allows you to prerender the pages, prerendering is a process where your page is processed as static page at the build time.
+
+## Command to Prerender a static page
+
+To prerender a static page, run the following command:
+
+<code-example language="sh">
+npm run prerender
Before prompting users to run this command, I think we should mention
(maybe at the top of the guide) you should have added SSR capabilities to
your application and point users to the Universal guide for more details
(or list it as a prerequisite).
------------------------------
In aio/content/guide/prerendering.md
<#36005 (comment)>:
> +Angular Universal allows you to prerender the pages, prerendering is a process where your page is processed as static page at the build time.
+
+## Command to Prerender a static page
+
+To prerender a static page, run the following command:
+
+<code-example language="sh">
+npm run prerender
+</code-example>
+
+### 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 prerenering the application.
⬇️ Suggested change
-* `serverTarget`: Specify the Server target to use for prerenering the application.
+* `serverTarget`: Specify the Server target to use for prerendering the application.
------------------------------
In aio/content/guide/prerendering.md
<#36005 (comment)>:
> +
+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 prerenering 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 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, you can choose one from the following options:
+ * Provide additional routes
⬇️ Suggested change
- * Provide additional routes
+ * Provide additional routes in the command-line
------------------------------
In aio/content/guide/prerendering.md
<#36005 (comment)>:
> +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 prerenering 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 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, you can choose one from the following options:
+ * Provide additional routes
+ * Provide all routes using a file
Based on #36005 (comment)
<#36005 (comment)>, I
would remove all:
⬇️ Suggested change
- * Provide all routes using a file
+ * Provide routes using a file
------------------------------
In aio/content/guide/prerendering.md
<#36005 (comment)>:
> + * Provide additional routes
+ * Provide all 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:
+
+<code-example language="sh">
+ng run <app-name>:prerender --routes /product/1 /product/2
+</code-example>
+
+
+#### 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 be generate, such as product details for an ecommerce application, which may come from a external source (Database or CMS).
⬇️ Suggested change
-You can provide routes using a file to generate static pages. This method is useful if you have a large number of routes to be generate, such as product details for an ecommerce application, which may come from a external source (Database or CMS).
+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 a external source (Database or CMS).
------------------------------
In aio/content/guide/prerendering.md
<#36005 (comment)>:
> +While running the prerender command, you can provide additional routes. For example:
+
+<code-example language="sh">
+ng run <app-name>:prerender --routes /product/1 /product/2
+</code-example>
+
+
+#### 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 be generate, such as product details for an ecommerce application, which may come from a external source (Database or CMS).
+
+To provide routes using a file, use the `--route-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:
+
+<code-example>
To prevent automatic code highlighting (since this is not code), you can
add language="none":
⬇️ Suggested change
-<code-example>
+<code-example language="none">
You could also add a header to make it more clear that you are showing the
.txt file:
⬇️ Suggested change
-<code-example>
+<code-example language="none" header="routes.txt">
------------------------------
In aio/content/guide/prerendering.md
<#36005 (comment)>:
> + * Prerender specific routes
+
+#### Provide additional routes in the command-line
+
+While running the prerender command, you can provide additional routes. For example:
+
+<code-example language="sh">
+ng run <app-name>:prerender --routes /product/1 /product/2
+</code-example>
+
+
+#### 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 be generate, such as product details for an ecommerce application, which may come from a external source (Database or CMS).
+
+To provide routes using a file, use the `--route-file` option with the name of a `.txt` file containing the routes.
If am not mistaken, the option name is --routes-file (with an s), right?
⬇️ Suggested change
-To provide routes using a file, use the `--route-file` option with the name of a `.txt` file containing the routes.
+To provide routes using a file, use the `--routes-file` option with the name of a `.txt` file containing the routes.
------------------------------
In aio/content/guide/prerendering.md
<#36005 (comment)>:
> + /products/1
+ /products/555
+</code-example>
+
+When your `.txt` file is ready, run the following command to prerender the static files with dynamic values:
+
+<code-example language="sh">
+ng run <app-name>:prerender --routes-file routes.txt
+</code-example>
+
+#### 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.
+
+<code-example language="sh">
+ng run <app-name>:prerender --routes=product --no-guess-routes=false
⬇️ Suggested change
-ng run <app-name>:prerender --routes=product --no-guess-routes=false
+ng run <app-name>:prerender --no-guess-routes --routes product
So, what routes will this command prerender? Just /product?
If so, consider using the same routes as in other examples (i.e. /product/1
/product/2).
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#36005 (review)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AR4DPGQJPXJXQBZOTWCQECLTPN7NPANCNFSM4LFO3WNQ>
.
--
*--Teri Glover--*
*Technical Editor*
|
f5f0fbd to
a6756aa
Compare
|
Done @gkalpak @TeriGlover, there are was some similar comment from both of you, just kept one from George 😁. |
|
You can preview a6756aa at https://pr36005-a6756aa.ngbuilds.io/. |
gkalpak
left a comment
There was a problem hiding this comment.
Hopefully, the last round of comments ✨
a6756aa to
8e3217b
Compare
|
You can preview 8e3217b at https://pr36005-8e3217b.ngbuilds.io/. |
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
|
FYI, I've pushed a fixup commit with some final fixes. It is good to go as far as I'm concerned |
|
You can preview 050abce at https://pr36005-050abce.ngbuilds.io/. |
AndrewKushnir
left a comment
There was a problem hiding this comment.
LGTM 👍 Approving for code-ownership group.
|
This issue has been automatically locked due to inactivity. Read more about our automatic conversation locking policy. This action has been performed automatically by a bot. |
included the new feature like live reload and prerender using guess
parser
Fixes #36004
PR Checklist
Please check if your PR fulfills the following requirements:
PR Type
What kind of change does this PR introduce?
What is the current behavior?
Issue Number: #36004
What is the new behavior?
Does this PR introduce a breaking change?
Other information