InstantDB

https://www.instantdb.com/docs
Admin
InstantDB is an easy-to-use backend for frontend applications, enabling developers to build...
Tokens:107,559
Snippets:1,102
Trust Score:8.2
Update:2 months ago
Show doc for...
Tokens:
Raw
### Manual Project Setup

Source: https://www.instantdb.com/docs

Commands to initialize a Next.js project and install the required InstantDB dependencies.

```shell
npx create-next-app instant-demo --tailwind --yes
cd instant-demo
npm run dev
```

```shell
npm i @instantdb/react
```

```shell
npx instant-cli init
```

--------------------------------

### Manual project setup commands

Source: https://www.instantdb.com/docs/start-svelte

Commands to initialize a SvelteKit app, install the InstantDB library, and initialize the database configuration.

```shell
npx sv create my-app
```

```shell
npm i @instantdb/svelte
```

```shell
npx instant-cli init
```

--------------------------------

### Manual project initialization

Source: https://www.instantdb.com/docs/start-tanstack

Commands to create a blank TanStack Start app and install the required InstantDB dependency.

```shell
npx @tanstack/cli create my-app
```

```shell
npm i @instantdb/react
```

--------------------------------

### Manual project setup commands

Source: https://www.instantdb.com/docs/start-vue

Commands to initialize a standard Vue project and install the required InstantDB library.

```shell
npm create vue@latest my-app
```

```shell
npm i @instantdb/vue
```

```shell
npx instant-cli init
```

--------------------------------

### Install the Instant Python SDK

Source: https://www.instantdb.com/docs/start-python

Use uv or pip to install the instantdb package.

```shell
uv add instantdb
# or
pip install instantdb
```

--------------------------------

### Initialize Instant CLI

Source: https://www.instantdb.com/docs/platform-api

Command to start the Instant CLI tool.

```bash
npx instant-cli
```

--------------------------------

### Install Platform SDK

Source: https://www.instantdb.com/docs/platform-api

Command to install the Platform SDK for backend server integration.

```bash
npm install @instantdb/platform
```

--------------------------------

### Run the development server

Source: https://www.instantdb.com/docs/create-instant-app

Navigate to the project directory and start the local development server.

```shell
cd instant-demo
npm run dev
```

--------------------------------

### Install InstantDB and dependencies

Source: https://www.instantdb.com/docs/start-rn

Run these commands in your terminal to set up a new Expo project and install the required InstantDB package and its peer dependencies.

```shell
# Create an app with expo
npx create-expo-app instant-rn-demo
cd instant-rn-demo

# Install instant
npm i @instantdb/react-native

# Install peer dependencies
npm i @react-native-async-storage/async-storage @react-native-community/netinfo react-native-get-random-values
```

--------------------------------

### Initialize Next.js Project

Source: https://www.instantdb.com/docs/storage

Sets up a new Next.js project with Tailwind CSS and installs the InstantDB React package.

```shell
npx create-next-app instant-storage --tailwind --yes
cd instant-storage
npm i @instantdb/react
```

--------------------------------

### Schema push output example

Source: https://www.instantdb.com/docs/modeling-data

Example output showing the planning and execution of schema changes, including entity additions and attribute configurations.

```text
Checking for an Instant SDK...
Found [32m@instantdb/react[39m in your package.json.
Found [32mNEXT_PUBLIC_INSTANT_APP_ID[39m: *****
Planning schema...
The following changes will be applied to your production schema:
[35mADD ENTITY[39m profiles.id
[35mADD ENTITY[39m posts.id
[35mADD ENTITY[39m comments.id
[35mADD ENTITY[39m tags.id
[32mADD ATTR[39m profiles.nickname :: unique=false, indexed=false
[32mADD ATTR[39m profiles.createdAt :: unique=false, indexed=false
[32mADD ATTR[39m posts.title :: unique=false, indexed=false
[32mADD ATTR[39m posts.slug :: unique=true, indexed=false
[32mADD ATTR[39m posts.body :: unique=false, indexed=false
[32mADD ATTR[39m posts.createdAt :: unique=false, indexed=true
[32mADD ATTR[39m comments.body :: unique=false, indexed=false
[32mADD ATTR[39m comments.createdAt :: unique=false, indexed=false
[32mADD ATTR[39m tags.title :: unique=false, indexed=false
[32mADD LINK[39m posts.author <=> profiles.authoredPosts
[32mADD LINK[39m comments.post <=> posts.comments
[32mADD LINK[39m comments.author <=> profiles.authoredComments
[32mADD LINK[39m posts.tags <=> tags.posts
[32mADD LINK[39m profiles.$user <=> $users.profile
[2K[34m?[39m [1mOK to proceed?"2 [36myes
[32mSchema updated![39m
```

--------------------------------

### Manually initialize a SolidJS project

Source: https://www.instantdb.com/docs/start-solidjs

Commands to set up a blank Vite SolidJS project and install the necessary InstantDB library.

```shell
npx create-vite@latest -t solid-ts
```

```shell
npm i @instantdb/solidjs
```

```shell
npx instant-cli init
```

--------------------------------

### Install Docker dependencies

Source: https://www.instantdb.com/docs/self-hosting/vps.md

Initial commands to set up the Docker repository keyring and certificates on Ubuntu.

```sh
sudo apt update
sudo apt install -y ca-certificates curl git
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
```

--------------------------------

### Start the development server

Source: https://www.instantdb.com/docs/start-rn

Command to launch the Expo development server.

```shell
npm run start
```

--------------------------------

### Install Google Sign-In Package

