Have you ever wanted to customize which features of the New Relic browser agent you ship to your customers? Maybe you need to support different or older browsers than the browser agent does in its browser support matrix? Since the browser agent is open source, you have the option to fork the repository, modify the code, and build your own custom browser agent. But this process comes with the extra overhead of managing a forked repository: learning the code, building the system, testing tools, etc. Top it off with keeping up to date with the changes being made to the main browser agent repository and this task of managing a fork can be overwhelming.

The browser agent has a solution for this: an npm package that you can use instead. The npm package allows you to import the browser agent in your client-side application, pick which features to deploy, and include the agent in the same JavaScript build process you already use. In this blog post, you’ll learn how to do all of the above with examples, and where you can go to learn more.  

Why should you check out the npm package? It can open the door to easy customization in these use cases:

  • Shipping a subset of the included features of the browser agent.
  • Supporting browsers that the browser agent does not natively support.
  • Controlling which version of the browser agent is used in your application and when the version changes.
  • Injecting different browser agent configurations into the HTML for different instances of your app (multiple environments or customers).
  • Eliminating the total cost of ownership that comes with maintaining a forked repository of the open source browser agent.

Create a browser app and get its configuration values

To get started, you will need to create a new browser app in New Relic or locate an existing browser app that you would like to use with the npm package. This may be done with or without a corresponding APM agent. To create an app, follow these instructions:

  1. Open New Relic, and select Add Data from the navigation panel.
  2. Select Browser & mobile, then select the Browser monitoring data source.
  3. Choose your deployment method, either APM or Copy/Paste.
  4. Select an existing app monitored in APM, or name your new app and click Enable.

Next, you’ll need to get configuration values for your browser app in order to define options when instantiating the agent via the npm package:

  1. From the navigation panel in New Relic, select Browser to view your browser apps.
  2. Select the desired app and navigate to the Application settings page.
  3. From the Copy/Paste JavaScript box, copy the configuration values assigned to the NREUM object: init, info, and loader_config. You will use these configuration values when instantiating the agent using the npm package.

Set up instrumentation with the npm package

To make the agent available to your application, install via NPM or Yarn.

$ npm install @newrelic/browser-agent --save
$ yarn add @newrelic/browser-agent

For best results, it is important that the browser agent loads as early as possible on the page. Since the browser agent is going to be bundled into your browser application, you need to pick a location that ensures it runs early, preferably first. Most browser applications will have a JavaScript or Typescript file that is referred to as the entry point. This is the first file that is executed when your site loads and is the best location to instantiate the browser agent.

Modify your browser application’s entry point source file so it looks similar to the next example.

import { BrowserAgent } from '@newrelic/browser-agent/loaders/browser-agent'
// The rest of your client-side application imports

// Populate using values in copy-paste JavaScript snippet.
const options = {
  init: { ... }, // NREUM.init
  info: { ... }, // NREUM.info
  loader_config: { ... } // NREUM.loader_config

// The agent loader code executes immediately on instantiation.
new BrowserAgent(options)
// The rest of your client-side application code

Update the options object with the values from the NREUM object in New Relic: the values for init, info, and loader_config. Build and deploy your browser application to apply the changes. Now you have the same full and automatic instrumentation of your site that you would get with Copy/Paste and APM injection methods.

Customize your instrumentation

The BrowserAgent class is a utility class that includes all the available features of the browser agent. The npm package also contains an Agent class that allows you to pass in an array of features that you would like to include. This allows you to customize what is being instrumented and reported to New Relic for your site.

Check out the next code snippet. This example includes all the current features that can be enabled for the browser agent. But you can pick and choose which ones you want to import and include in the features array.

import { Agent } from '@newrelic/browser-agent/loaders/agent'
import { Ajax } from '@newrelic/browser-agent/features/ajax';
import { JSErrors } from '@newrelic/browser-agent/features/jserrors';
import { Metrics } from '@newrelic/browser-agent/features/metrics';
import { PageAction } from '@newrelic/browser-agent/features/page_action';
import { PageViewEvent } from '@newrelic/browser-agent/features/page_view_event';
import { PageViewTiming } from '@newrelic/browser-agent/features/page_view_timing';
import { SessionTrace } from '@newrelic/browser-agent/features/session_trace';
import { Spa } from '@newrelic/browser-agent/features/spa';
// The rest of your client-side application imports

// Populate using values in copy-paste JavaScript snippet.
const options = {
  init: { ... }, // NREUM.init
  info: { ... }, // NREUM.info
  loader_config: { ... }, // NREUM.loader_config
  features: [

// The agent loader code executes immediately on instantiation.
new Agent(options)
// The rest of your browser application code

JavaScript toolchain support

Client-side build tools vary, but many of these tools offer useful features for integrating and customizing the browser agent npm package. For example, webpack can be configured to apply transformations to the browser agent npm package to provide support for browsers not in our browser support matrix. Check out the next code snippet for an example.

  ... // Other webpack config settings
  rules: [{
    test: /\.(js|jsx)$/i,
    exclude: /node_modules\/(?!@newrelic\/browser-agent).*/,
    use: 'babel-loader'
  ... // Other webpack config settings

In this webpack configuration, the exclude property of the babel rule has been updated so the browser agent npm package is also transformed by babel. Similar support for transforming npm package code is available in many other JavaScript build tools.

Video demo: Adding the customizable browser agent to a React app

Watch the next video from Johnathan Potter for a walkthrough of the process you just learned about. In this example, you’ll add the newrelic-browser-agent package to a React app.