---
title: "Velt Next.js Starter Kit"
description: "Collaborative docs app: real-time editing, comments, presence, live cursors, and per-document sharing. Built with Next.js and Velt."
url: "https://vercel.com/templates/next.js/velt-next-js-starter-kit"
links:
  repository: "https://github.com/velt-js/velt-next-js-templates/tree/main/tiptap"
  demo: "https://velt-tiptap-next-js-templates.vercel.app"
  deploy: "https://vercel.com/new/clone?demo-title=Velt+Next.js+Starter+Kit&demo-description=Collaborative+docs+app%3A+real-time+editing%2C+comments%2C+presence%2C+live+cursors%2C+and+per-document+sharing.+Built+with+Next.js+and+Velt.&demo-url=https%3A%2F%2Fvelt-tiptap-next-js-templates.vercel.app&demo-image=%2F%2Fimages.ctfassets.net%2Fe5382hct74si%2F5s68K3i24oY3vXG6WOkLYL%2Fc8470e6cfbfc2bfa7f4a49b0b83f09f6%2Fvelt-template-thumbnail-editor.png&project-name=Velt+Next.js+Starter+Kit&repository-name=velt-next-js-starter-kit&repository-url=https%3A%2F%2Fgithub.com%2Fvelt-js%2Fvelt-next-js-templates%2Ftree%2Fmain%2Ftiptap&from=templates&integration-ids=Upstash&skippable-integrations=1&env=NEXT_PUBLIC_VELT_API_KEY%2CVELT_AUTH_TOKEN&envDescription=Your+Velt+API+key+and+auth+token+%28free+at+console.velt.dev%29.&envLink=https%3A%2F%2Fdocs.velt.dev%2Fget-started%2Fquickstart&root-directory=tiptap&project-names=Comma+separated+list+of+project+names%2Cto+match+the+root-directories"
---

# Velt Next.js Starter Kit

Collaborative docs app: real-time editing, comments, presence, live cursors, and per-document sharing. Built with Next.js and Velt.

