Skip to content

docs: update universal doc#36005

Closed
santoshyadavdev wants to merge 2 commits into
angular:masterfrom
santoshyadavdev:feature/update-SSR-docs
Closed

docs: update universal doc#36005
santoshyadavdev wants to merge 2 commits into
angular:masterfrom
santoshyadavdev:feature/update-SSR-docs

Conversation

@santoshyadavdev

@santoshyadavdev santoshyadavdev commented Mar 11, 2020

Copy link
Copy Markdown
Contributor

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?

  • Bugfix
  • Feature
  • Code style update (formatting, local variables)
  • Refactoring (no functional changes, no api changes)
  • Build related changes
  • CI related changes
  • Documentation content changes
  • angular.io application / infrastructure changes
  • Other... Please describe:

What is the current behavior?

Issue Number: #36004

What is the new behavior?

Does this PR introduce a breaking change?

  • Yes
  • No

Other information

@pullapprove pullapprove Bot requested a review from kyliau March 11, 2020 06:52
@alan-agius4 alan-agius4 self-requested a review March 11, 2020 07:43
@gkalpak gkalpak added comp: docs area: server Issues related to server-side rendering state: blocked state: WIP feature Label used to distinguish feature request from other issues labels Mar 11, 2020
@ngbot ngbot Bot modified the milestone: needsTriage Mar 11, 2020
@gkalpak gkalpak added the target: patch This PR is targeted for the next patch release label Mar 11, 2020

@gkalpak gkalpak left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Comment thread aio/content/guide/universal.md Outdated
Comment thread aio/content/guide/universal.md Outdated
@santoshyadavdev

Copy link
Copy Markdown
Contributor Author

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.

@alan-agius4

Copy link
Copy Markdown
Contributor

@santoshyadav198613, thanks for this. I’ll try to review it in the coming days!

@santoshyadavdev

Copy link
Copy Markdown
Contributor Author

Hi @kapunahelewong ,
Can we get it reviewed, let me know if any changes are required.

@gkalpak

gkalpak commented Apr 6, 2020

Copy link
Copy Markdown
Member

Please do not merge this before the universal guide/example changes from #34374 are merged 🙏
#34374 is currently blocked on #36143, which was just approved. So once #36143 is merged, I'll extract the universal guide/example changes from #34374 into a separate PR. Once that new PR is merged, this can go in 🎉

@alan-agius4

Copy link
Copy Markdown
Contributor

I'll try to review this in the coming days, but since it was blocked I didn't give this priority.

@gkalpak

gkalpak commented Apr 7, 2020

Copy link
Copy Markdown
Member

FYI, here is the PR that this needs to be merged after: #36483

@santoshyadavdev

Copy link
Copy Markdown
Contributor Author

Hi @gkalpak, @alan-agius4,
I have merged the main PR into this, let me know if anything else needs to be changed.

Comment thread aio/content/guide/universal.md Outdated

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Comment thread aio/content/guide/universal.md Outdated

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread aio/content/guide/universal.md Outdated

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread aio/content/guide/universal.md Outdated

@alan-agius4 alan-agius4 Apr 22, 2020

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Providing manual routes -> Providing additional routes

Clarify when the --routes can be used, even outside of dynamic routes concept.

Comment thread aio/content/guide/universal.md Outdated

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is actually not a feature of Angular 9, but rather of Angular Universal version 9.

@santoshyadavdev

Copy link
Copy Markdown
Contributor Author

Thanks @alan-agius4 ,
Will make the changes.

@santoshyadavdev santoshyadavdev force-pushed the feature/update-SSR-docs branch from 23ae32c to f597fed Compare May 3, 2020 13:30
@santoshyadavdev santoshyadavdev marked this pull request as draft May 3, 2020 13:35
@kapunahelewong kapunahelewong requested a review from rockument69 May 7, 2020 17:10
Comment thread aio/content/guide/universal.md Outdated

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.

Comment thread aio/content/guide/universal.md Outdated

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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:

Comment thread aio/content/guide/universal.md Outdated

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.

Comment thread aio/content/guide/universal.md Outdated

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
You can run the below command to prerender static page:
To pre-render a static page, run the following command:

Comment thread aio/content/guide/universal.md Outdated

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
### Prerendering Dynamic Routes
### Pre-rendering Dynamic Routes

Comment thread aio/content/guide/universal.md Outdated

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.

Comment thread aio/content/guide/universal.md Outdated

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
#### Providing all routes via file
#### Providing all routes in a file

Comment thread aio/content/guide/universal.md Outdated

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.

Comment thread aio/content/guide/universal.md Outdated

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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:

Comment thread aio/content/guide/universal.md Outdated

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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:

@santoshyadavdev santoshyadavdev force-pushed the feature/update-SSR-docs branch from f597fed to 5f5eb70 Compare May 12, 2020 21:42

@gkalpak gkalpak left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thx for making the changes, @santoshyadavdev 🏅
I have left a few more (mostly minor) comments/suggestions. PTAL

