@gsol-frontend/nuxt2-monitor

@gsol-frontend/nuxt2-monitor

GSOL browser monitoring SDK and Nuxt 2 integration, maintained in the gsol-egg repository. The package contains the browser script served by the Egg monitor endpoint and a Nuxt 2 module for SDK setup and route metadata.

Nuxt 2 integration

Install the package and register the module once in nuxt.config.js:

npm install @gsol-frontend/nuxt2-monitor

module.exports = {
  modules: ['@gsol-frontend/nuxt2-monitor']
}

The module reads monitor-config.js from the Nuxt project's root by default. It accepts appId, appKey, env, release, subApp, and reportUrl; each value can instead come from MONITOR_APP_ID, MONITOR_APP_KEY, MONITOR_ENV, MONITOR_RELEASE, MONITOR_SUB_APP, and MONITOR_CLIENT_REPORT_URL. Explicit module options override both sources. appKey is a browser credential and will be included in the SDK URL. The client module deliberately does not read the server-side MONITOR_REPORT_URL variable.

The module injects the Egg-hosted browser SDK, annotates generated Nuxt routes, and connects route changes to the SDK. On the server, it also records $axios requests made during SSR as ssr_api events, including successful responses, HTTP failures, and network failures. The server plugin runs after the Nuxt Axios module injects $axios and before application plugins and asyncData. It does not capture fetch or separate Axios instances.

Configure the following variables in the Nuxt server process before starting Nuxt:

MONITOR_REPORT_URL=https://monitor.example.com/api/v1/monitor/server/report
MONITOR_SERVER_REPORT_TOKEN=<the application's server report token>

MONITOR_REPORT_URL defaults to the browser reportUrl with /report replaced by /server/report. The Token is read only at runtime in the server plugin and is never included in the browser bundle. Without a Token, SSR API reporting is skipped. Existing application-specific SSR error hooks remain separate. To disable automatic $axios capture, set the module option serverApi: false.

For the optional monitor-playground test page, enable its three test APIs without application-side middleware files:

module.exports = {
  modules: [['@gsol-frontend/nuxt2-monitor', { playground: true }]]
}

This registers /api/monitor-test, /api/server-monitor-test, and /api/server-code-error. The test endpoints deliberately return failures and should only be enabled where the playground is needed. Server-side test reports use MONITOR_REPORT_URL and MONITOR_SERVER_REPORT_TOKEN at runtime; neither value is bundled into the browser script.

Build

From this directory:

npm run build

The build copies src/monitor-sdk.js to dist/monitor-sdk.js and synchronizes Egg's compatibility copy at app/public/monitor-sdk.js. The Egg /api/v1/monitor/sdk.js endpoint reads the package's dist file and injects application configuration and sampling settings at request time.

Local development before publishing

Link this package while changing the SDK or Nuxt adapter:

# In packages/nuxt2-monitor-sdk
npm run build
npm link --ignore-scripts

# In each Nuxt 2 application
npm link @gsol-frontend/nuxt2-monitor --no-save --ignore-scripts

For applications with existing peer dependency conflicts, add --legacy-peer-deps to the application-side npm link command. Linking changes only the local node_modules; keep package.json and the lockfile on the latest published version. Restart Nuxt after changing module code. Run npm run build again after editing src/monitor-sdk.js so the Egg-served browser script is refreshed. Test the linked application, then pack and publish a new version. Finally, install that exact published version in each application to replace the local link.

Browser setup

Load the Egg-hosted script after configuring the public browser credentials:

<script>
  window.__MONITOR__ = {
    appId: 'your-app-id',
    appKey: 'your-app-key',
    env: 'production',
    reportUrl: 'https://monitor.example.com/api/v1/monitor/report'
  }
</script>
<script src="https://monitor.example.com/api/v1/monitor/sdk.js" defer></script>

appKey is a browser-side application credential and must be protected with the monitor application's domain allowlist and rate limits. Never include a server report token in browser configuration or this package.

The app/public/monitor-sdk.iife.js file is a separate legacy script and is not part of this package. The maintained and hosted implementation is src/monitor-sdk.js.

Package contents

The npm tarball is restricted to this package's entry file, documentation, license, source, and built browser script. It does not include Egg environment files, database credentials, server report tokens, or the rest of the application repository.