Source: https://www.instantdb.com/docs/auth/google-oauth/rn-native

Install the required Google Sign-In package for Expo projects.

```bash
npx expo install @react-native-google-signin/google-signin
```

--------------------------------

### Temporary App Creation Output

Source: https://www.instantdb.com/docs/platform-api

Example JSON response after creating a temporary app.

```json
Successfully created new app!

{
  "app": {
    "appId": "...",
    "adminToken": "..."
  },
  "error": null
}
```

--------------------------------

### Start Instant services

Source: https://www.instantdb.com/docs/self-hosting/vps.md

Command to launch the container stack in detached mode.

```sh
sudo docker compose -f docker-compose.with-caddy.yml --env-file .env up -d
```

--------------------------------

### Firebase Auth Integration Example

Source: https://www.instantdb.com/docs/auth/firebase

A complete React example demonstrating Firebase authentication flow integrated with Instant, including sign-in, sign-up, and session management.

```tsx
'use client';

import { init } from '@instantdb/react';
import { initializeApp } from 'firebase/app';
import {
  getAuth,
  signInWithEmailAndPassword,
  createUserWithEmailAndPassword,
  onAuthStateChanged,
} from 'firebase/auth';
import { useEffect, useState } from 'react';

// Instant app
const APP_ID = '__APP_ID__';

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

// Use the firebase client name you set in the Instant dashboard auth tab
const FIREBASE_CLIENT_NAME = 'REPLACE_ME';

const firebaseConfig = {
  // Use the same Project ID you set in the Instant dashboard auth tab
  projectId: 'REPLACE_ME',
  apiKey: 'REPLACE_ME',
};

const firebaseApp = initializeApp(firebaseConfig);
const firebaseAuth = getAuth(firebaseApp);

function App() {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');

  useEffect(() => {
    const unsubscribe = onAuthStateChanged(firebaseAuth, (user) => {
      if (user) {
        user.getIdToken().then((idToken) => {
          db.auth.signInWithIdToken({
            idToken,
            clientName: FIREBASE_CLIENT_NAME,
          });
        });
      } else {
        db.auth.signOut();
      }
    });
    return () => unsubscribe();
  }, []);

  const handleSignIn = async (e) => {
    e.preventDefault();
    try {
      await signInWithEmailAndPassword(firebaseAuth, email, password);
    } catch (error) {
      console.error('Sign in error:', error);
    }
  };

  const handleSignUp = async (e) => {
    e.preventDefault();
    try {
      await createUserWithEmailAndPassword(firebaseAuth, email, password);
    } catch (error) {
      console.error('Sign up error:', error);
    }
  };

  return (
    <>
      <db.SignedOut>
        <form onSubmit={handleSignIn}>
          <input
            type="email"
            placeholder="Email"
            value={email}
            onChange={(e) => setEmail(e.target.value)}
          />
          <input
            type="password"
            placeholder="Password"
            value={password}
            onChange={(e) => setPassword(e.target.value)}
          />
          <button type="submit">Sign In</button>
          <button type="button" onClick={handleSignUp}>
            Sign Up
          </button>
        </form>
      </db.SignedOut>
      <db.SignedIn>
        <SignedInComponent />
      </db.SignedIn>
    </>
  );
}

function SignedInComponent() {
  const user = db.useUser();

  const handleSignOut = async () => {
    await firebaseAuth.signOut();
  };

  return (
    <div>
      <div>Signed in as {user.email}!</div>
      <button onClick={handleSignOut}>Sign Out</button>
    </div>
  );
}

export default App;
```

--------------------------------

### Define Namespace Permissions

Source: https://www.instantdb.com/docs/permissions

Examples of setting explicit and implicit permission rules for a namespace.

```json
{
  "todos": {
    "allow": {
      "view": "true",
      "create": "true",
      "update": "true",
      "delete": "true"
    }
  }
}
```

```json
{
  "todos": {
    "allow": {
      "view": "true"
    }
  }
}
```

```json
{}
```

--------------------------------

### Initialize a new project with Vite

Source: https://www.instantdb.com/docs/start-vanilla

Use these terminal commands to scaffold a new TypeScript project and install the InstantDB core dependency.

```shell
npx create-vite@latest -t vanilla-ts instant-vanilla
cd instant-vanilla
npm i @instantdb/core
npm run dev
```

--------------------------------

### Platform SDK App Creation Output

Source: https://www.instantdb.com/docs/platform-api

Example console output after creating an app via the Platform SDK.

```bash
app -> {
  app: {
    id: '....',
    adminToken: '...'
    title: 'my-new-app',
    createdAt: '...'
    orgId: null,
  },
  ...
}
```

--------------------------------

### Implement Google Sign-in in React

Source: https://www.instantdb.com/docs/auth/google-oauth/web-google-button

Full example of integrating Google OAuth with InstantDB in a React application.

