Basic Initialization

The first step to using Instant in your app is to call init. Here is a simple example at the root of your app.

import { init } from '@instantdb/react';

// Visit https://instantdb.com/dash to get your APP_ID :)
const APP_ID = '__APP_ID__';

const db = init({ appId: APP_ID });

function App() {
  return <Main />;
}

With that, you can use db to write data, make queries, handle auth, and more!

Typesafety

If you're using typescript, init accepts a schema argument. Adding a schema provides auto-completion and typesafety for your queries and transactions.

import { init, i } from '@instantdb/react';

// Visit https://instantdb.com/dash to get your APP_ID :)
const APP_ID = '__APP_ID__';

const schema = i.schema({
  entities: {
    $files: i.entity({
      path: i.string().unique().indexed(),
      url: i.any(),
    }),
    $users: i.entity({
      email: i.string().unique().indexed(),
    }),
    todos: i.entity({
      text: i.string(),
      done: i.boolean(),
      createdAt: i.number(),
    }),
  },
});

const db = init({ appId: APP_ID, schema });

To learn more about writing schemas, head on over to the Modeling your data section.

Flexible Initialization

Instant maintains a single connection regardless of where or how many times you call init with the same app ID. This means you can safely call init multiple times without worrying about creating multiple connections or performance overhead. However, we do recommend the pattern of exporting a reference from a utility file like so:

// lib/db.ts
import { init } from '@instantdb/react';
import schema from '../instant.schema';

// Visit https://instantdb.com/dash to get your APP_ID :)
const APP_ID = '__APP_ID__';
export const db = init({ appId: APP_ID, schema });

// app/page.tsx
"use client";

import { db } from '../lib/db';

function App() {
  // do some instant magic 🪄
  db.useQuery({ todos: {} });
}

export default App;

Configuration Options

init accepts a few options. For most use cases you'll want to provide appId and schema. Here are all the options you can provide:

  • appId (required): Your InstantDB application ID. This identifies your app and is used to connect to the correct backend.
  • schema?: Instant schema export from your instant.schema.ts file. Provide this for typesafety and auto-completion in queries, transactions, and ephemeral features.
  • websocketURI?: Custom WebSocket endpoint for real-time connections. Defaults to 'wss://api.instantdb.com/runtime/session'. Change this for connecting to development or self-hosted instances.
  • apiURI?: Custom HTTP API endpoint for auth and storage operations. Defaults to 'https://api.instantdb.com'. Change this for connecting to development or self-hosted instances.
  • devtool?: Controls the Instant dev tool. Defaults to true on localhost. Set to false to disable, or configure with { position: 'bottom-right', allowedHosts: ['localhost'] }.
  • verbose?: Enables detailed console logging for debugging. When true, logs WebSocket messages and internal operations. Helpful for troubleshooting connection and sync issues.
  • queryCacheLimit?: Maximum number of query subscriptions to cache for offline mode. Defaults to 10. Cached queries provide instant data on app reload while fresh data loads in the background.
  • useDateObjects?: When true, all date columns in queries will return a Javascript Date object. Disabled by default.

If you are an LLM trying to learn how to develop with Instant, here are all of the links to the docs:

Getting started w/ React
Getting started w/ React Native
Getting started w/ Vanilla JS
Getting started w/ SolidJS
Getting started w/ Svelte
Getting started w/ TanStack Start
Create Instant App
Recommended Workflow
Using LLMs
Init
Modeling data
Writing data
Reading data
Infinite Queries
Instant on the backend
Patterns
Auth
Magic codes
Guest Auth
Google OAuth
Sign In with Apple
GitHub OAuth
LinkedIn OAuth
Clerk
Firebase Auth
Permissions
Rate Limits
Managing users
Presence, Cursors, and Activity
Instant CLI
Devtool
Platform API
Explorer Component
Custom emails
App teams
Storage
Streams
Stripe Payments
Admin HTTP API
(Experimental) Next.js SSR
Migrating from Supabase