@lucenthq/cli is a zero‑config installer for the Lucent browser SDK. Run it
once, pick your framework, and the CLI writes the provider file, adds the
environment variable, and wraps your app tree so recording starts on the next
page load.
What the CLI does
- Validates your public key against the Lucent ingest API.
- Prompts for your framework and (where relevant) a sub‑variant like App Router vs Pages Router, or Vite vs Create React App.
- Detects your package manager (
npm,yarn,pnpm) and installs@lucenthq/sdk. - Writes an environment variable into the right
.envfile for your framework (NEXT_PUBLIC_LUCENT_PUBLIC_KEY,VITE_LUCENT_PUBLIC_KEY, etc.). - Creates a provider or service file (
app/providers.tsx,src/lib/lucent.ts,lucent.service.ts, …). - Modifies your root file to wire the provider into your app tree.
Supported frameworks
Next.js
App Router and Pages Router.
React
Vite and Create React App.
Vue
Vue 3 with Vite.
Angular
Standalone (17+) and NgModule.
Svelte
SvelteKit and plain Svelte.
Nuxt
Nuxt 3.
Remix
Remix v2.
Astro
Astro with Layout components.
Gatsby
Gatsby v5.
Vanilla JS
Plain JavaScript, any bundler.
Flags
Print every action the CLI would take without touching the filesystem or
installing any packages. Useful for previewing changes in a clean repo.
What the CLI fully automates vs what it scaffolds
Not every framework can be wired up without human judgment. The table below is the honest truth about whatnpx @lucenthq/cli init does for each framework.
When a framework is marked scaffold + manual step, the CLI still writes the
provider file and env var — it just prints one final step you need to do by
hand. Every framework page in this section shows exactly what that step is.
| Framework | Category | Final step |
|---|---|---|
| Next.js App Router | Fully automatic | — |
| React (Vite) | Fully automatic | — |
| React (CRA) | Fully automatic | — |
| Vue | Fully automatic | — |
| SvelteKit | Fully automatic | — |
| Svelte (plain) | Fully automatic | — |
| Astro | Fully automatic | — |
| Gatsby | Fully automatic | — |
| Next.js Pages Router | Scaffold + manual step | Wrap <Component> with <LucentProvider> in pages/_app.tsx |
| Angular (Standalone) | Scaffold + manual step | Inject LucentService in AppComponent so DI instantiates it |
| Angular (NgModule) | Scaffold + manual step | Inject LucentService in AppComponent so DI instantiates it |
| Nuxt | Scaffold + manual step | Add lucentPublicKey to runtimeConfig.public in nuxt.config.ts |
| Remix | Scaffold + manual step | Expose LUCENT_PUBLIC_KEY via a loader |
| Vanilla JS | Scaffold only | Add the script tag and bundle the init file yourself |
The “fully automatic” list is verified by running the CLI against real
starter files for each framework and checking that the output compiles.
If you hit a case the CLI can’t handle — e.g. a customized
layout.tsx
with a non‑standard structure — the CLI falls back to manual instructions
instead of producing broken code.Troubleshooting
Validation failed — 'Invalid or revoked public key'
Validation failed — 'Invalid or revoked public key'
Either the key is wrong, has been revoked in the dashboard, or belongs to
a different org. Get a fresh key at Settings → SDK keys in
app.lucenthq.com.
Could not reach Lucent API
Could not reach Lucent API
The CLI validates your key against the ingest API before touching your
project. Check your network connection and retry. If you’re behind a
corporate proxy, you may need to configure
HTTPS_PROXY.CLI skipped my root file
CLI skipped my root file
The CLI skips files that already contain the word “lucent” or reference
@lucenthq/sdk. This is intentional — rerunning the CLI won’t clobber
an existing setup. If you want to re‑apply the template, remove the
Lucent references by hand first.My framework isn't listed
My framework isn't listed
Use the vanilla JS instructions — they work
with any bundler. If you’d like first‑class support for your framework,
open an issue.