```javascript
'use client';
 
import React, { useState } from 'react';
import { init } from '@instantdb/react';
import { GoogleOAuthProvider, GoogleLogin } from '@react-oauth/google';
 
const APP_ID = '__APP_ID__';
 
const db = init({ appId: APP_ID });
 
// e.g. 89602129-cuf0j.apps.googleusercontent.com
const GOOGLE_CLIENT_ID = 'REPLACE_ME';
 
// Use the google client name in the Instant dashboard auth tab
const GOOGLE_CLIENT_NAME = 'REPLACE_ME';
 
function App() {
  return (
    <>
      <db.SignedIn>
        <UserInfo />
      </db.SignedIn>
      <db.SignedOut>
        <Login />
      </db.SignedOut>
    </>
  );
}
 
function UserInfo() {
  const user = db.useUser();
  return <h1>Hello {user.email}!</h1>;
}
 
function Login() {
  const [nonce] = useState(crypto.randomUUID());
 
  return (
    <GoogleOAuthProvider clientId={GOOGLE_CLIENT_ID}>
      <GoogleLogin
        nonce={nonce}
        onError={() => alert('Login failed')}
        onSuccess={({ credential }) => {
          db.auth
            .signInWithIdToken({
              clientName: GOOGLE_CLIENT_NAME,
              idToken: credential,
              // Make sure this is the same nonce you passed as a prop
              // to the GoogleLogin button
              nonce,
            })
            .catch((err) => {
              alert('Uh oh: ' + err.body?.message);
            });
        }}
      />
    </GoogleOAuthProvider>
  );
}
```

--------------------------------

### Implement Google Sign-In in React Native

Source: https://www.instantdb.com/docs/auth/google-oauth/rn-native

Full example demonstrating how to configure Google Sign-In and authenticate with InstantDB using an ID token.

```javascript
import { View, Text, Button, StyleSheet } from 'react-native';
import { init } from '@instantdb/react-native';
import {
  GoogleSignin,
  GoogleSigninButton,
} from '@react-native-google-signin/google-signin';
 
const APP_ID = '__APP_ID__';
const db = init({ appId: APP_ID });
 
GoogleSignin.configure({
  // See https://react-native-google-signin.github.io/docs/original#configure
  iosClientId: 'YOUR_IOS_CLIENT_ID',
});
 
function App() {
  return (
    <>
      <db.SignedIn loading={<Text>Loading...</Text>}>
        <UserInfo />
      </db.SignedIn>
      <db.SignedOut>
        <Login />
      </db.SignedOut>
    </>
  );
}
 
function UserInfo() {
  const user = db.useUser();
  return <Text>Hello {user.email}!</Text>;
}
 
function Login() {
  return (
    <GoogleSigninButton
      size={GoogleSigninButton.Size.Wide}
      color={GoogleSigninButton.Color.Dark}
      onPress={async () => {
        // 1. Sign in to Google
        await GoogleSignin.hasPlayServices();
        const userInfo = await GoogleSignin.signIn();
        const idToken = userInfo.data?.idToken;
 
        if (!idToken) {
          console.error('no ID token present!');
          return;
        }
        // 2. Use your token to sign in to InstantDB!
        try {
          const res = await db.auth.signInWithIdToken({
            // The unique name you gave the OAuth client when you
            // registered it on the Instant dashboard
            clientName: 'YOUR_INSTANT_AUTH_CLIENT_NAME',
            idToken,
          });
          console.log('logged in!', res);
        } catch (error) {
          console.log('error signing in', error);
        }
      }}
    />
  );
}
 
const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
});
 
export default App;
```

--------------------------------

### Implement To-Do list component

Source: https://www.instantdb.com/docs/start-solidjs

A complete example of a SolidJS component using InstantDB for querying and performing transactions.

```typescript
import { id, type InstaQLEntity } from "@instantdb/solidjs";
import { createSignal, For, Show, type Component } from "solid-js";
import { db } from "./lib/db";
import type { AppSchema } from "./instant.schema";

type Todo = InstaQLEntity<AppSchema, "todos">;

const App: Component = () => {
  const state = db.useQuery({ todos: {} });
  const todos = () => state().data?.todos ?? [];

  return (
    <Show when={!state().isLoading}>
      <Show
        when={!state().error}
        fallback={
          <div class="text-red-500 p-4">Error: {state().error?.message}</div>
        }
      >
        <div class="p-8 grid-cols-2 items-start gap-2 grid">
          <Welcome />
          <div class="bg-white rounded-lg p-6 border border-neutral-200 shadow flex flex-col">
            <h2 class="tracking-wide text-[#F54A00] text-2xl">Todos</h2>
            <div class="text-xs pb-4">
              Open another tab to see todos update in realtime!
            </div>
            <div class="border rounded border-neutral-300">
              <TodoForm />
              <TodoList todos={todos()} />
              <ActionBar todos={todos()} />
            </div>
          </div>
        </div>
      </Show>
    </Show>
  );
};

function addTodo(text: string) {
  db.transact(
    db.tx.todos[id()].update({
      text,
      done: false,
      createdAt: Date.now(),
    }),
  );
}

function deleteTodo(todo: Todo) {
  db.transact(db.tx.todos[todo.id].delete());
}

function toggleDone(todo: Todo) {
  db.transact(db.tx.todos[todo.id].update({ done: !todo.done }));
}

function deleteCompleted(todos: Todo[]) {
  const completed = todos.filter((todo) => todo.done);
  if (completed.length === 0) return;
  const txs = completed.map((todo) => db.tx.todos[todo.id].delete());
  db.transact(txs);
}

function TodoForm() {
  const [text, setText] = createSignal("");
  return (
    <div class="flex items-center h-10 border-neutral-300">
      <form
        class="flex-1 h-full"
        onSubmit={(e) => {
          e.preventDefault();
          if (!text()) return;
          addTodo(text());
          setText("");
        }}
      >
        <input
          value={text()}
          onInput={(e) => setText(e.currentTarget.value)}
          class="w-full h-full placeholder-neutral-300 px-2 outline-none bg-transparent"
          autofocus
          placeholder="What needs to be done?"
          type="text"
          name="input"
        />
      </form>
    </div>
  );
}
```

--------------------------------

### Implement Web Redirect OAuth Flow

Source: https://www.instantdb.com/docs/auth/google-oauth

