> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spanary.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Install the Lens web SDK, configure it, and verify telemetry in production.

## 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

```bash theme={null}
npm install @lens/web
```

If you use pnpm:

```bash theme={null}
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:

```bash theme={null}
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

```ts theme={null}
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.

```ts theme={null}
lens.setUser({
  id: currentUser.id,
})
```

If your project context matters for debugging, you can also attach metadata:

```ts theme={null}
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:

```ts theme={null}
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.