Project setup

Prerequisites

• Node.js 20 or newer — required by Next 16 and the React 19 toolchain.
• A package manager — npm (used in the examples below), pnpm, or yarn.
• A Clerk application — for authentication. You'll need the publishable key, secret key, and a webhook signing secret.
• A Neon (Postgres) database — for storing users and the encrypted vault blobs.

Getting started

# 1. Install dependencies
npm install

# 2. Create your env file (see the table below)
cp .env.example .env.local

touch .env.sample

# 3. Run the dev server
npm run dev

For Different Packages :

Different packages are :

• npm (Node Package Manager)
• bun
• yarn

# 1 For Node Package Manager
npm run dev

# 2 For Bun Package Manager
bun dev

# 3 For PNPM Package Manager 
pnpm dev

The app will be available at http://localhost:3000.

Available scripts

Environment variables

Create a .env.local file in the project root. None of these are encryption keys for your vault — those are derived in the browser and never stored here.

Database

The schema centers on a few tables that the route handlers expect to exist:

• users — one row per Clerk user, holding profile fields plus the wrapped vault keys, KDF salt/params, vault_initialized flag, and item_count.
• plans — defines each plan's item_limit. Every user row references a plan.
• vault_items — the encrypted items (ciphertext, iv, type, favorite, folder_id).
• vault_folders and vault_audit_log — folders and an audit trail, both removed via ON DELETE CASCADE when a user is deleted.

Tip: Seed the plans table before creating items. The item-insert query joins plans to read item_limit; if there is no matching plan row, the insert finds nothing and item creation fails. This is a common first-run gotcha.

In development, the Clerk webhook can't reach localhost, so a user row may not exist yet. The /api/vault/init route creates it on first vault setup using ON CONFLICT DO NOTHING, keeping the webhook as the source of truth in production.

What to put — and what not to

Put in version control: the source, the .env.example template (with empty or placeholder values), and the database migration/seed files.

Keep out of version control and out of this doc:

• Real values for any variable in the table above — commit only .env.example, never .env.local.
• Master passwords, recovery phrases, or any derived key material. These exist only in the browser at runtime and must never touch the server, logs, or the repo.
• The deep crypto walkthrough and full endpoint reference — those belong on the Encryption and API pages, not in setup, so this guide stays short.

Dependencies

A complete list of what's installed and why. Scope distinguishes runtime packages from development-only tooling.

Where to go next

• Architecture — how the routes, database, and webhook sync fit together.
• Encryption — the key-wrapping and recovery-phrase flow.
• Introduction — the high-level overview of the project.