Example of using a redirect-based authentication flow with InstantDB.

```jsx
'use client';

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

const APP_ID = '__APP_ID__';

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

const url = db.auth.createAuthorizationURL({
  // Use the google client name in the Instant dashboard auth tab
  clientName: 'REPLACE_ME',
  redirectURL: window.location.href,
});

import React from 'react';

export default function App() {
  return (
    <>
      <db.SignedIn>
        <UserInfo />
      </db.SignedIn>
      <db.SignedOut>
        <Login />
      </db.SignedOut>
    </>
  );
}

function UserInfo() {
  const user = db.useUser();
  return <h1>Hello {user.email}!</h1>;
}

function Login() {
  return <a href={url}>Log in with Google</a>;
}
```

--------------------------------

### Initialize InstantDB in React Native

Source: https://www.instantdb.com/docs/start-rn

A complete example showing schema definition, database initialization, and usage of useQuery and db.transact within a React Native component.

```tsx
import { init, i, InstaQLEntity } from '@instantdb/react-native';
import { View, Text, Button, StyleSheet } from 'react-native';

// Instant app
const APP_ID = '__APP_ID__';

// Optional: You can declare a schema!
const schema = i.schema({
  entities: {
    colors: i.entity({
      value: i.string(),
    }),
  },
});

type Color = InstaQLEntity<typeof schema, 'colors'>;

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

const selectId = '4d39508b-9ee2-48a3-b70d-8192d9c5a059';

function App() {
  const { isLoading, error, data } = db.useQuery({
    colors: {
      $: { where: { id: selectId } },
    },
  });
  if (isLoading) {
    return (
      <View>
        <Text>Loading...</Text>
      </View>
    );
  }
  if (error) {
    return (
      <View>
        <Text>Error: {error.message}</Text>
      </View>
    );
  }

  return <Main color={data.colors[0]} />;
}

function Main(props: { color?: Color }) {
  const { value } = props.color || { value: 'lightgray' };

  return (
    <View style={[styles.container, { backgroundColor: value }]}>
      <View style={[styles.contentSection]}>
        <Text style={styles.header}>Hi! pick your favorite color</Text>
        <View style={styles.spaceX4}>
          {['green', 'blue', 'purple'].map((c) => {
            return (
              <Button
                title={c}
                onPress={() => {
                  db.transact(db.tx.colors[selectId].update({ value: c }));
                }}
                key={c}
              />
            );
          })}
        </View>
      </View>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
  spaceY4: {
    marginVertical: 16,
  },
  spaceX4: {
    flexDirection: 'row',
    justifyContent: 'space-between',
    marginHorizontal: 16,
  },
  contentSection: {
    backgroundColor: 'white',
    opacity: 0.8,
    padding: 12,
    borderRadius: 8,
  },
  header: {
    fontSize: 24,
    fontWeight: 'bold',
    marginBottom: 16,
  },
});

export default App;
```

--------------------------------

### Implement File Storage in React

Source: https://www.instantdb.com/docs/storage

A complete example showing how to initialize the database, upload files with metadata, query the $files namespace for real-time updates, and delete files using transactions.

```javascript
'use client';

import { init, InstaQLEntity } from '@instantdb/react';
import schema, { AppSchema } from '../instant.schema';
import React from 'react';

type InstantFile = InstaQLEntity<AppSchema, '$files'>

const APP_ID = process.env.NEXT_PUBLIC_INSTANT_APP_ID;

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

// `uploadFile` is what we use to do the actual upload!
// The `$files` query will automatically update once the upload is complete
async function uploadImage(file: File) {
  try {
    // Optional metadata you can set for uploads
    const opts = {
      // See: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type
      // Default: 'application/octet-stream'
      contentType: file.type,
      // See: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition
      // Default: 'inline'
      contentDisposition: 'attachment',
    };
    await db.storage.uploadFile(file.name, file, opts);
  } catch (error) {
    console.error('Error uploading image:', error);
  }
}

function App() {
  // $files is the special namespace for querying storage data
  const { isLoading, error, data } = db.useQuery({
    $files: {
      $: {
        order: { serverCreatedAt: 'asc' },
      },
    },
  });

  if (isLoading) {
    return null;
  }

  if (error) {
    return <div>Error fetching data: {error.message}</div>;
  }

  // The result of a $files query will contain objects with
  // metadata and a download URL you can use for serving files!
  const { $files: images } = data
  return (
    <div className="box-border bg-gray-50 font-mono min-h-screen p-5 flex items-center flex-col">
      <div className="tracking-wider text-5xl text-gray-300 mb-8">
        Image Feed
      </div>
      <ImageUpload />
      <div className="text-xs text-center py-4">
        Upload some images and they will appear below! Open another tab and see
        the changes in real-time!
      </div>
      <ImageGrid images={images} />
    </div>
  );
}

interface SelectedFile {
  file: File;
  previewURL: string;
}

function ImageUpload() {
  const [selectedFile, setSelectedFile] = React.useState<SelectedFile | null>(null);
  const [isUploading, setIsUploading] = React.useState(false);
  const fileInputRef = React.useRef<HTMLInputElement>(null);
  const { previewURL } = selectedFile || {};

  const handleFileSelect = (e: React.ChangeEvent<HTMLInputElement>) => {
    const file = e.target.files?.[0];
    if (file) {
      const previewURL = URL.createObjectURL(file);
      setSelectedFile({ file, previewURL });
    }
  };

  const handleUpload = async () => {
    if (selectedFile) {
      setIsUploading(true);

      await uploadImage(selectedFile.file);

      URL.revokeObjectURL(selectedFile.previewURL);
      setSelectedFile(null);
      fileInputRef.current?.value && (fileInputRef.current.value = '');
      setIsUploading(false);
    }
  };

  return (
    <div className="mb-8 p-5 border-2 border-dashed border-gray-300 rounded-lg">
      <input
        ref={fileInputRef}
        type="file"
        accept="image/*"
        onChange={handleFileSelect}
        className="font-mono"
      />
      {isUploading ? (
        <div className="mt-5 flex flex-col items-center">
          <div className="w-8 h-8 border-2 border-t-2 border-gray-200 border-t-green-500 rounded-full animate-spin"></div>
          <p className="mt-2 text-sm text-gray-600">Uploading...</p>
        </div>
      ) : previewURL && (
        <div className="mt-5 flex flex-col items-center gap-3">
          <img src={previewURL} alt="Preview" className="max-w-xs max-h-xs object-contain" />
          <button onClick={handleUpload} className="py-2 px-4 bg-green-500 text-white border-none rounded-sm cursor-pointer font-mono">
            Upload Image
          </button>
        </div>
      )}
    </div>
  );
}

function ImageGrid({ images }: { images: InstantFile[] }) {
  // Use `db.transact` to delete files
  const handleDelete = async (image: InstantFile) => {
    db.transact(db.tx.$files[image.id].delete());
  }

  return (
    <div className="grid grid-cols-1 sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-5 w-full max-w-6xl">
      {images.map((image) => {
        return (
          <div key={image.id} className="border border-gray-300 rounded-lg overflow-hidden">
            <div className="relative">
              {/* $files entities come with a `url` property */}
              <img src={image.url} alt={image.path} className="w-full h-64 object-cover" />
            </div>

            <div className="p-3 flex justify-between items-center bg-white">
              <span>{image.path}</span>
              <span onClick={() => handleDelete(image)} className="cursor-pointer text-gray-300 px-1">
                𝘟
              </span>
            </div>
          </div>
        )
      })}
    </div>
  );
}

export default App;
```

