ngx-lazy-script v0.0.2

ngx-lazy-script

Because I'm tired of copying this stuff between projects. https://www.npmjs.com/package/ngx-lazy-script

About

ngx-lazy-script gives you some programmatic control over manual script loading.

Sometimes it's helpful to load scripts manually. It can help reduce bundle size and unnecessary network requests. Not all projects are set up for Angular Router's lazy loading and even then, you may want to load a script "lazier" than that.

For example, if a user wants to make a payment and you use Stripe.js to process it, you can use ngx-lazy-script to easily load it once the user accesses your payment component.

This is meant for lazy loading non-Angular scripts.

Getting Started

1. Install via npm or yarn

npm i -S ngx-lazy-script
//------------- OR --------------
yarn add ngx-lazy-script

2. Import NgxLazyScriptModule in your application

import { NgxLazyScriptModule } from 'ngx-lazy-script';
@NgModule({
  ...
  imports: [NgxLazyScriptModule],
  ...
})
export class AppModule { }

Usage

Use the ngx-lazy-script component or NgxLazyScriptService to lazy load scripts. Both achieve a similar result.

The ngx-lazy-script component:

<ngx-lazy-script url="https://js.stripe.com/v3/" globalObject="stripe" (status)="onScriptStatus($event)"></ngx-lazy-script>

This will load Stripe.js when the parent (containing) component is attached to the view. It won't make duplicate requests, so it's safe to place the above in multiple places (or in different routes, etc.)

You should listen to the status event and react accordingly in your component. The status event will be emitted whenever the script load status changes:

onScriptStatus({ loading, loaded, error }: LazyScriptStatus) {
  if (loading) {
    // Script is loading
  } else if (error) {
    // Script failed to load
  } else if (loaded) {
    // Script loaded, do what you need to now
  }
}

If you want to lazy load based on some custom trigger, use ViewChild:

<ngx-lazy-script
  url="https://js.stripe.com/v3/"
  globalObject="stripe"
  (status)="onScriptStatus($event)"
  [manual]="true"
  #stripeScript
></ngx-lazy-script>

<!-- E.g. this button loads the above script -->
<button (click)="stripeScript.loadScript()">Load Stripe</button>

The ngx-lazy-script component has a few other options:

scriptAttributes allow you to customize the script element inserted into the DOM. By default, the script will be loaded with:

{ async: true, defer: true, type: 'text/javascript' }

This module also exposes a NgxLazyScriptService service (injected in root). This gives similar functionality as above without using the ngx-lazy-script component. Just inject the service and use like this:

const url = 'https://js.stripe.com/v3/';
const globalObject = 'stripe';
const scriptAttributes = {}; // Just use the defaults
this.ngxLazyScriptService.load(url, globalObject, scriptAttributes).subscribe(status => {
  console.log(status);
});

Local Development

If you wish to contribute to this repository, below are the steps for local development.

1. Clone the repository git clone https://github.com/cf91/ngx-lazy-script.git
2. Run npm install to install the dependencies
3. Run npm build to build both the library and demo app and create a link
4. Run npm start to build and watch the demo app (opens the app at http://localhost:4200/ automatically)
5. Run npm watch:lib to build and watch the library

Build

Run npm run build to build the library and demo app together. The build artifacts will be stored in the dist/ directory.

This step is used by CircleCI to build both library and demo app. After a succesful build, a new semantic version of library is published to npm.

Tests

Run npm run test:lib or npm run test:app to execute the unit tests via Karma.