ngx-prefetch - Load your Angular application faster.
Angular builder for prefetching resources before loading the application.
Description
In some cases, it is possible to prefetch the resources of an application before actually loading the application itself. For example, if the application can be accessed through a static web page or another web application.
The prefetch builder generates a ngxPrefetch.js
file that should be included in the HTML page of the entry point. When run, it dynamically creates <link>
tags for each resource (such as JS and CSS files) so that the browser can prefetch them during idle times. This will improve the Page Load Time of the application when it is accessed for the first time. Then, the browser caching will take over until a new version of the application is deployed or the browser cache is cleared.
Prerequisites
A prerequisite for the script is to have Angular Service Worker enabled as it is using the ngsw.json
from the production build folder that is generated by the Angular Service Worker. Therefore, it will be run after the build prod.
Install
npm install -D @o3r/ngx-prefetch
OR
ng add @o3r/ngx-prefetch
NOTE: This library is following the Angular release cycle. For instance, if you are using Angular 13, use a 13.x version of the library:
npm install -D @o3r/ngx-prefetch@13
OR
ng add @o3r/ngx-prefetch@13
Get started
- By running the
ng add
command above, the following lines should have been added to the application's angular.json
:
"generate-prefetch": {
"builder": "@o3r/ngx-prefetch:run",
"options": {
"targetBuild": "app-name:build:production"
}
},
NOTE: Additional configuration can be added to the angular.json
(builder options are described below with an example of full configuration).
- Then, add a command to the
package.json
to run generate-prefetch
:
"generate:prefetch": "ng run app-name:generate-prefetch"
- Run the
ng build
command with the production
configuration.
The default configuration of the build command should be production
, otherwise it should be specified:
...
"build:prod": "ng build --configuration production",
...
- Run the previously defined
generate:prefetch
command.
How it works
Please refer to the details on how the ngx-prefetch works here.
Builder options
-
targetBuild
Mandatory The target build where prefetch should be applied. Used for identifying the outputPath
of the build.
-
resourceTypes
An object describing the resource types that should be prefetched. The valid values for the type of content can be found here.
-
crossorigin
Flag that sets the crossorigin attribute on links. If true it will be set for all prefetched resources.
-
production
Flag for creating a production (minified) version of the js file or a development one.
-
staticsFullPath
By default the prefetched resources are hosted next to the ngxPrefetch.js
file, on the same server.
If this is not the case, you can configure the full path of the resources that will be prefetched (ex: https://my-web-app.com/path/to/my-app/).
It is also possible to set this value at runtime. Instead of setting it in the Builder's options, you can search for {STATICS_FULL_PATH}
and replace it on the server side in order to inject a path.
-
localizationPattern
Pattern for the relative path of the localization file. By default, the pattern corresponds to the JSON file in a folder called localizations: "localizations/${language}.json"
.
If the localization pattern contains the ${language}
variable, the language value must be set (as explained here), and it will be replaced by the server.
-
fallbackLocalesMap
Mapping of fallback locales (only available if there is dynamic content in the application), in case the localization file of the input language cannot be found.
First, a search for an exact match of the input language will be done in the fallbackLocalesMap
. If not found and the input language parameter is of type locale,
a search for the shortened version of the locale (for example, search for en
if the input language is en-GB
) will be done. If this is not found either, a search
for the default locale *
will be searched for. If none of these are found within the dynamic content files, the localization file will not be prefetched.
You can find a detailed example below.
-
outputPath
Path to the folder of ngsw.json
in the production build output. If not defined, will try to compute it from the executor options.
Example of full configuration
[angular.json
: full configuration]
"generate-prefetch": {
"builder": "@o3r/ngx-prefetch:run",
"options": {
"targetBuild": "my-app:build:production",
"resourceTypes": {
"image": ["png", "jpg", "gif"],
"font": ["eot", "ttf", "woff", "woff2", "svg"],
"style": ["css"],
"script": ["js"],
"document": ["html"]
},
"crossorigin": true,
"production": false,
"staticsFullPath": "https://my-web-app.com/path/to/my-app/",
"localizationPattern": "localizations/${language}.json",
"outputPath": "dist",
"fallbackLocalesMap": {
"fr-CA": "fr-FR",
"de": "de-DE",
"*": "en-GB"
}
}
}
Example of fallback locale
Let's assume you have the fallbackLocalesMap
above in your configuration and three localization files in your assets: fr-FR.json
, de-DE.json
, and en-GB.json
.
If your language parameter is equal to:
fr-FR
: you will prefetch this file directlyfr-CA
: you will fallback to fr-FR
de-AT
: you will fallback to de-DE
it-IT
: you will fallback to en-GB
(the default fallback locale)