Star us on GitHub

Using with Gatsby

Learn how to set up with your Gatsby application.
Install the gatsby plugin.

Install the npm pulugin in your terminal.

# with npm npm install @highlight-run/gatsby-plugin-highlight
# with yarn yarn add @highlight-run/gatsby-plugin-highlight
# with pnpm pnpm add @highlight-run/gatsby-plugin-highlight
Initialize the plugin in your gatsby configuration.

Grab your project ID from, and set it as the orgID.

To get started, we recommend setting environment, version, and networkRecording. Refer to our docs on SDK configuration to read more about these options.

module.exports = { plugins: [ { resolve: '@highlight-run/gatsby-plugin-highlight', options: { orgID: '<YOUR_PROJECT_ID>', // Get your project ID from }, }, ], }
Identify users.

Identify users after the authentication flow of your web app. We recommend doing this in any asynchronous, client-side context.

The first argument of identify will be searchable via the property identifier, and the second property is searchable by the key of each item in the object.

For more details, read about session search or how to identify users.

import { H } from ''; function Login(username: string, password: string) { // login logic here... // pass the user details from your auth provider to the H.identify call H.identify('', { id: 'very-secure-id', phone: '867-5309', bestFriend: 'jenny' }); }
Verify installation

Check your dashboard for a new session. Make sure to remove the Status is Completed filter to see ongoing sessions. Don't see anything? Send us a message in our community and we can help debug.

Configure sourcemaps in CI. (optional)

To get properly enhanced stacktraces of your javascript app, we recommend instrumenting sourcemaps. If you deploy public sourcemaps, you can skip this step. Refer to our docs on sourcemaps to read more about this option.

# Upload sourcemaps to Highlight ... npx --yes @highlight-run/sourcemap-uploader upload --apiKey ${YOUR_ORG_API_KEY} --path ./build ...
Instrument your backend.

The next step is instrumenting your backend to tie logs/errors to your frontend sessions. Read more about this in our backend instrumentation section.