--------------------------------

### Platform Refresh Token Format

Source: https://www.instantdb.com/docs/platform-api

Example of the format for a token obtained via the 'Sign in with Instant' OAuth flow.

```bash
prt_xxx11x1xxx1xx1x11x1x1111xxx1xx11x11xxxx1x1x1x1111xxx11111xxx111x
```

--------------------------------

### Full Apple Authentication Example

Source: https://www.instantdb.com/docs/auth/apple/native

A complete React Native component demonstrating initialization, user state management, and the Apple Sign-In button flow.

```javascript
import React, { useState } from 'react';
import { Button, View, Text, StyleSheet } from 'react-native';
import { init, tx } from '@instantdb/react-native';
import * as AppleAuthentication from 'expo-apple-authentication';
 
const APP_ID = '__APP_ID__';
const db = init({ appId: APP_ID });
 
function App() {
  return (
    <>
      <db.SignedIn>
        <UserInfo />
      </db.SignedIn>
      <db.SignedOut>
        <Login />
      </db.SignedOut>
    </>
  );
}
 
function UserInfo() {
  const user = db.useUser();
  return (
    <View style={styles.container}>
      <Text>Hello {user.email}!</Text>
      <Button
        title="Sign Out"
        onPress={async () => {
          await db.auth.signOut();
        }}
      />
    </View>
  );
}
 
function Login() {
  const [nonce] = useState('' + Math.random());
  return (
    <View style={styles.container}>
      <AppleAuthentication.AppleAuthenticationButton
        buttonType={AppleAuthentication.AppleAuthenticationButtonType.SIGN_IN}
        buttonStyle={AppleAuthentication.AppleAuthenticationButtonStyle.BLACK}
        cornerRadius={5}
        style={styles.button}
        onPress={async () => {
          try {
            const credential = await AppleAuthentication.signInAsync({
              requestedScopes: [
                AppleAuthentication.AppleAuthenticationScope.FULL_NAME,
                AppleAuthentication.AppleAuthenticationScope.EMAIL,
              ],
              nonce: nonce,
            });
            // signed in
            db.auth
              .signInWithIdToken({
                clientName: 'apple',
                idToken: credential.identityToken,
                nonce: nonce,
              })
              .catch((err) => {
                console.log('Error', err.body?.message, err);
              });
          } catch (e) {
            if (e.code === 'ERR_REQUEST_CANCELED') {
              // handle that the user canceled the sign-in flow
            } else {
              // handle other errors
            }
          }
        }}
      />
    </View>
  );
}
 
const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
  button: {
    width: 200,
    height: 44,
  },
});
 
export default App;
```

--------------------------------

### Define DNS hostnames

Source: https://www.instantdb.com/docs/self-hosting/vps.md

Example hostnames to point to the server for dashboard, API, and file storage services.

```text
dash.myinstant.com
api.myinstant.com
files.myinstant.com
```

--------------------------------

### Implement Clerk Authentication in React

Source: https://www.instantdb.com/docs/auth/clerk

Full example demonstrating how to retrieve a Clerk JWT and sign into Instant, including handling sign-out flows for both services.