A full collaborative-documents app built with [Next.js](https://nextjs.org) (App
Router) and [Velt](https://velt.dev) — like a minimal Google Docs. Sign in, see
your documents, create new ones, share them with teammates (viewer / editor),
and edit together in real time.

It demonstrates the core Velt features inside a realistic, multi-user app with
working access control:

- **Real-time editing (CRDT)** — a [TipTap](https://tiptap.dev) editor synced with Yjs
- **Comments** — inline comments on selected text + a comments sidebar
- **Presence & live cursors** — see who's online and where their cursor is
- **Notifications** — in-app panel for mentions, replies and shares
- **Sharing & permissions** — restricted documents with per-user viewer/editor roles, enforced by Velt

## Tech stack

- Next.js 16 (App Router) · React 19 · TypeScript
- Velt SDK (`@veltdev/react`) + TipTap CRDT & Comments packages
- Tailwind CSS v4

---

## Deploy to Vercel

Click the **Deploy with Vercel** button above. The clone flow will prompt for the
two required Velt environment variables (`NEXT_PUBLIC_VELT_API_KEY`,
`VELT_AUTH_TOKEN`) and deploy the `tiptap/` directory.

Then add a storage backend so the document directory persists (Vercel's runtime
filesystem is read-only, so the local JSON store can't be used in production):

1. In your Vercel project: **Storage → Create Database → Upstash for Redis** and
   **Connect to Project**. Vercel injects `KV_REST_API_URL` + `KV_REST_API_TOKEN`
   automatically (the variables `lib/documentStore.ts` reads).
2. Redeploy.

See [The document directory: local dev vs. hosting](#the-document-directory-local-dev-vs-hosting)
for details.

## Getting started

### 1. Get your Velt credentials

Create an app at [console.velt.dev](https://console.velt.dev) and copy your **API
key** and **Auth Token**.

### 2. Configure environment variables

```bash
cp .env.example .env
```

```bash
# .env
NEXT_PUBLIC_VELT_API_KEY=your_velt_api_key_here   # public, used in the browser
VELT_AUTH_TOKEN=your_velt_auth_token_here         # secret, server-only (token + REST calls)
```

### 3. Install & run

```bash
pnpm install   # or npm install / yarn
pnpm dev
```

Open [http://localhost:3000](http://localhost:3000).

### 4. Try collaboration with two users

1. In your main browser, pick a demo user on the sign-in page, then **create a document**.
2. Open a second browser (or an incognito window) and sign in as a **different** demo user.
3. That user's dashboard is empty — the document is restricted and not shared yet.
4. Back in the first browser, click **Share** and invite the second user as **Editor**.
5. Reload the second browser — the document now appears and opens. Type together,
   add comments, and watch presence avatars + live cursors update in real time.
6. Change the second user to **Viewer** and reload — their editor becomes read-only.
   Revoke access and reload — they're locked out.

---

## How it works

### Authentication (demo)

`app/userAuth/AppUserContext.tsx` stores the demo user you pick on `/signin` in
`localStorage`. The fixed demo users live in `lib/demoUsers.ts`.

> **In your real app:** delete the demo pieces and pass your authenticated user
> (from NextAuth, Clerk, Auth0, …) to Velt. The only integration point is
> `components/velt/VeltInitializeUser.tsx`.

### Identifying the user to Velt

`components/velt/VeltInitializeUser.tsx` builds the Velt `authProvider`. Its
`generateToken` callback calls `POST /api/velt/token`, which mints a JWT via the
Velt REST API encoding the user's access to the organization and the document
they're opening (with their `viewer` / `editor` role).

### Documents, sharing & permissions

Velt is the source of truth for collaboration data and permission enforcement,
but it has no "list every document a user can access" query — so the dashboard
keeps a small directory of its own.

- **`lib/veltRest.ts`** — server-only wrapper around the Velt REST API
  (create / rename / delete documents, set access type, grant / revoke permissions).
- **`lib/documentStore.ts`** — the per-organization document directory used to
  render each user's dashboard. **This is the only place that touches storage.**

| Action | Route | Velt REST calls |
| --- | --- | --- |
| Create | `POST /api/documents` | `documents/add` → `documents/access/update` (restricted) → `auth/permissions/add` (owner = editor) |
| List | `GET /api/documents` | — (reads the directory) |
| Rename / Delete | `PATCH` / `DELETE /api/documents/[id]` | `documents/update` / `documents/delete` |
| Share / Revoke | `POST` / `DELETE /api/documents/[id]/share` | `auth/permissions/add` / `auth/permissions/remove` |

A newly created document is set to **`restricted`**, so only explicitly invited
users can access it. `AccessGate` (`app/documents/[id]/AccessGate.tsx`) mirrors
this on the client: no access → locked screen, `viewer` → read-only editor.

> Velt also ships a drop-in `<VeltUserInviteTool />` share UI. This kit uses a
> custom `ShareMenu` so sharing is wired to the backend and the dashboard
> directory, but you can swap in the native tool if you prefer.

### The document directory: local dev vs. hosting

`lib/documentStore.ts` picks its backend automatically:

- **Local development** — no config needed. It writes one JSON file per org under
  `data/` (gitignored).
- **Hosted / serverless (e.g. Vercel)** — the runtime filesystem is **read-only**,
  so the JSON-file path can't write (you'll see `ENOENT … mkdir '/var/task/.../data'`).
  Provision a **Vercel KV (Upstash Redis)** store and the directory is kept in Redis
  instead.

**Deploying to Vercel:**

1. In your Vercel project, open **Storage → Create Database → KV (Upstash Redis)**
   and connect it to the project. Vercel injects `KV_REST_API_URL` and
   `KV_REST_API_TOKEN` automatically.
2. Add `NEXT_PUBLIC_VELT_API_KEY` and `VELT_AUTH_TOKEN` as environment variables.
3. Redeploy. The store now uses Redis (durable across instances).

`lib/documentStore.ts` is the only place that touches storage, so swapping Redis
for Postgres/SQLite/etc. is a single-file change.

---

## Project structure

```
app/
  signin/                 demo-user picker
  dashboard/              list / create / rename / delete documents
  documents/[id]/         collaborative editor + ShareMenu + AccessGate
  document/               document metadata context (role, members)
  userAuth/               demo auth (swap for your real auth)
  api/
    velt/token/           mint Velt JWTs (encodes per-document role)
    documents/            create / list / rename / delete / share
components/
  document/               TipTap editor (CRDT + comments wiring)
  velt/                   Velt provider, document setup, tools, collaboration
  header/  sidebar/  ui/  app chrome
lib/
  demoUsers.ts            fixed demo users
  veltRest.ts             server-only Velt REST wrapper
  documentStore.ts        document directory (swap for a DB in production)
```

## Learn more

- [Velt docs](https://docs.velt.dev) · [Velt REST API](https://docs.velt.dev/api-reference/rest-apis)
- [Next.js docs](https://nextjs.org/docs) · [TipTap docs](https://tiptap.dev/docs)

---

## Additional documentation

The [Vercel Knowledge Base](https://vercel.com/kb) contains guides and answers to common questions about Vercel, including deployment, framework configuration, domains, caching, and troubleshooting.