Comment thread aio/content/guide/universal.md Outdated
Comment thread aio/content/guide/universal.md Outdated
Comment thread aio/content/guide/prerendering.md Outdated
Comment thread aio/content/guide/prerendering.md Outdated
Comment thread aio/content/guide/prerendering.md Outdated
Comment thread aio/content/guide/prerendering.md Outdated
Comment thread aio/content/guide/prerendering.md Outdated
Comment thread aio/content/guide/prerendering.md Outdated
Comment thread aio/content/guide/prerendering.md Outdated
Comment thread aio/content/guide/prerendering.md Outdated
Comment thread aio/content/guide/prerendering.md Outdated

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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. Prerendering is processing your page as a static page at build time.

Suggested for clarity.

Comment thread aio/content/guide/prerendering.md Outdated

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* `serverTarget`: Specify the Server target to use for prerenering the application.
* `serverTarget`: Specify the Server target to use for prerendering the application.

Fixed spello

Comment thread aio/content/guide/prerendering.md Outdated

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* `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.

Comment thread aio/content/guide/prerendering.md Outdated

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
## Command to Prerender a static page
## Command to prerender a static page

Per style guide: Use sentence case for headings and titles.

Comment thread aio/content/guide/prerendering.md Outdated

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# Prerendering Static Pages
# Prerendering static pages

Developer documentation style guide says: Use sentence case for headings and titles.

Comment thread aio/content/guide/prerendering.md Outdated

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
#### Provide additional routes in the command-line
#### Provide additional routes in the command line

Not hyphenated when used as a noun.

Comment thread aio/content/guide/prerendering.md Outdated

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should newlines be one or two words?

Comment thread aio/content/guide/prerendering.md Outdated

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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?

Comment thread aio/content/guide/prerendering.md Outdated

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 ecommerce application, which may come from an external source (Database or CMS).

Comment thread aio/content/guide/universal.md Outdated

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 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.

@TeriGlover

TeriGlover commented May 25, 2021 via email

Copy link
Copy Markdown
Contributor

@santoshyadavdev santoshyadavdev force-pushed the feature/update-SSR-docs branch from f5f0fbd to a6756aa Compare May 30, 2021 08:56
@santoshyadavdev

Copy link
Copy Markdown
Contributor Author

Done @gkalpak @TeriGlover, there are was some similar comment from both of you, just kept one from George 😁.

@mary-poppins

Copy link
Copy Markdown

You can preview a6756aa at https://pr36005-a6756aa.ngbuilds.io/.

@gkalpak gkalpak left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hopefully, the last round of comments ✨

Comment thread aio/content/guide/prerendering.md Outdated
Comment thread aio/content/guide/prerendering.md Outdated
Comment thread aio/content/guide/prerendering.md Outdated
Comment thread aio/content/guide/universal.md Outdated
Comment thread aio/content/guide/universal.md Outdated
Comment thread aio/content/guide/universal.md Outdated
@santoshyadavdev santoshyadavdev force-pushed the feature/update-SSR-docs branch from a6756aa to 8e3217b Compare May 30, 2021 19:48
@mary-poppins

Copy link
Copy Markdown

You can preview 8e3217b at https://pr36005-8e3217b.ngbuilds.io/.

@google-cla

This comment has been minimized.

@google-cla google-cla Bot added cla: no and removed cla: yes labels May 31, 2021
@gkalpak

This comment has been minimized.

@google-cla google-cla Bot added cla: yes and removed cla: no labels May 31, 2021
@gkalpak gkalpak removed the request for review from kyliau May 31, 2021 10:24
@gkalpak

gkalpak commented May 31, 2021

Copy link
Copy Markdown
Member

FYI, I've pushed a fixup commit with some final fixes. It is good to go as far as I'm concerned :shipit:
Thx for the amazing work, @santoshyadavdev ❤️

@mary-poppins

Copy link
Copy Markdown

You can preview 050abce at https://pr36005-050abce.ngbuilds.io/.

@AndrewKushnir AndrewKushnir left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM 👍 Approving for code-ownership group.

@AndrewKushnir AndrewKushnir removed the request for review from alxhub June 8, 2021 19:28
@AndrewKushnir AndrewKushnir added action: merge The PR is ready for merge by the caretaker and removed state: WIP feature Label used to distinguish feature request from other issues labels Jun 8, 2021
jessicajaniuk pushed a commit that referenced this pull request Jun 8, 2021
@angular-automatic-lock-bot

Copy link
Copy Markdown

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

This action has been performed automatically by a bot.

@angular-automatic-lock-bot angular-automatic-lock-bot Bot locked and limited conversation to collaborators Jul 9, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

action: merge The PR is ready for merge by the caretaker area: server Issues related to server-side rendering cla: yes effort3: weeks risk: low state: needs doc team review target: patch This PR is targeted for the next patch release

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Update Universal doc to include prerender and live reload functionality

10 participants