```javascript
'use client';

import {
  useAuth,
  ClerkProvider,
  SignInButton,
  SignedIn,
  SignedOut,
} from '@clerk/nextjs';
import { init } from '@instantdb/react';
import { useEffect } from 'react';

// Instant app
const APP_ID = '__APP_ID__';

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

// Use the clerk client name you set in the Instant dashboard auth tab
const CLERK_CLIENT_NAME = 'REPLACE_ME';

function ClerkSignedInComponent() {
  const { getToken, signOut } = useAuth();

  const signInToInstantWithClerkToken = async () => {
    // getToken gets the jwt from Clerk for your signed in user.
    const idToken = await getToken();

    if (!idToken) {
      // No jwt, can't sign in to instant
      return;
    }

    // Create a long-lived session with Instant for your clerk user
    // It will look up the user by email or create a new user with
    // the email address in the session token.
    db.auth.signInWithIdToken({
      clientName: CLERK_CLIENT_NAME,
      idToken: idToken,
    });
  };

  useEffect(() => {
    signInToInstantWithClerkToken();
  }, []);

  const { isLoading, user, error } = db.useAuth();

  if (isLoading) {
    return <div>Loading...</div>;
  }
  if (error) {
    return <div>Error signing in to Instant! {error.message}</div>;
  }
  if (user) {
    return (
      <div>
        <p>Signed in with Instant through Clerk!</p>{' '}
        <button
          onClick={() => {
            // First sign out of Instant to clear the Instant session.
            db.auth.signOut().then(() => {
              // Then sign out of Clerk to clear the Clerk session.
              signOut();
            });
          }}
        >
          Sign out
        </button>
      </div>
    );
  }
  return (
    <div>
      <button onClick={signInToInstantWithClerkToken}>
        Sign in to Instant
      </button>
    </div>
  );
}

function App() {
  return (
    <ClerkProvider>
      <SignedOut>
        <SignInButton />
      </SignedOut>
      <SignedIn>
        <ClerkSignedInComponent />
      </SignedIn>
    </ClerkProvider>
  );
}

export default App;
```

--------------------------------

### Initialize Instant Project

Source: https://www.instantdb.com/docs/cli

Sets up a project by generating schema and permission files, with an optional flag for temporary apps.

```shell
npx instant-cli@latest init
```

```shell
npx instant-cli@latest init --temp
```

--------------------------------

### Supabase to InstantDB Migration Prompt

Source: https://www.instantdb.com/docs/migrate-from-supabase

A markdown-formatted prompt designed to guide an AI assistant through the migration process from Supabase to InstantDB.

```markdown
# Supabase to InstantDB Migration

Migrate a Supabase project to InstantDB in a new directory.

**Primary reference**: Fetch `https://www.instantdb.com/llms.txt` for the full
doc index. Use it to find relevant docs for each step below.

## Inputs

Ask the user for source and target directories.

## Process

1. **Setup**: Run `npx instant-cli info` to check login. If not logged in,
   direct the user to https://instantdb.com then `npx instant-cli login`.
   Create app: `npx instant-cli init-without-files --title "<Name>"`

2. **Copy project**: Copy source to target (excluding `node_modules`, `.next`).
   Remove `@supabase/*` deps, add the appropriate `@instantdb/*` SDK.
   Add app ID and admin token to env. Install deps.

3. **Schema**: Create `instant.schema.ts` — profiles merge into `$users`,
   foreign keys become links, join tables become many-to-many links.
   Push: `npx instant-cli push schema --yes`

4. **Permissions**: Create `instant.perms.ts` — translate RLS policies to CEL.
   `auth.uid()` → `auth.id`, ownership checks → `data.ref('link.id')`.
   Push: `npx instant-cli push perms --yes`

5. **Rewrite app**: Server components become client components with `db.useQuery()`.
   Supabase inserts/updates/deletes become `db.transact()`. Auth becomes magic
   codes or OAuth. Remove middleware, proxy, session management. Remove all
   `router.refresh()` — queries are live.

6. **Migrate data**: Ask the user if they have data to migrate. If yes, ask for
   their Supabase service role key. Write and run export + import scripts.
   If the app uses Supabase Storage, migrate files too.

7. **Verify**: Build must pass. Test all pages and auth flows.

8. **Agent rules**: Ask the user if they want to install Instant agent rules:
   `npx skills add instantdb/skills --yes`

## Rules

- Ask one question at a time — don't batch user prompts
- Fetch docs just-in-time from `llms.txt` index, not all at once
- `$files` permissions default to all false — must enable explicitly
```

--------------------------------

### Initialize InstantDB project

Source: https://www.instantdb.com/docs/start-tanstack

Run the instant-cli to set up schema, permissions, and environment variables.

```shell
npx instant-cli init
```

--------------------------------

### Install expo-sqlite dependencies

Source: https://www.instantdb.com/docs/start-rn

Install the expo-sqlite package and its peer dependency.

```shell
npm i @instantdb/expo-sqlite

# Install the expo-sqlite peer dependency
npx expo install expo-sqlite
```

--------------------------------

### Implement Guest Authentication in React

Source: https://www.instantdb.com/docs/auth/guest-auth

A complete React component example demonstrating guest sign-in, sign-out, and conditional rendering based on user authentication status.

```tsx
'use client';

import React, { useState } from 'react';
import { init, User } from '@instantdb/react';

// Instant app
const APP_ID = '__APP_ID__';
const db = init({ appId: APP_ID });

function App() {
  return (
    <>
      <db.SignedIn>
        <Main />
      </db.SignedIn>
      <db.SignedOut>
        <Login />
      </db.SignedOut>
    </>
  );
}

function Main() {
  const user = db.useUser();
  return (
    <div className="space-y-4 p-4">
      <h1 className="text-2xl font-bold">
        Hello {user.isGuest ? 'Guest' : user.email}!
      </h1>
      <button
        onClick={() => db.auth.signOut()}
        className="bg-blue-600 px-3 py-1 font-bold text-white hover:bg-blue-700"
      >
        Sign out
      </button>
    </div>
  );
}

