vektis-install

vektis-install installs the @vektis-io/tracker SDK in your current project. It detects your framework, authenticates with VEKTIS, auto-creates an SDK API key on your behalf, writes the env var, and inserts the init code — with diff confirmations at each write.

claude /vektis-install

The default path is OAuth — zero credential pastes. The fallback (--paste-token) is at most one paste action. Both paths produce a working install in under 15 minutes.

When to use this skill

You’re in this situation	Use this skill
Just want the SDK installed; you’ll set up tracking later	`vektis-install`
Want install + tracking setup in one go	`vektis-bootstrap`
Already have the SDK installed and want to follow a manual framework guide	Per-framework guides

If the SDK is already installed (@vektis-io/tracker in package.json AND a vektis.init( call exists in your source), the skill detects it on first launch and skips straight to verification.

Supported frameworks

Framework	Detected by	Where init code lands
Next.js (App Router)	`"next"` in dependencies + `app/` directory	New `app/_vektis-init.tsx` client component, imported into `app/layout.tsx`
Next.js (Pages Router)	`"next"` in dependencies + `pages/` directory (no `app/`)	`pages/_app.tsx` (created if absent)
Vite + React	`"vite"` + `"react"` + `vite.config.{ts,js,mjs}`	`src/main.tsx` (or `.jsx`) before render
Nuxt 3	`"nuxt"` (^3) + `nuxt.config.{ts,js}`	New `plugins/vektis.client.ts` + `runtimeConfig` in `nuxt.config.ts`
SvelteKit	`"@sveltejs/kit"` + `svelte.config.{ts,js}`	New `src/hooks.client.ts`
Create React App	`"react-scripts"` in dependencies	`src/index.tsx` (or `.js`)
Vanilla / CDN	None of the above + an `index.html` exists at root	Inline `<script>` in `<head>` (you paste the API key manually — see below)

If multiple match (monorepo edge case), the skill prompts you to choose. If none match, it surfaces the supported list and exits.

What it walks through

Detect framework. Reads package.json and project files. Prints Detected framework: <name>.
Detect existing install (idempotency). If the SDK is already installed and initialized, jump to verification. Otherwise continue.
Authenticate. OAuth browser flow on first run, cached afterwards in ~/.vektis/credentials.json. Subsequent skill runs reuse the cached token silently.
Auto-create the SDK API key. The skill calls VEKTIS to create a new API key labeled vektis-install (<framework>) in the development environment by default. You never see or paste the key value — it flows directly from the response into the env-var write step. Rotate to a staging or production key in the dashboard before deploying.
Write env var. Each framework has a specific env-var name (e.g., NEXT_PUBLIC_VEKTIS_KEY for Next.js, VITE_VEKTIS_KEY for Vite). The skill shows a unified diff appending the new line to the right env file (.env.local for most, .env for Nuxt and SvelteKit). You confirm the diff before writing.
.gitignore audit. Reads your .gitignore and checks whether the env file is matched by any pattern — including generous globs like .env*, *.local, **/.env.local. If no pattern matches, the skill prompts to add the env file. You see the diff before the append.
Insert init code. Per framework. Always shows a unified diff and waits for your approval before writing. The exact code varies — see per-framework guides for what each looks like.
Install the SDK package. Runs npm install @vektis-io/tracker@^1.0.0 (or pnpm add / yarn add / bun add based on your lockfile).
Pointer to optional next steps. Prints a short reminder that CSP and logout-reset are manual decisions, with links to the relevant docs.

Verification instructions. Prints how to verify the install in your browser DevTools:

Install complete. To verify:

  1. Start your dev server (e.g. npm run dev).
  2. Open your app in a browser.
  3. Open DevTools → Console.
  4. Run: vektis.getStatus()

Expected output:
  { state: "READY", queueLength: 0, identityCustomerId: null, identityUserId: null }

API key handling

The skill auto-creates a key, writes it to your env file, and never prints it to the terminal. The default environment is development — keys look like vk_dev_*.

When you deploy to staging or production, don’t ship the development key. Rotate to a staging or production key from the dashboard’s Settings → API & CLI tokens page, and update your hosting provider’s env vars accordingly.

Hard guarantees

The skill never prints or displays the SDK API key value. It flows directly from the create-key response into the env-var write.
Every code or config change is shown as a unified diff before being applied. You can refuse any of them.
The skill never auto-edits CSP config files or logout handlers. Those decisions are manual — see the CSP guide and Reset on logout.
Idempotent re-runs. If the SDK is already installed, the skill jumps to verification rather than re-creating keys or duplicating init code.
The role check happens at the auth step. If your VEKTIS user is not an admin, the skill exits with “Ask your admin to run this skill.” before any key is created.

What happens when something goes wrong

Situation	What the skill does
OAuth polling fails for 10 minutes	The browser flow times out. Restart auth, or re-run with `--paste-token`.
Framework detection finds nothing	Surfaces the supported framework list. If your stack isn’t supported, file an issue or follow a manual framework guide.
API-key creation returns 403	You’re not an admin in your VEKTIS organization. The auth step’s role check should have caught this — if it surfaces here, ask your admin to run the skill.
`.env.local` write permission denied	Skill prints the diff and the path; you create the file manually.
Init-code site not found (unusual project structure)	Skill prompts you for the correct file.
You cancel mid-flow	Auth credentials in `~/.vektis/credentials.json` are preserved (so the next run doesn’t re-prompt the browser). No app files are modified yet — every write was diff-confirmed.

Flags

--paste-token — skip the OAuth browser flow and use a manually-pasted CLI token instead. Useful on headless servers, restrictive corporate firewalls, or anywhere a default browser isn’t available.

What this skill does NOT do

Modify your CSP config — fragile detection. See CSP guide.
Insert a vektis.reset() call in your logout handler — auth-provider detection is fragile. See Reset on logout.
Add vektis.identify(...) to your auth flow — the skill writes a placeholder example in the init code, but wiring real customer/user IDs is your call.
Create Dev Items in your dashboard — that’s vektis-discover + vektis-instrument, or the manual wizard in /dev.

Skills overview
Per-framework SDK install guides — manual install if you’d rather not use the skill
vektis-bootstrap — runs this skill plus discover + instrument as one flow
Content Security Policy — manual CSP setup
Reset on logout — manual logout handler
Tracker troubleshooting — what to check when verification fails