Installation and setup

Requirements

Node.js 22 or later, with npm, pnpm or yarn.
A VAIF Studio account and project. Create them in the console.

Install the SDK

Add @vaifstudio/client to your app:

npm install @vaifstudio/client

The JavaScript SDK page covers the full API. React and React Native apps can add the React or Expo package on top.

Moving from the older client package? See the migration guide.

Install the CLI

The vaif command-line tool creates tables from SQL files, deploys functions, manages secrets and generates types. Install it globally:

npm install -g @vaifstudio/cli

Then sign in:

vaif login

See CLI for every command.

Environment variables

Put your project’s values in a .env file at the root of your app. Use the same names everywhere, with your framework’s prefix for anything the browser bundle reads:

# Node.js scripts and servers
VAIF_PROJECT_ID=your-project-id
VAIF_PUBLISHABLE_KEY=vk_pub_your_publishable_key

# Vite (React, Vue, Svelte)
VITE_VAIF_PROJECT_ID=your-project-id
VITE_VAIF_PUBLISHABLE_KEY=vk_pub_your_publishable_key

# Next.js
NEXT_PUBLIC_VAIF_PROJECT_ID=your-project-id
NEXT_PUBLIC_VAIF_PUBLISHABLE_KEY=vk_pub_your_publishable_key

Both values are on Security > Credentials in the console.

A server that needs a secret key reads it from VAIF_SECRET_KEY. Never give it a VITE_ or NEXT_PUBLIC_ prefix: those values are copied into the browser bundle.

Keys come in two kinds, and the prefix tells you which. A vk_pub_ key is publishable: row rules apply, and it is safe in browser bundles. A vk_srv_ key is secret: it bypasses row rules and belongs on servers only. See Key types.

Types for your tables

Generate TypeScript types from your tables:

vaif init --typescript
vaif generate --project-id <your-project-id>

vaif init writes vaif.config.json; put your project ID in it, and later commands read it from there. vaif generate reads your schema through the API, so it needs no database address once you have run vaif login. It writes ./src/types/database.ts by default; change that with --output.

The file has a row type, an insert type and an update type for each table, plus the helpers Row<"posts">, Insert<"posts"> and Update<"posts">. Pass a row type to vaif.from<Row<"posts">>("posts") for typed results. A column that a row rule fills on insert, such as author_id, is optional in the insert type.