function Login() {
  return (
    <div className="flex min-h-screen items-center justify-center">
      <div className="max-w-sm">
        <button
          onClick={() => db.auth.signInAsGuest()}
          className="w-full bg-blue-600 px-3 py-1 font-bold text-white hover:bg-blue-700"
        >
          Sign in as Guest
        </button>
      </div>
    </div>
  );
}

export default App;
```

--------------------------------

### Install MMKV dependencies

Source: https://www.instantdb.com/docs/start-rn

Install the required MMKV package and its peer dependencies.

```shell
npm i @instantdb/react-native-mmkv

# Install MMKV peer dependencies
npx expo install react-native-mmkv react-native-nitro-modules
```

--------------------------------

### Implement GitHub Login with Expo AuthSession

Source: https://www.instantdb.com/docs/auth/github-oauth/rn-web

A complete example demonstrating how to use InstantDB and Expo AuthSession to manage user authentication states and perform the OAuth exchange.

```javascript
import { View, Text, Button } from 'react-native';
import { init } from '@instantdb/react-native';
import {
  makeRedirectUri,
  useAuthRequest,
  useAutoDiscovery,
} from 'expo-auth-session';
 
const APP_ID = '__APP_ID__';
const db = init({ appId: APP_ID });
 
function App() {
  return (
    <>
      <db.SignedIn>
        <UserInfo />
      </db.SignedIn>
      <db.SignedOut>
        <Login />
      </db.SignedOut>
    </>
  );
}
 
function UserInfo() {
  const user = db.useUser();
  return (
    <View>
      <Text>Hello {user.email}!</Text>
      <Button title="Log out" onPress={() => db.auth.signOut()}></Button>
    </View>
  );
}
 
function Login() {
  const discovery = useAutoDiscovery(db.auth.issuerURI());
 
  const [request, _response, promptAsync] = useAuthRequest(
    {
      // The unique name you gave the OAuth client when you
      // registered it on the Instant dashboard
      clientId: 'github-web',
      redirectUri: makeRedirectUri(),
    },
    discovery,
  );
 
  return (
    <Button
      title="Log in with GitHub"
      disabled={!request}
      onPress={async () => {
        try {
          const res = await promptAsync();
          if (res.type === 'success') {
            await db.auth.exchangeOAuthCode({
              code: res.params.code,
              codeVerifier: request?.codeVerifier,
            });
          }
        } catch (e) {
          console.error(e);
        }
      }}
    />
  );
}
 
export default App;
```

--------------------------------

### Scaffold a new Instant project

Source: https://www.instantdb.com/docs/start-python

Initialize a new project with the required configuration files.

```shell
npx create-instant-app --python my-app
cd my-app
uv sync
```

--------------------------------

### Scaffold InstantDB Projects

Source: https://www.instantdb.com/docs

Use the CLI to quickly initialize new projects with pre-configured InstantDB settings.

```bash
npx create-instant-app --next
```

```bash
npx create-instant-app --vite-react
```

--------------------------------

### Install Apple Authentication Dependency

Source: https://www.instantdb.com/docs/auth/apple/native

Install the required expo-apple-authentication package via npm.

```bash
npx expo install expo-apple-authentication
```

--------------------------------

### Install Expo AuthSession Dependencies

Source: https://www.instantdb.com/docs/auth/github-oauth/rn-web

Install the necessary Expo packages to handle authentication sessions and cryptographic operations.

```bash
npx expo install expo-auth-session expo-crypto
```

--------------------------------

### Initialize Instant CLI

Source: https://www.instantdb.com/docs/modeling-data

Run this command to generate the initial schema and permissions files for your project.

```shell
npx instant-cli@latest init
```

--------------------------------

### Install React Google OAuth Package

Source: https://www.instantdb.com/docs/auth/google-oauth/web-google-button

Install the required dependency for using Google Sign-in buttons in React.

```bash
npm install @react-oauth/google
```

--------------------------------

### Initialize project with self-hosted backend

Source: https://www.instantdb.com/docs/self-hosting

Use the CLI to create a new app configured for your self-hosted backend URL.

```shell
INSTANT_CLI_API_URI=https://api.myinstant.com npx create-instant-app@latest
```

--------------------------------

### Scaffold a new Instant project

Source: https://www.instantdb.com/docs/start-solidjs

Use the CLI to quickly initialize a new SolidJS project with InstantDB pre-configured.

```shell
npx create-instant-app -b solidjs-vite
```

--------------------------------

### Create GET Handler for Stream Resumption

Source: https://www.instantdb.com/docs/streams

Implement the GET handler to resume an existing stream using the active stream ID stored in the chat.

```ts
// app/api/chat/[id]/stream/route.ts
import { readChat } from '@util/chat-store';
import { UI_MESSAGE_STREAM_HEADERS } from 'ai';
import { after } from 'next/server';
import { createResumableStreamContext } from '@instantdb/resumable-stream';

export async function GET(
  _: Request,
  { params }: { params: Promise<{ id: string }> },
) {
  const { id } = await params;

  const chat = await readChat(id);

  if (chat.activeStreamId == null) {
    // no content response when there is no active stream
    return new Response(null, { status: 204 });
  }

  const streamContext = createResumableStreamContext({
    waitUntil: after,
    appId: process.env.INSTANT_APP_ID,
    adminToken: process.env.INSTANT_APP_ADMIN_TOKEN,
  });

  return new Response(
    await streamContext.resumeExistingStream(chat.activeStreamId),
    { headers: UI_MESSAGE_STREAM_HEADERS },
  );
}
```

--------------------------------

### Scaffold a new Instant project

Source: https://www.instantdb.com/docs/start-svelte

Use the CLI tool to automatically set up a new SvelteKit project with InstantDB pre-configured.

```shell
npx create-instant-app --sv
```

--------------------------------

### GET /admin/users

Source: https://www.instantdb.com/docs/http-api.md

Fetch an app user by email, id, or refresh_token.

```APIDOC
## GET /admin/users

