diff --git a/docs/en/framework/ui/angular/pwa-configuration.md b/docs/en/framework/ui/angular/pwa-configuration.md index 4c10fb6d27..23935bbdcf 100644 --- a/docs/en/framework/ui/angular/pwa-configuration.md +++ b/docs/en/framework/ui/angular/pwa-configuration.md @@ -11,24 +11,26 @@ Converting your Angular application to a PWA is easy. +> If you created your solution with the **Progressive Web Application** option (in ABP Studio, or with the `-pwa` parameter of the `abp new` command), step 1 has already been done for you. Check the `assets` configuration described at the end of step 1, then continue from [step 2](#2-update-the-web-app-manifest). + ## 1. Install Angular PWA -Run the following command in the root folder of your Angular application: +Run the following command in the root folder of your Angular application. Use the `@angular/pwa` version whose major version matches the `@angular/cli` version in your `package.json` (for example, `@angular/pwa@22` for Angular 22): ```shell -yarn ng add @angular/pwa +yarn ng add @angular/pwa@ ``` ...or... ```shell -npm run ng add @angular/pwa +npx ng add @angular/pwa@ ``` This will install the `@angular/service-worker` package and make your default app a PWA. Alternatively, you may add `project` parameter to target a specific app in your workspace: ```shell -yarn ng add @angular/pwa --project MyProjectName +yarn ng add @angular/pwa@ --project MyProjectName ``` Here is the output of the command: @@ -38,17 +40,24 @@ Here is the output of the command: So, Angular CLI updates some files and add a few others: - **ngsw-config.json** is where the [service worker configuration](https://angular.dev/ecosystem/service-workers/config) is placed. Not all PWAs have this file. It is specific to Angular. -- **manifest.webmanifest** is a [web app manifest](https://developer.mozilla.org/en-US/docs/Web/Manifest) and provides information about your app in JSON format. -- **icons** are placeholder icons that are referred to in your web app manifest. We will replace these in a minute. -- **angular.json** has following modifications: - - `assets` include _manifest.webmanifest_. - - `serviceWorker` is `true` in production build. - - `ngswConfigPath` refers to _ngsw-config.json_. +- **public/manifest.webmanifest** is a [web app manifest](https://developer.mozilla.org/en-US/docs/Web/Manifest) and provides information about your app in JSON format. +- **public/icons** are placeholder icons that are referred to in your web app manifest. We will replace these in a minute. +- **angular.json** has the `serviceWorker` option set to _ngsw-config.json_ in the production configuration. - **package.json** has _@angular/service-worker_ as a new dependency. -- **app.config.ts** The `provideServiceWorker` provider is imported to register the service worker script. -- **index.html** has following modifications: - - A `` element that refers to _manifest.webmanifest_. - - A `` tag that sets a theme color. +- **main.ts** (or **app.config.ts**) registers the service worker script with the `provideServiceWorker` provider. In the ABP startup templates, `main.ts` passes the application configuration to `bootstrapApplication` directly, so the provider is added to `main.ts`. +- **index.html** has a `` element that refers to _manifest.webmanifest_. + +The manifest and the icons are placed in the `public` folder. Make sure this folder is copied to the build output. If the `assets` array of your application in `angular.json` does not include it, add it: + +```json +"assets": [ + "src/favicon.ico", + "src/assets", + { "glob": "**/*", "input": "public" } +] +``` + +Otherwise, the browser cannot find the manifest and the icons, and the application cannot be installed. ## 2. Update the Web App Manifest @@ -97,7 +106,7 @@ Open the _manifest.webmanifest_ file and update `theme_color` and `background_co } ``` -Then open _index.html_ and change the theme color meta tag as below: +Then open _index.html_ and add (or update) the theme color meta tag as below: ```html @@ -119,7 +128,7 @@ First, open the _manifest.webmanifest_ file and remove all elements in the `icon Then, run the following command in your terminal (changing the path of course): ```shell -npx pwa-asset-generator /path/to/your/logo.png ./src/assets/pwa -i ./src/index.html -m ./src/manifest.webmanifest +npx pwa-asset-generator /path/to/your/logo.png ./public/pwa -i ./src/index.html -m ./public/manifest.webmanifest ``` Open the _manifest.webmanifest_ file again. You will see this: @@ -150,134 +159,134 @@ In addition to updated icons, the library will generate splash screens. However, ``` diff --git a/framework/src/Volo.Abp.Cli.Core/Volo/Abp/Cli/ProjectModification/AngularPwaSupportAdder.cs b/framework/src/Volo.Abp.Cli.Core/Volo/Abp/Cli/ProjectModification/AngularPwaSupportAdder.cs index 86880aaacf..8c0ae98385 100644 --- a/framework/src/Volo.Abp.Cli.Core/Volo/Abp/Cli/ProjectModification/AngularPwaSupportAdder.cs +++ b/framework/src/Volo.Abp.Cli.Core/Volo/Abp/Cli/ProjectModification/AngularPwaSupportAdder.cs @@ -1,6 +1,8 @@ using System; using System.IO; using System.Linq; +using System.Text.RegularExpressions; +using Newtonsoft.Json.Linq; using Volo.Abp.Cli.Utils; using Volo.Abp.DependencyInjection; @@ -29,7 +31,37 @@ public class AngularPwaSupportAdder : ITransientDependency protected virtual void AddPwaSupportToProject(string filePath) { var directory = Path.GetDirectoryName(filePath).EnsureEndsWith(Path.DirectorySeparatorChar); + var pwaMajorVersion = GetAngularCliMajorVersion(filePath); - CmdHelper.RunCmd("ng add @angular/pwa@13 --skip-confirmation", workingDirectory: directory); + CmdHelper.RunCmd( + $"ng add @angular/pwa@{pwaMajorVersion} --skip-confirmation", + out var exitCode, + workingDirectory: directory + ); + + if (exitCode != 0) + { + throw new AbpException( + $"Failed to add Angular PWA support to '{filePath}'. 'ng add @angular/pwa@{pwaMajorVersion}' exited with code {exitCode}." + ); + } + } + + protected virtual string GetAngularCliMajorVersion(string packageJsonFilePath) + { + var packageJson = JObject.Parse(File.ReadAllText(packageJsonFilePath)); + + var cliVersion = + (packageJson["devDependencies"]?["@angular/cli"] ?? packageJson["dependencies"]?["@angular/cli"])?.ToString(); + + var match = cliVersion == null ? null : Regex.Match(cliVersion, @"\d+"); + if (match == null || !match.Success) + { + throw new AbpException( + $"Could not determine the @angular/cli version from '{packageJsonFilePath}', so the matching @angular/pwa version cannot be selected." + ); + } + + return match.Value; } }