Your data. Anywhere you go.

New Relic for iOS or Android

Download on the App Store    Android App on Google play

New Relic Insights App for iOS

Download on the App Store

Learn more

Close icon

Workshop - Build Your First Nerdpack



Workshop - Building Your First Nerdpack

There are a series of Labs that will be particularly helpful as you get started with building Nerdpacks. The purpose of these labs is to provide hands on experience building on top of the New Relic One platform. In GitHub, this step is known as Lab0.

Key Concepts

Here are three Nerdpack vocabulary words defined. You are going to want to know these as you move forward in Lab0:

  • Launcher : An entry point into the New Relic One platform that is loaded on the “Home” page.
  • Nerdlet : A visual component that renders inside the New Relic One platform at a well defined extension point. For example, a Launcher can invoke a Nerdlet (as you will see shortly). At their core, Nerdlets are React.js components.
  • Nerdpack (aka Package): A collection of artifacts, e.g. Nerdlets, that are “packaged” up and published into the New Relic One platform.

In Lab0, you will create a Launcher and then add a Nerdlet to it that will be invoked when the user clicks on the Launcher. After this lab you should understand:

  • How to use the CLI to create a Launcher
  • How to use the CLI to create a Nerdlet
  • How to connect a Launcher to a Nerdlet
  • How to create and locally develop an Nerdpack


Link to Setup GitHub Repo and Instructions

Reminder : Make sure that you’re ready to go with your lab0 by ensuring you’ve run the following commands:

from the nr1-workshop directory

cd lab0
nr1 nerdpack:uuid -gf

Create A Launcher

Launchers are a type of artifact within a Nerdpack that is selectable from the New Relic One homepage, and serves as an entry to a Nerdlet.

  1. Use the New Relic One CLI to create a new Launcher
    assuming we’re in nr1-workshop/lab0
    nr1 create
    ? What kind of component do you want to create? launcher

    chose launcher and name your component lab0-launcher
    ? Name your component. lab0-launcher
    Component created successfully!
    launcher lab0-launcher is available at "./launchers/lab0-launcher"

You’ll notice that the CLI creates a ./launchers/lab0-launcher directory: with a nr1.json configuration.

  1. Now that you have a Launcher, open the launchers/lab0-launcher/nr1.json . You’ll see something like this.
        "schemaType": "LAUNCHER",
        "id": "lab0-launcher",
        "displayName": "Lab0Launcher",
        "description": "",
        "icon": "interface_placeholders_icon-placeholder",
        "rootNerdletId": "replace-me-with-nerdlet-id"
  1. Now, we’re going to start our development server using the CLI.
    > npm install
    > nr1 nerdpack:serve

# Note: Once you start the local server, it will automatically listen for changes in the file system. To issue commands while the local server is running, simply open a new terminal and change to the lab0 directory.

  1. Navigate in Google Chrome to and click on the Lab0Launcher .

Your browser should look something like the screenshot below showing a 404 error message. Why? Remember that a Launcher is the entry point on the Home page to a specific Nerdlet. Currently, the Lab 0 Launcher is not connected to a Nerdlet, which causes an error to be displayed. Let’s fix that by creating a Nerdlet and connecting it to the Lab0 Launcher.

(Did you think you would be excited to see a 404 error today?)

Keep reading and we’ll create a new Nerdlet and connect our Launcher to this Nerdlet!

Create a Nerdlet

A Nerdlet is the main artifact that is included within an Nerdpack. A Nerdlet consists of three files by default: index.js , styles.scss , and a nr1.json configuration.

A Nerdlet is where the bulk of the code in your Nerdpack will live.

  1. Use the CLI to create a Nerdlet.

assuming we’re in nr1-workshop/lab0

nr1 create
? What kind of component do you want to create? nerdlet
? Name your component. lab0-nerdlet
Component created successfully!

your lab0-nerdlet is available at "./nerdlets/lab0-nerdlet"

You’ll notice that the CLI creates three files in the ./nerdlets/lab0-nerdlet directory: index.js , styles.scss , and a nr1.json configuration.

  1. Open the project in your text editor or IDE (reminder: these instructions assume Visual Studio Code, but you are free to use the IDE of your choice. Here’s a shout out to all the VI users!! :tada: )

if you’re not there already, navigate to the workshop directory

cd nr1-workshop/lab0

open the current project directory in your IDE


  1. A Nerdlet is created and added to the ./lab0/nerdlets folder. Your code editor should look similar to the screenshot below:

Connecting your Launcher and Nerdlet

  1. Within ./lab0/launchers/lab0-launcher open the Launcher’s nr1.json configuration file and add the correct rootNerdletId .

  1. Replace the code within ./lab0/launchers/lab0-launcher/nr1.json with the JSON object below.
        "schemaType": "LAUNCHER",
        "id": "lab0-launcher",
        "displayName": "Lab 0 Launcher",
        "description": "",
        "icon": "interface_placeholders_icon-placeholder",
        "rootNerdletId": "<your_package_id>.lab0-nerdlet"
  1. To draw the association precisesly, open the file lab0/package.json and find the value of the attribute nr1.uuid . That uuid is the identifier of your package.

  2. Save the nr1.json , then navigate back and click on the Lab0Launcher . Your browser window should look similar to below with the lab0-nerdlet launched.