### Description
Fetch an app user by email, id, or refresh_token.

### Method
GET

### Endpoint
/admin/users

### Parameters
#### Query Parameters
- **email** (string) - Optional - The email of the user.
- **id** (string) - Optional - The unique identifier of the user.
- **refresh_token** (string) - Optional - The refresh token of the user.
```

--------------------------------

### init

Source: https://www.instantdb.com/docs/backend

Initializes the Instant Admin SDK instance with an app ID and admin token.

```APIDOC
## init

### Description
Initializes the Instant Admin SDK instance. This must be called before performing any queries or transactions.

### Parameters
- **appId** (string) - Required - The unique identifier for your Instant app.
- **adminToken** (string) - Required - The administrative token used for authentication. Should be kept secure.
```

--------------------------------

### Initialize App via CLI

Source: https://www.instantdb.com/docs/platform-api

Command to initialize a new long-lived application using the Instant CLI.

```bash
npx instant-cli init-without-files --title my-long-lived-app --token YOUR_TOKEN
```

--------------------------------

### Use custom update function

Source: https://www.instantdb.com/docs/instaml

Example usage of a custom update wrapper.

```typescript
// Goal
myCustomUpdate('todos', { dueDate: Date.now() });
```

--------------------------------

### Initialize InstantDB project

Source: https://www.instantdb.com/docs/streams

Command to scaffold a new project using the AI chat template.

```sh
npx create-instant-app@latest --base ai-chat
```

--------------------------------

### Push Configuration to Instant

Source: https://www.instantdb.com/docs/storage

Deploys the local schema and permission rules to the Instant backend.

```shell
npx instant-cli@latest push
```

--------------------------------

### Define Data Model Schema

Source: https://www.instantdb.com/docs/permissions

Example structure for a goals namespace definition.

```json
{
  "goals": { "id": UUID, "title": string }
}
```

--------------------------------

### Example JSON Output

Source: https://www.instantdb.com/docs/cli

The structure of the JSON output returned by the init-without-files command.

```json
{
  "app": {
    "appId": "4f1e575c-6c00-44dd-bc69-004e89b9d788",
    "adminToken": "67ce37cb-aa47-468d-9c54-99efcf40497f"
  },
  "error": null
}
```

--------------------------------

### init

Source: https://www.instantdb.com/docs/backend

Initializes the InstantDB instance with configuration and optional schema.

```APIDOC
## init

### Description
Initializes the InstantDB client for backend use with an app ID, admin token, and optional schema.

### Signature
`init({ appId, adminToken, schema })`

### Parameters
- **appId** (string) - Required - The unique identifier for the app.
- **adminToken** (string) - Required - The admin token for authentication.
- **schema** (object) - Optional - The schema definition for type safety and autocompletion.
```

--------------------------------

### init(options)

Source: https://www.instantdb.com/docs/init

Initializes the InstantDB client instance. This function should be called to establish a connection to your InstantDB application.

```APIDOC
## init(options)

### Description
Initializes the InstantDB client. This function establishes a connection to the backend and returns a database instance used for queries, mutations, and authentication.

### Parameters
- **appId** (string) - Required - Your InstantDB application ID.
- **schema** (object) - Optional - The schema definition for typesafety and auto-completion.
- **websocketURI** (string) - Optional - Custom WebSocket endpoint for real-time connections.
- **apiURI** (string) - Optional - Custom HTTP API endpoint for auth and storage operations.
- **devtool** (boolean|object) - Optional - Configuration for the Instant dev tool.
- **verbose** (boolean) - Optional - Enables detailed console logging.
- **logger** (object) - Optional - Custom logger object with debug, info, and error methods.
- **queryCacheLimit** (number) - Optional - Maximum number of query subscriptions to cache for offline mode.
- **useDateObjects** (boolean) - Optional - Whether to return date columns as JavaScript Date objects.

### Request Example
```javascript
import { init } from '@instantdb/react';

const db = init({
  appId: '__APP_ID__',
  verbose: true
});
```
```

--------------------------------

### Clone and prepare environment

Source: https://www.instantdb.com/docs/self-hosting/vps.md

Commands to clone the repository and initialize the environment configuration file.

```sh
git clone https://github.com/instantdb/instant.git
cd instant/self-hosting
cp .env.example .env
nano .env
```

--------------------------------

### Initialize App Without Files

Source: https://www.instantdb.com/docs/cli

Creates an Instant app without generating schema or permission files, outputting credentials as JSON.

```shell
npx instant-cli@latest init-without-files --title "Hello World"
```

--------------------------------

### GET /admin/rooms/presence

Source: https://www.instantdb.com/docs/http-api.md

Query for the data currently in a room, useful for checking if a user is online.

```APIDOC
## GET /admin/rooms/presence

### Description
Query for the data currently in a room. This is useful for checking if a user is online.

### Method
GET

### Endpoint
/admin/rooms/presence

### Parameters
#### Query Parameters
- **room-type** (string) - Required - The type of the room.
- **room-id** (string) - Required - The unique identifier of the room.
```
Tokens:
Raw