Skip to content

Commit

Permalink
Merge pull request #139 from angular/main
Browse files Browse the repository at this point in the history 
Create a new pull request by comparing changes across two branches
  • Loading branch information
@GulajavaMinistudio
GulajavaMinistudio authored Oct 24, 2023
2 parents afd5054 + 47ab069 commit 175de93
Show file tree
Hide file tree
Showing 83 changed files with 3,606 additions and 1,911 deletions.
2 changes: 1 addition & 1 deletion aio/content/cli/help/build-info.json
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
{
"branchName": "refs/heads/main",
"sha": "81c55a67fc38f47d14387584cf9593286ddd18c1"
"sha": "47810588dd3e0458285fe60a9f530021c8a915a3"
}
4 changes: 2 additions & 2 deletions aio/content/cli/help/build.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
"command": "ng build [project]",
"shortDescription": "Compiles an Angular application or library into an output directory named dist/ at the given output path.",
"longDescriptionRelativePath": "@angular/cli/src/commands/build/long-description.md",
"longDescription": "The command can be used to build a project of type \"application\" or \"library\".\nWhen used to build a library, a different builder is invoked, and only the `ts-config`, `configuration`, and `watch` options are applied.\nAll other options apply only to building applications.\n\nThe application builder uses the [webpack](https://webpack.js.org/) build tool, with default configuration options specified in the workspace configuration file (`angular.json`) or with a named alternative configuration.\nA \"development\" configuration is created by default when you use the CLI to create the project, and you can use that configuration by specifying the `--configuration development`.\n\nThe configuration options generally correspond to the command options.\nYou can override individual configuration defaults by specifying the corresponding options on the command line.\nThe command can accept option names given in dash-case.\nNote that in the configuration file, you must specify names in camelCase.\n\nSome additional options can only be set through the configuration file,\neither by direct editing or with the `ng config` command.\nThese include `assets`, `styles`, and `scripts` objects that provide runtime-global resources to include in the project.\nResources in CSS, such as images and fonts, are automatically written and fingerprinted at the root of the output folder.\n\nFor further details, see [Workspace Configuration](guide/workspace-config).\n",
"longDescription": "The command can be used to build a project of type \"application\" or \"library\".\nWhen used to build a library, a different builder is invoked, and only the `ts-config`, `configuration`, and `watch` options are applied.\nAll other options apply only to building applications.\n\nThe application builder uses the [esbuild](https://esbuild.github.io/) build tool, with default configuration options specified in the workspace configuration file (`angular.json`) or with a named alternative configuration.\nA \"development\" configuration is created by default when you use the CLI to create the project, and you can use that configuration by specifying the `--configuration development`.\n\nThe configuration options generally correspond to the command options.\nYou can override individual configuration defaults by specifying the corresponding options on the command line.\nThe command can accept option names given in dash-case.\nNote that in the configuration file, you must specify names in camelCase.\n\nSome additional options can only be set through the configuration file,\neither by direct editing or with the `ng config` command.\nThese include `assets`, `styles`, and `scripts` objects that provide runtime-global resources to include in the project.\nResources in CSS, such as images and fonts, are automatically written and fingerprinted at the root of the output folder.\n\nFor further details, see [Workspace Configuration](guide/workspace-config).\n",
"aliases": [
"b"
],
Expand All @@ -12,7 +12,7 @@
{
"name": "allowed-common-js-dependencies",
"type": "array",
"description": "A list of CommonJS packages that are allowed to be used without a build time warning."
"description": "A list of CommonJS or AMD packages that are allowed to be used without a build time warning. Use `'*'` to allow all."
},
{
"name": "aot",
Expand Down
6 changes: 3 additions & 3 deletions aio/content/cli/help/update.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@
{
"name": "from",
"type": "string",
"description": "Version from which to migrate from. Only available with a single package being updated, and only with 'migrate-only'."
"description": "Version from which to migrate from. Only available when a single package is updated, and only with 'migrate-only'."
},
{
"name": "help",
Expand All @@ -46,7 +46,7 @@
{
"name": "name",
"type": "string",
"description": "The name of the migration to run. Only available with a single package being updated, and only with 'migrate-only' option."
"description": "The name of the migration to run. Only available when a single package is updated."
},
{
"name": "next",
Expand All @@ -71,7 +71,7 @@
{
"name": "to",
"type": "string",
"description": "Version up to which to apply migrations. Only available with a single package being updated, and only with 'migrate-only' option. Requires 'from' to be specified. Default to the installed version detected."
"description": "Version up to which to apply migrations. Only available when a single package is updated, and only with 'migrate-only' option. Requires 'from' to be specified. Default to the installed version detected."
},
{
"name": "verbose",
Expand Down
74 changes: 20 additions & 54 deletions aio/content/guide/app-shell.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,17 +7,17 @@ This gives users a meaningful first paint of your application that appears quick

Learn more in [The App Shell Model](https://developers.google.com/web/fundamentals/architecture/app-shell).

## Step 1: Prepare the application
## Step 1: Generate an application

Do this with the following Angular CLI command:

<code-example format="shell" language="shell">

ng new my-app --routing
ng new my-app

</code-example>

For an existing application, you have to manually add the `RouterModule` and defining a `<router-outlet>` within your application.
For an existing application, you have to manually add the `Router` and defining a `<router-outlet>` within your application.

## Step 2: Create the application shell

Expand All @@ -31,70 +31,36 @@ ng generate app-shell

For more information about this command, see [App shell command](cli/generate#app-shell-command).

After running this command you can see that the `angular.json` configuration file has been updated to add two new targets, with a few other changes.

<code-example language="json">

"server": {
"builder": "&commat;angular-devkit/build-angular:server",
"defaultConfiguration": "production",
"options": {
"outputPath": "dist/my-app/server",
"main": "src/main.server.ts",
"tsConfig": "tsconfig.server.json"
},
"configurations": {
"development": {
"outputHashing": "none",
},
"production": {
"outputHashing": "media",
"fileReplacements": [
{
"replace": "src/environments/environment.ts",
"with": "src/environments/environment.prod.ts"
}
],
"sourceMap": false,
"optimization": true
}
}
},
"app-shell": {
"builder": "&commat;angular-devkit/build-angular:app-shell",
"defaultConfiguration": "production",
"options": {
"route": "shell"
},
"configurations": {
"development": {
"browserTarget": "my-app:build:development",
"serverTarget": "my-app:server:development",
},
"production": {
"browserTarget": "my-app:build:production",
"serverTarget": "my-app:server:production"
}
}
}
The command updates the application code and adds extra files to the project structure.

<code-example language="text">

src
├── app
│ ├── app.config.server.ts # server application configuration
│ └── app-shell # app-shell component
│ ├── app-shell.component.html
│ ├── app-shell.component.scss
│ ├── app-shell.component.spec.ts
│ └── app-shell.component.ts
└── main.server.ts # main server application bootstrapping

</code-example>

## Step 3: Verify the application is built with the shell content

Use the Angular CLI to build the `app-shell` target.
## Step 3: Verify the application is built with the shell content

<code-example format="shell" language="shell">

ng run my-app:app-shell:development
ng build --configuration=development

</code-example>

Or to use the production configuration.

<code-example format="shell" language="shell">

ng run my-app:app-shell:production
ng build

</code-example>

Expand All @@ -107,4 +73,4 @@ Look for default text `app-shell works!` to show that the application shell rout

<!-- end links -->

@reviewed 2022-02-28
@reviewed 2023-10-20
100 changes: 51 additions & 49 deletions aio/content/guide/prerendering.md
View file
Original file line number Diff line number Diff line change
@@ -1,63 +1,65 @@
# Prerendering static pages
# Prerendering (SSG)

Angular Universal lets you prerender the pages of your application.
Prerendering is the process where a dynamic page is processed at build time generating static HTML.
Prerendering, commonly referred to as Static Site Generation (SSG), represents the method by which pages are rendered to static HTML files during the build process.

ndering maintains the same performance benefits of [server-side rendering (SSR)](/guide/universal/#why-do-it). But achieves a reduced Time to First Byte (TTFB), ultimately enhancing user experience. The key distinction lies in its approach that pages are served as static content, and there is no request-based rendering.

When the data necessary for server-side rendering remains consistent across all users, the strategy of prerendering emerges as a valuable alternative. Rather than dynamically rendering pages for each user request, prerendering takes a proactive approach by rendering them in advance.

## How to prerender a page

To prerender a static page make sure to add Server-Side Rendering (SSR) capabilities to your application.
For more information see the [universal guide](guide/universal).
Once SSR is added, run the following command:
To prerender a static page, add SSR capabilities to your application with the following Angular CLI command:

<code-example format="shell" language="shell">

npm run prerender
ng add &commat;angular/ssr

</code-example>

### Build options for prerendering
<div class="alert is-helpful">

When you add prerendering to your application, the following build options are available:
To create an application with prerendering capabilities from the beginning use the [ng new --ssr](cli/new) command.

| Options | Details |
|:--- |:--- |
| `browserTarget` | Specify the target to build. |
| `serverTarget` | Specify the Server target to use for prerendering the application. |
| `routes` | Define an array of extra 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. |
</div>

### Prerendering dynamic routes
Once SSR is added, you can generate the static pages by running the build command:

You can prerender dynamic routes.
An example of a dynamic route is `product/:id`, where `id` is dynamically provided.
<code-example format="shell" language="shell">

To prerender dynamic routes, choose one from the following options:
ng build

* Provide extra routes in the command line
* Provide routes using a file
* Prerender specific routes
</code-example>

#### Provide extra routes in the command line
### Build options for prerender

While running the prerender command, you can provide extra routes.
For example:
The application builder `prerender` option can be either a Boolean or an Object for more fine-tuned configuration.
When the option is `false`, no prerendering is done. When it's is `true`, all options use the default value. When it's is an Object, each option can be individually configured.

<code-example format="shell" language="shell">
| Options | Details | Default Value |
| :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------ |
| `discoverRoutes` | Whether the builder should process the Angular Router configuration to find all unparameterized routes and prerender them. | `true` |
| `routesFile` | The path to a file that contains a list of all routes to prerender, separated by newlines. This option is useful if you want to prerender routes with parameterized URLs. | |

ng run &lt;app-name&gt;:prerender --routes /product/1 /product/2
<code-example format="json" language="json">

</code-example>
&hellip;
"architect": {
"build": {
"builder": "&commat;angular-devkit/build-angular:application",
"options": {
"prerender": {
"discoverRoutes": false
},
},
&hellip;

#### Providing extra routes using a file
</code-example>

You can provide routes using a file to create static pages.
This method is useful if you have a large number of routes to create. For example, product details for an e-commerce application, which might come from an external source, like a Database or Content Management System (CMS).
### Prerendering parameterized routes

To provide routes using a file, use the `--routes-file` option with the name of a `.txt` file containing the routes.
You can prerender parameterized routes using the `routesFile` option. An example of a parameterized route is `product/:id`, where `id` is dynamically provided. To specify these routes, they should be listed in a text file, with each route on a separate line.

For example, you could create this file by using a script to extract IDs from a database and save them to a `routes.txt` file:
For an app with a large number of parameterized routes, consider generating this file using a script before running `ng build`.

<code-example language="none" header="routes.txt">

Expand All @@ -66,29 +68,29 @@ For example, you could create this file by using a script to extract IDs from a

</code-example>

When your `.txt` file is ready, run the following command to prerender the static files with dynamic values:
With routes specified in the `routes.txt` file, use the `routesFile` option to configure the builder to prerender the product routes.

<code-example format="shell" language="shell">
<code-example format="json" language="json">

ng run &lt;app-name&gt;:prerender --routes-file routes.txt
&hellip;
"architect": {
"build": {
"builder": "&commat;angular-devkit/build-angular:application",
"options": {
"prerender": {
"routesFile": "routes.txt"
},
},
&hellip;

</code-example>

#### Prerendering specific routes

You can also pass specific routes to the prerender command.
If you choose this option, make sure to turn off the `guessRoutes` option.

<code-example format="shell" language="shell">

ng run &lt;app-name&gt;:prerender --no-guess-routes --routes /product/1 /product/2

</code-example>
This configures `ng build` to prerender `/products/1` and `/products/555` at build time.

<!-- links -->

<!-- external links -->

<!-- end links -->

@reviewed 2022-02-28
@reviewed 2023-10-23
8 changes: 4 additions & 4 deletions aio/src/app/app.component.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,11 @@
<header>
<mat-toolbar #appToolbar color="primary" class="app-toolbar no-print" [class.transitioning]="isTransitioning">
<mat-toolbar-row class="notification-container">
<aio-notification notificationId="survey-august-2023" expirationDate="2023-10-08" [dismissOnContentClick]="true" (dismissed)="notificationDismissed()">
<a href="https://goo.gle/angular-devsat-q3-2023">
<aio-notification notificationId="angular-event" expirationDate="2023-11-08" [dismissOnContentClick]="true" (dismissed)="notificationDismissed()">
<a href="https://goo.gle/angular-event">
<mat-icon class="icon" svgIcon="insert_comment" aria-label="Announcement"></mat-icon>
<span class="message">Help Angular by taking a <strong>quick survey</strong>!</span>
<span class="action-button">Go to survey</span>
<span class="message">We have a lot to share, tune in on November 6th!</span>
<span class="action-button">Join us live</span>
</a>
</aio-notification>
</mat-toolbar-row>
Expand Down
Loading

0 comments on commit 175de93

Please sign in to comment.