Helpful hint: if not, restart your local developer server by typing Ctrl + c in the Terminal and then running nr1 nerdpack:serve .

Creating a Nerdpack (!)

What’s a Nerdpack again…?

A Nerdpack is a deployable unit that contains one or more artifacts. A Nerdlet is the main artifact in a Nerdpack, but Nerdpacks can also include Launchers, overlays, hooks, and entities.

In steps 1-3 we were creating a lab0 Nerdpack. Yet, there is a quicker way to create a Nerdpack with a Launcher and Nerdlet already connected.

nr1 create will do it for you!

From your root directory (or the directory your want your Nerdpacks located), run the following command in your terminal:

The CLI will create a new folder to contain the artifacts within your Nerdpack

nr1 create
? What kind of component do you want to create? package
? Name your component. lab0-nerdpack
Component created successfully!

You’ll notice that the CLI creates a /lab0-nerdpack directory: including launchers and nerdlets folders, and all of the needed internal files.

If you go into the lab0-nerdpack directory and run npm install && npm start you will be able to run your package!

The GitHub repositories for Lab0-Lab10 can be found here.

Questions? :thinking:

Did we lose you somewhere? Any tricky bits you are stumbling over? Let us know below—we are here and willing to learn all together!

FutureHack Nerdpack Contest - Win an iPad!
Insights api request through react
Remove "Since 30 minutes ago" even when I use time series since the data that is being sent to insights is Custom

Hello! I’ve been working through the labs. For some reason, in lab 6, when i query the accounts here:{ %20%20actor%20{ %20%20%20%20accounts%20{ %20%20%20%20%20%20id %20%20%20%20%20%20name %20%20%20%20} %20%20} }

I see all the accounts i have access to.

However, the query in the nerdpack in lab 6 i only see 1 account.

Do you know what i’m doing wrong?




Ok, so I’m having issues and can’t seem to generate the same screens as you have. I have gone through and obtained VS Code so I could easily follow along but when I try and “Connect my launcher and nerdlet”; I’m having issues.

I opened the JSON file and added the correct rootNerdletID but still have issues. Here’s what I have in my lab0-launcher nr1.json file:

“schemaType”: “LAUNCHER”,
“id”: “lab0-launcher”,
“displayName”: “Lab 0 Launcher”,
“description”: “”,
“icon”: “interface_placeholders_icon-placeholder”,
“rootNerdletId”: “MY ID.lab0-nerdlet”

and here’s what keeps displaying:
404 - Nerdlet “MY ID.lab0.root” not found.

I did have lab0.root in the nr1 file, but removed that based on what you instructed me to do. So, what am I doing wrong? Using Chrome as a browser as well.

Ok, not sure what was happening but I downloaded and reinstalled the setup and went through everything and this time it worked fine.


Hey @dave.houlker I suspect this is a problem with the scope of the API keys you are using.

The API key set in your nr1 CLI Profile is somewhat different to the API key you will use in the GraphQL explorer.

I’ll chat to the team to get further clarification, but for now I’m thinking this is expected, and based on the scope of API keys.


@cnorman -

That is odd - I just ran through Lab0 and had no such problems :confused:

Anyway, thanks for updating to say that it’s now working fine for you. Let us know if you run into any further issues.


Hello! I’m a React developer for my team and just started the workshop exercises. I got on the React bandwagon pretty recently and am more familiar with newer syntax (React versions >=16.8), and I noticed the nr1 create command starts at React 16.6.3 and doesn’t build the application on my device (at least not from what I can tell).

If I install newer versions/features of React (or other dependencies for that matter), will it work just fine when I run nr1 nerdpack:serve?


Hey @Kyle.Berkley - I asked this in our internal channels for you and below is the response I got:

any feature released after the 16.6.3 version won’t be available. But we are passing the feedback to the team to see how feasible is to move to more recent versions of React.

So right now newer versions of react may allow you to serve nerdpacks, but newer react features won’t be available to you.


I appreciate you asking! Is there a roadmap/document I can check periodically for any changes to version compatibility? I totally understand if it’s not a priority, my team and I are all in the same boat with being more familiar with React “hooks” and it would help us get up and running quickly but React is React :smiley:

Regardless NR1 looks great so far, and thanks again for your response!


@Kyle.Berkley - No worries, glad you’re liking New Relic One :smiley:

We don’t have anything public RE: roadmap - but I’ll chat to the team to see if they are adding the NR1 CLI to our Release Notes section in Docs.
If not, we’re always here in the Explorers Hub, if there’s ever a roadmap question, or any questions, we’ll be able to ask them internally and relay that info back to you.

pinned #10