Velt Next.js Starter Kit

A full collaborative-documents app built with Next.js (App Router) and Velt — 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 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 for details.

Getting started

1. Get your Velt credentials

Create an app at console.velt.dev and copy your API key and Auth Token.

2. Configure environment variables

1
cp .env.example .env

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

3. Install & run

1
pnpm install   # or npm install / yarn
2
pnpm dev

Open 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.

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

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

Learn more

• Velt docs · Velt REST API
• Next.js docs · TipTap docs