Skip to main content

​
Lens Web SDK

The public frontend SDK is @lens/web. Use it when you want to instrument a browser app and start sending telemetry to Lens with minimal setup.

​
Before you start

Make sure you have:
  • a Lens account
  • a project in Lens
  • a project API key
  • a frontend app you can deploy

​
1. Create or find your API key

In Lens:
  1. Open your project.
  2. Go to the API keys page.
  3. Create a key for your frontend app.
  4. Copy the secret value somewhere safe. You will use it in your frontend environment.

​
2. Install the SDK

npm install @lens/web
If you use pnpm: 
pnpm add @lens/web

​
3. Add frontend runtime configuration

Your browser app needs to expose three values to client-side code:
  • a Lens collector endpoint
  • a Lens API key
  • a stable service name
For a Vite app, that can look like: 
VITE_LENS_OTLP_ENDPOINT="https://collector.lens.sh"
VITE_LENS_API_KEY="YOUR_API_KEY"
VITE_LENS_SERVICE_NAME="my-app-web"
VITE_LENS_SERVICE_NAME should be stable and descriptive. Treat it as the service identity that will show up in Lens queries and dashboards.

​
4. Initialize Lens once at startup

import { init } from '@lens/web'

export const lens = init({
  endpoint: import.meta.env.VITE_LENS_OTLP_ENDPOINT,
  apiKey: import.meta.env.VITE_LENS_API_KEY,
  serviceName: import.meta.env.VITE_LENS_SERVICE_NAME,
})
Initialize the SDK once near your application bootstrap, before most user navigation happens.

​
5. Attach user identity after auth loads

Use an opaque internal ID, not email. 
lens.setUser({
  id: currentUser.id,
})
If your project context matters for debugging, you can also attach metadata: 
lens.setMetadata({
  app: 'dashboard-web',
  projectId: activeProject.id,
  projectName: activeProject.name,
})

​
6. Deploy and verify

After deploying:
  1. Load the app in a browser.
  2. Navigate across a few routes.
  3. Trigger a handled or unhandled frontend error.
  4. Open Lens and confirm you see incoming page views, errors, and Web Vitals.

​
What is automatic

With @lens/web, Lens automatically captures:
  • page views
  • session start
  • unhandled errors
  • unhandled promise rejections
  • Web Vitals
You only need manual calls for product-specific events: 
lens.trackInteractionEvent('clicked_upgrade')
lens.trackBusinessEvent('Subscription', 'Started')

​
Troubleshooting

If you do not see data:
  1. Confirm your deployed frontend environment exposes the Lens API key used by the SDK.
  2. Confirm your deployed frontend environment exposes the Lens OTLP endpoint and that it resolves to https://collector.lens.sh.
  3. Confirm the SDK is initialized exactly once.
  4. Confirm the browser network tab shows requests to /v1/logs.
  5. Confirm you are looking at the correct Lens project for that API key.
If you use Vite, those values are typically named:
  • VITE_LENS_API_KEY
  • VITE_LENS_OTLP_ENDPOINT
  • VITE_LENS_SERVICE_NAME

​
Next

Once the base integration is working, instrument the app you care about first and expand from there.