---
name: vector-nextjs
description: "Provisions an Upstash Vector index for a Next.js app with `npx extraorbital add vector` (no signup, no card) and wires it into Next.js with `@upstash/vector`. Use when a Next.js project needs Vector index, embeddings, semantic search, RAG, a vector database or UPSTASH_VECTOR_REST_URL, or when UPSTASH_VECTOR_REST_URL is missing or unset in .env."
---

# Vector index in Next.js

<!-- Generated from ExtraOrbital's service registry by `pnpm skills:build` in platform/app. Edit the generator, not this file. -->

ExtraOrbital provisions an Upstash Vector index in one command and writes the credentials into the project's env file. For anything this recipe does not cover, use the `extraorbital` skill or https://extraorbital.dev/llms.txt.

## 1. Provision

```bash
npx extraorbital add vector
```

Run it from the project root. It is idempotent (a second run returns the same resource) and writes to `.env.local` if the project has one, otherwise `.env`, keeping that file out of git. Add `--json` to parse the result; credential values are redacted there, and you should never print them either.

| Variable | |
| --- | --- |
| `UPSTASH_VECTOR_REST_URL` |  |
| `UPSTASH_VECTOR_REST_TOKEN` |  |

Free on the Prototype plan: 10K queries + 10K updates/day.

## 2. Install the client

```bash
npm install @upstash/vector
```

## 3. Connect

Next.js loads both `.env.local` and `.env`, so either file ExtraOrbital writes is read on the next `next dev`.

**`lib/vector.ts`**

```ts
import { Index } from "@upstash/vector";

export const vectorIndex = new Index({
  url: process.env.UPSTASH_VECTOR_REST_URL!,
  token: process.env.UPSTASH_VECTOR_REST_TOKEN!,
});
```

## 4. Use it

**`app/api/vector/route.ts`**

```ts
import { vectorIndex } from "@/lib/vector";

export async function GET() {
  const info = await vectorIndex.info();
  return Response.json({ vectors: info.vectorCount, dimension: info.dimension });
}
```

Store and search:

```ts
// Each vector must have the index's dimension (1536 unless provisioned otherwise).
await vectorIndex.upsert({ id: "doc-42", vector: embedding, metadata: { title: "Q3 report" } });
const hits = await vectorIndex.query({ vector: queryEmbedding, topK: 5, includeMetadata: true });
```

## 5. Verify

```bash
npx extraorbital list        # the resource is listed as active
npm run dev
curl http://localhost:3000/api/vector
```

A JSON answer means the credentials, the client and the route all work. Delete the route afterwards if the app does not need it.

## Pitfalls

- Dimensions and the similarity function are fixed at creation. Match the embedding model: `npx extraorbital add vector --dimensions 3072` (default 1536, `COSINE`); to change them, provision a new `--slug` and re-index.
- `provision .` creates the index at 1536 dimensions when it detects the variables; run `add vector --dimensions …` first if your model differs.
- Embeddings come from your model; for an API key to call one, see the `ai-gateway-*` skills.
- Import the module only from server code (route handlers, server components, server actions). Only `NEXT_PUBLIC_*` variables reach the browser, and nothing else should.
- With a `src/` directory the module goes in `src/lib/`; without the `@/*` path alias, import it relatively.
- Restart `next dev` after the env file changes: it is read at startup.
- Exit code 3 means the account is past its free allowance: show the human the link the command printed and wait. Do not retry or work around it.

Docs: https://extraorbital.dev/docs/resources/vector.md