# Common mistakes

Common mistakes when working with Instant

Below are some common mistakes when working with Instant.

## Common mistakes with schema

❌ **Common mistake**: Reusing the same label for different links

```
// ❌ Bad: Conflicting labels
const _schema = i.schema({
  links: {
    postAuthor: {
      forward: { on: 'posts', has: 'one', label: 'author' },
      reverse: { on: 'profiles', has: 'many', label: 'posts' }, // Creates 'posts' attr
    },
    postEditor: {
      forward: { on: 'posts', has: 'one', label: 'editor' },
      reverse: { on: 'profiles', has: 'many', label: 'posts' }, // Conflicts!
    },
  },
});
```

✅ **Correction**: Use unique labels for each relationship

```
// ✅ Good: Unique labels for each relationship
const _schema = i.schema({
  links: {
    postAuthor: {
      forward: { on: 'posts', has: 'one', label: 'author' },
      reverse: { on: 'profiles', has: 'many', label: 'authoredPosts' }, // Unique
    },
    postEditor: {
      forward: { on: 'posts', has: 'one', label: 'editor' },
      reverse: { on: 'profiles', has: 'many', label: 'editedPosts' }, // Unique
    },
  },
});
```

## Common mistakes with permissions

Sometimes you want to express permissions based on an attribute in a linked entity. For those instances you can use `data.ref`.

❌ **Common mistake**: Not using `data.ref` to reference linked data

```
// ❌ Bad: This will throw an error!
{
  "comments": {
    "allow": {
      "update": "auth.id in data.post.author.id"
    }
  }
}
```

```
// ✅ Good: Permission based on linked data
{
  "comments": {
    "allow": {
      "update": "auth.id in data.ref('post.author.id')"  // Allow post authors to update comments
    }
  }
}
```

When using `data.ref` the last part of the string is the attribute you want to access. If you do not specify an attribute an error will occur.

❌ **Common mistake**: Not specifying an attribute when using data.ref

```
// ❌ Bad: No attribute specified. This will throw an error!
"view": "auth.id in data.ref('author')"
```

✅ **Correction**: Specify the attribute you want to access

```
// ✅ Good: Correctly using data.ref to reference a linked attribute
"view": "auth.id in data.ref('author.id')"
```

`data.ref` will _ALWAYS_ return a CEL list of linked entities. So we must use the `in` operator to check if a value exists in that list.

❌ **Common mistake**: Using `==` to check if a value exists in a list

```
// ❌ Bad: data.ref returns a list! This will throw an error!
"view": "data.ref('admins.id') == auth.id"
```

✅ **Correction**: Use `in` to check if a value exists in a list

```
✅ Good: Checking if a user is in a list of admins
"view": "auth.id in data.ref('admins.id')"
```

Even if you are referencing a one-to-one relationship, `data.ref` will still return a CEL list. You must extract the first element from the list to compare it properly.

❌ **Common mistake**: Using `==` to check if a value matches in a one-to-one relationship

```
// ❌ Bad: data.ref always returns a CEL list. This will throw an error!
"view": "auth.id == data.ref('owner.id')"
```

✅ **Correction**: Use `in` to check a value even for one-to-one relationships

```
// ✅ Good: Extracting the first element from a one-to-one relationship
"view": "auth.id in data.ref('owner.id')"
```

Be careful when checking whether there are no linked entities. Here are a few correct ways to do this:

❌ **Common mistake**: Incorrectly checking for an empty list

```
// ❌ Bad: `data.ref` returns a CEL list so checking against null will throw an error!
"view": "data.ref('owner.id') != null"

// ❌ Bad: `data.ref` is a CEL list and does not support `length`
"view": "data.ref('owner.id').length > 0"

// ❌ Bad: You must specify an attribute when using `data.ref`
"view": "data.ref('owner') != []"
```

✅ **Correction**: Best way to check for an empty list

```
// ✅ Good: Checking if the list is empty
"view": "data.ref('owner.id') != []"
```

Use `auth.ref` to reference the authenticated user's linked data. This behaves similar to `data.ref` but you _MUST_ use the `$user` prefix when referencing auth data:

❌ **Common mistake**: Missing `$user` prefix with `auth.ref`

```
// ❌ Bad: This will throw an error!
{
  "adminActions": {
    "allow": {
      "create": "'admin' in auth.ref('role.type')"
    }
  }
}
```

✅ **Correction**: Use `$user` prefix with `auth.ref`

```
// ✅ Good: Checking user roles
{
  "adminActions": {
    "allow": {
      "create": "'admin' in auth.ref('$user.role.type')"  // Allow admins only
    }
  }
}
```

`auth.ref` returns a CEL list, so use `[0]` to extract the first element when needed.

❌ **Common mistake**: Using `==` to check if auth.ref matches a value

```
// ❌ Bad: auth.ref returns a list! This will throw an error!
"create": "auth.ref('$user.role.type') == 'admin'"
```

✅ **Correction**: Extract the first element from `auth.ref`

```
// ✅ Good: Extracting the first element from auth.ref
"create": "auth.ref('$user.role.type')[0] == 'admin'"
```

For update operations, you can compare the existing (`data`) and updated (`newData`) values.

One difference between `data.ref` and `newData.ref` is that `newData.ref` does not exist. You can only use `newData` to reference the updated attributes directly.

❌ **Common mistake**: `newData.ref` does not exist.

```
// ❌ Bad: This will throw an error!
// This will throw an error because newData.ref does not exist
{
  "posts": {
    "allow": {
      "update": "auth.id == data.authorId && newData.ref('isPublished') == data.ref('isPublished')"
    }
  }
}
```

❌ **Common mistake**: ref arguments must be string literals

```
// ❌ Bad: This will throw an error!
"view": "auth.id in data.ref(someVariable + '.members.id')"
```

✅ **Correction**: Only string literals are allowed

```
// ✅ Good: Using string literals for ref arguments
"view": "auth.id in data.ref('team.members.id')"
```

## Common mistakes with transactions

Use `merge` for updating nested objects without overwriting unspecified fields:

❌ **Common mistake**: Using `update` for nested objects

```typescript
// ❌ Bad: This will overwrite the entire preferences object
db.transact(
  db.tx.profiles[userId].update({
    preferences: { theme: 'dark' }, // Any other preferences will be lost
  }),
);
```

✅ **Correction**: Use `merge` to update nested objects

```
// ✅ Good: Update nested values without losing other data
db.transact(db.tx.profiles[userId].merge({
  preferences: {
    theme: "dark"
  }
}));
```

You can use `merge` to remove keys from nested objects by setting the key to `null`:

❌ **Common mistake**: Calling `update` instead of `merge` for removing keys

```
// ❌ Bad: Calling `update` will overwrite the entire preferences object
db.transact(db.tx.profiles[userId].update({
  preferences: {
    notifications: null
  }
}));
```

✅ **Correction**: Use `merge` to remove keys from nested objects

```
// ✅ Good: Remove a nested key
db.transact(db.tx.profiles[userId].merge({
  preferences: {
    notifications: null  // This will remove the notifications key
  }
}));
```

Large transactions can lead to timeouts. To avoid this, break them into smaller batches:

❌ **Common mistake**: Not batching large transactions leads to timeouts

```typescript
import { id } from '@instantdb/react';

const txs = [];
for (let i = 0; i < 1000; i++) {
  txs.push(
    db.tx.todos[id()].update({
      text: `Todo ${i}`,
      done: false,
    }),
  );
}

// ❌ Bad: This will likely lead to a timeout!
await db.transact(txs);
```

❌ **Common mistake**: Creating too many transactions will also lead to timeouts

```typescript
import { id } from '@instantdb/react';

// ❌ Bad: This will fire 1000 transactions at once and will lead to multiple
// timeouts!
for (let i = 0; i < 1000; i++) {
  db.transact(
    db.tx.todos[id()].update({
      text: `Todo ${i}`,
      done: false,
    }),
  );
}

await db.transact(txs);
```

✅ **Correction**: Batch large transactions into smaller ones

```
// ✅ Good: Batch large operations
import { id } from '@instantdb/react';

const batchSize = 100;
const createManyTodos = async (count) => {
  for (let i = 0; i < count; i += batchSize) {
    const batch = [];

    // Create up to batchSize transactions
    for (let j = 0; j < batchSize && i + j < count; j++) {
      batch.push(
        db.tx.todos[id()].update({
          text: `Todo ${i + j}`,
          done: false
        })
      );
    }

    // Execute this batch
    await db.transact(batch);
  }
};

// Create 1000 todos in batches
createManyTodos(1000);
```

## Common mistakes with queries

Nest namespaces to fetch associated entities:

❌ **Common mistake**: Not nesting namespaces will fetch unrelated entities

```
// ❌ Bad: This will fetch all todos and all goals instead of todos associated with their goals
const query = { goals: {}, todos: {} };
```

✅ **Correction**: Nest namespaces to fetch associated entities

```
// ✅ Good: Fetch goals and their associated todos
const query = { goals: { todos: {} } };
```

Use `where` operator to filter entities:

❌ **Common mistake**: Placing `where` at the wrong level

```typescript
// ❌ Bad: Filter must be inside $
const query = {
  goals: {
    where: { id: 'goal-1' },
  },
};
```

✅ **Correction**: Place `where` inside the `$` operator

```typescript
// ✅ Good: Fetch a specific goal by ID
const query = {
  goals: {
    $: {
      where: {
        id: 'goal-1',
      },
    },
  },
};
```

`where` operators support filtering entities based on associated values

❌ **Common mistake**: Incorrect syntax for filtering on associated values

```
// ❌ Bad: This will return an error!
const query = {
  goals: {
    $: {
      where: {
        todos: { title: 'Go running' }, // Wrong: use dot notation instead
      },
    },
  },
};
```

✅ **Correction**: Use dot notation to filter on associated values

```
// ✅ Good: Find goals that have todos with a specific title
const query = {
  goals: {
    $: {
      where: {
        'todos.title': 'Go running',
      },
    },
    todos: {},
  },
};
```

Use `or` inside of `where` to filter entities based on any criteria.

❌ **Common mistake**: Incorrect syntax for `or` and `and`

```typescript
// ❌ Bad: This will return an error!
const query = {
  todos: {
    $: {
      where: {
        or: { priority: 'high', dueDate: { $lt: tomorrow } }, // Wrong: 'or' takes an array
      },
    },
  },
};
```

✅ **Correction**: Use an array for `or` and `and` operators

```typescript
// ✅ Good: Find todos that are either high priority OR due soon
const query = {
  todos: {
    $: {
      where: {
        or: [{ priority: 'high' }, { dueDate: { $lt: tomorrow } }],
      },
    },
  },
};
```

Using `$gt`, `$lt`, `$gte`, or `$lte` is supported on indexed attributes with checked types:

❌ **Common mistake**: Using comparison on non-indexed attributes

```typescript
// ❌ Bad: Attribute must be indexed for comparison operators
const query = {
  todos: {
    $: {
      where: {
        nonIndexedAttr: { $gt: 5 }, // Will fail if attr isn't indexed
      },
    },
  },
};
```

✅ **Correction**: Use comparison operators on indexed attributes

```typescript
// ✅ Good: Find todos that take more than 2 hours
const query = {
  todos: {
    $: {
      where: {
        timeEstimate: { $gt: 2 },
      },
    },
  },
};

// Available operators: $gt, $lt, $gte, $lte
```

Use `limit` and/or `offset` for simple pagination:

❌ **Common mistake**: Using limit in nested namespaces

```typescript
// ❌ Bad: Limit only works on top-level namespaces. This will return an error!
const query = {
  goals: {
    todos: {
      $: { limit: 5 }, // This won't work
    },
  },
};
```

✅ **Correction**: Use limit on top-level namespaces

```typescript
// ✅ Good: Get first 10 todos
const query = {
  todos: {
    $: {
      limit: 10,
    },
  },
};

// ✅ Good: Get next 10 todos
const query = {
  todos: {
    $: {
      limit: 10,
      offset: 10,
    },
  },
};
```

Use the `order` operator to sort results

❌ **Common mistake**: Using `orderBy` instead of `order`

```typescript
// ❌ Bad: `orderBy` is not a valid operator. This will return an error!
const query = {
  todos: {
    $: {
      orderBy: {
        serverCreatedAt: 'desc',
      },
    },
  },
};
```

✅ **Correction**: Use `order` to sort results

```typescript
// ✅ Good: Sort by creation time in descending order
const query = {
  todos: {
    $: {
      order: {
        serverCreatedAt: 'desc',
      },
    },
  },
};
```

❌ **Common mistake**: Ordering non-indexed fields

```typescript
// ❌ Bad: Field must be indexed for ordering
const query = {
  todos: {
    $: {
      order: {
        nonIndexedField: 'desc', // Will fail if field isn't indexed
      },
    },
  },
};
```

## Common mistakes with Instant on the backend

Use `db.query` in the admin SDK instead of `db.useQuery`. It is an async API without loading states. We wrap queries in try catch blocks to handle errors. Unlike the client SDK, queries in the admin SDK bypass permission checks

❌ **Common mistake**: Using `db.useQuery` in the admin SDK

```javascript
// ❌ Bad: Don't use useQuery on the server
const { data, isLoading, error } = db.useQuery({ todos: {} }); // Wrong approach!
```

✅ **Correction**: Use `db.query` in the admin SDK

```javascript
// ✅ Good: Server-side querying
const fetchTodos = async () => {
  try {
    const data = await db.query({ todos: {} });
    const { todos } = data;
    console.log(`Found ${todos.length} todos`);
    return todos;
  } catch (error) {
    console.error('Error fetching todos:', error);
    throw error;
  }
};
```

## Common mistakes with auth

InstantDB does not provide built-in username/password authentication.

❌ **Common mistake**: Using password-based authentication in client-side code

✅ **Correction**: Use Instant's magic code or OAuth flows instead in client-side code

If you need traditional password-based authentication, you must implement it as a custom auth flow using the Admin SDK.


# Getting started

How to use Instant with React

Instant is the easy to use backend for your frontend. With Instant you can build delightful apps in less than 10 minutes. Follow the quick start below to **build a live app!**

## Automatic Setup With Create Instant App

The fastest way to get started with Instant is to use `npx create-instant-app` to scaffold a new project with Instant already set up.

To get started with Next.JS run:

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

## Manual Setup

To create a new Next project, fire up your terminal and run the following:

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

Add the InstantDB React Library:

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

Setup and connect your Instant app.
This will log you in if you are not logged in already, then create a schema and permissions file, and update your `.env` file.

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

Create a database client in `src/lib/db.ts`:



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

export const db = init({
  appId: process.env.NEXT_PUBLIC_INSTANT_APP_ID!,
  schema,
  useDateObjects: true,
});
```

You're now ready to make queries and transactions to your database!

### Creating a To-Do List App

Let's add a "todo" entity to our schema file at `src/instant.schema.ts`:



```ts 
import { i } from '@instantdb/react';

const _schema = i.schema({
  entities: {
    $files: i.entity({
      path: i.string().unique().indexed(),
      url: i.string(),
    }),
    $users: i.entity({
      email: i.string().unique().indexed().optional(),
      imageURL: i.string().optional(),
      type: i.string().optional(),
    }),
    todos: i.entity({
      text: i.string(),
      done: i.boolean(),
      createdAt: i.date(),
    }),
  },
  links: {
    $usersLinkedPrimaryUser: {
      forward: {
        on: '$users',
        has: 'one',
        label: 'linkedPrimaryUser',
        onDelete: 'cascade',
      },
      reverse: {
        on: '$users',
        has: 'many',
        label: 'linkedGuestUsers',
      },
    },
  },
  rooms: {},
});

//...
```

Push the schema:

```shell 
npx instant-cli push
```

Replace the content of `src/app/page.tsx` with the following:



```typescript 
"use client";

import schema from "@/instant.schema";
import { db } from "@/lib/db";
import { id, i, init, InstaQLEntity } from "@instantdb/react";

type Todo = InstaQLEntity<typeof schema, "todos", {}, undefined, true>;

function App() {
  // Read Data
  const { isLoading, error, data } = db.useQuery({ todos: {} });
  if (isLoading) {
    return;
  }
  if (error) {
    return <div className="text-red-500 p-4">Error: {error.message}</div>;
  }
  const { todos } = data;
  return (
    <div className="font-mono min-h-screen flex justify-center items-center flex-col space-y-4">
      <h2 className="tracking-wide text-5xl text-gray-300">todos</h2>
      <div className="border border-gray-300 max-w-xs w-full">
        <TodoForm todos={todos} />
        <TodoList todos={todos} />
        <ActionBar todos={todos} />
      </div>
      <div className="text-xs text-center">
        Open another tab to see todos update in realtime!
      </div>
    </div>
  );
}

// Write Data
// ---------
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);
  const txs = completed.map((todo) => db.tx.todos[todo.id].delete());
  db.transact(txs);
}

function toggleAll(todos: Todo[]) {
  const newVal = !todos.every((todo) => todo.done);
  db.transact(
    todos.map((todo) => db.tx.todos[todo.id].update({ done: newVal })),
  );
}

// Components
// ----------
function ChevronDownIcon() {
  return (
    <svg viewBox="0 0 20 20">
      <path
        d="M5 8 L10 13 L15 8"
        stroke="currentColor"
        fill="none"
        strokeWidth="2"
      />
    </svg>
  );
}

function TodoForm({ todos }: { todos: Todo[] }) {
  return (
    <div className="flex items-center h-10 border-b border-gray-300">
      <button
        className="h-full px-2 border-r border-gray-300 flex items-center justify-center"
        onClick={() => toggleAll(todos)}
      >
        <div className="w-5 h-5">
          <ChevronDownIcon />
        </div>
      </button>
      <form
        className="flex-1 h-full"
        onSubmit={(e) => {
          e.preventDefault();
          const input = e.currentTarget.input as HTMLInputElement;
          addTodo(input.value);
          input.value = "";
        }}
      >
        <input
          className="w-full h-full px-2 outline-hidden bg-transparent"
          autoFocus
          placeholder="What needs to be done?"
          type="text"
          name="input"
        />
      </form>
    </div>
  );
}

function TodoList({ todos }: { todos: Todo[] }) {
  return (
    <div className="divide-y divide-gray-300">
      {todos.map((todo) => (
        <div key={todo.id} className="flex items-center h-10">
          <div className="h-full px-2 flex items-center justify-center">
            <div className="w-5 h-5 flex items-center justify-center">
              <input
                type="checkbox"
                className="cursor-pointer"
                checked={todo.done}
                onChange={() => toggleDone(todo)}
              />
            </div>
          </div>
          <div className="flex-1 px-2 overflow-hidden flex items-center">
            {todo.done ? (
              <span className="line-through">{todo.text}</span>
            ) : (
              <span>{todo.text}</span>
            )}
          </div>
          <button
            className="h-full px-2 flex items-center justify-center text-gray-300 hover:text-gray-500"
            onClick={() => deleteTodo(todo)}
          >
            X
          </button>
        </div>
      ))}
    </div>
  );
}

function ActionBar({ todos }: { todos: Todo[] }) {
  return (
    <div className="flex justify-between items-center h-10 px-2 text-xs border-t border-gray-300">
      <div>Remaining todos: {todos.filter((todo) => !todo.done).length}</div>
      <button
        className=" text-gray-300 hover:text-gray-500"
        onClick={() => deleteCompleted(todos)}
      >
        Delete Completed
      </button>
    </div>
  );
}

export default App;
```

Go to `localhost:3000`, and huzzah 🎉 You've got a fully functional todo list running!

## Next Steps

Want to dive deeper on how this todo app works? Check out our step-by-step [Todo List Tutorial](/examples/todos). In this tutorial we walk through how to build the above todo list app from scratch, and explain how the queries and transactions work in more detail.

You can also check out the [Working with data](/docs/init) section to learn more Instant concepts.

As you get more familiar with Instant, check out our [Recommended Workflow](/docs/recommended-workflow) docs for using Instant in your projects.


# Getting started with React Native

How to use Instant with React Native

You can use Instant in React Native projects too! Below is an example using Expo.

Open up your terminal and do the following:

```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
```

Now open up `app/(tabs)/index.tsx` in your favorite editor and replace the entirety of the file with the following code.

```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;
```

If you haven't already, install the Expo Go app on iOS or Android. Once you have that installed you can run the app from your terminal.

```
npm run start
```

Scan the QR code with your phone and follow the instructions on the screen :)

Huzzah 🎉 You've got your first React Native Instant app running! Check out the [Working with data](/docs/init) section to learn more about how to use Instant!

## Using MMKV for faster storage (optional)

By default, Instant uses [AsyncStorage](https://react-native-async-storage.github.io/async-storage/) to persist data on device. If you want faster read/write performance, you can use [MMKV](https://github.com/mrousavy/react-native-mmkv) instead.

### Install the MMKV package

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

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

Note: MMKV requires native code, so you'll need to run a prebuild:

```shell 
npx expo prebuild
```

### Configure Instant to use MMKV

Import `Store` from `@instantdb/react-native-mmkv` and pass it to `init`:

```tsx 
import { init } from '@instantdb/react-native';
import Store from '@instantdb/react-native-mmkv';

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

Then run your app on a device or simulator:

```shell 
npx expo run:ios # or npx expo run:android
```

That's it! Instant will now use MMKV for local persistence instead of AsyncStorage.

### Implementing your own store

You can also implement your own local cache interface by extending `StoreInterface` from `@instantdb/react-native`. Here's an example in-memory store implementation:

```tsx 
import {
  StoreInterface,
  StoreInterfaceStoreName,
} from '@instantdb/react-native';

class InMemoryStore extends StoreInterface {
  _map: Map<string, any>;

  constructor(appId: string, storeName: StoreInterfaceStoreName) {
    super(appId, storeName);
    this._map = new Map();
  }

  async getItem(key: string): Promise<any> {
    return this._map.get(key) ?? null;
  }

  async multiSet(keyValuePairs: Array<[string, any]>): Promise<void> {
    for (const [key, value] of keyValuePairs) {
      this._map.set(key, value);
    }
  }

  async removeItem(key: string): Promise<void> {
    this._map.delete(key);
  }

  async getAllKeys(): Promise<string[]> {
    return Array.from(this._map.keys());
  }
}
```

Then pass your custom store class to `init`:

```tsx 
import { init } from '@instantdb/react-native';

const db = init({
  appId: APP_ID,
  Store: InMemoryStore,
});
```

## Next Steps

Want a more in-depth tutorial on building an Expo app with Instant? Check out [Beto's](https://x.com/betomoedano) video on building a chat app below!

This video goes through core concepts of using Instant like setting up schema, writing queries, and using transactions!



For more advanced features, check out [Simon Grimm](https://x.com/schlimmson) building a mobile app builder with Instant!

In this video Simon builds on top of the concepts from Beto's video and shows off how to use Storage for uploading assets and the Platform API for programmatically spinning up databases.



If you prefer reading docs, you can also check out the [Working with data](/docs/init) section to learn more Instant concepts.

As you get more familiar with Instant, check out our [Recommended Workflow](/docs/recommended-workflow) docs for using Instant in your projects.


# Getting started with Vanilla JS

How to use Instant with Vanilla JS

You can use Instant with plain ol' Javascript/Typescript too. You may find this helpful to integrate Instant with a framework that doesn't have an official SDK yet.

To use Instant in a brand new project fire up your terminal set up a new project with Vite.

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

Now open up `src/main.ts` in your favorite editor and replace the entirety of the file with the following code.

```javascript 
import { init, i, id, InstaQLEntity } from "@instantdb/core";

// Instant app
const APP_ID = "__APP_ID__";

// Optional: Declare your schema!
const schema = i.schema({
  entities: {
    todos: i.entity({
      text: i.string(),
      done: i.boolean(),
      createdAt: i.date(),
    }),
  },
});

type Todo = InstaQLEntity<typeof schema, "todos">;

// Initialize the database
// ---------
const db = init({ appId: APP_ID, schema });

// Subscribe to data
// ---------
db.subscribeQuery({ todos: {} }, (resp) => {
  if (resp.error) {
    renderError(resp.error.message); // Pro-tip: Check you have the right appId!
    return;
  }
  if (resp.data) {
    render(resp.data);
  }
});

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

function deleteTodoItem(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);
  const txs = completed.map((todo) => db.tx.todos[todo.id].delete());
  db.transact(txs);
}

function toggleAllTodos(todos: Todo[]) {
  const newVal = !todos.every((todo) => todo.done);
  db.transact(
    todos.map((todo) => db.tx.todos[todo.id].update({ done: newVal }))
  );
}

// Styles
// ---------
const styles: Record<string, string> = {
  container: `
    box-sizing: border-box;
    background-color: #fafafa;
    font-family: code, monospace;
    height: 100vh;
    display: flex;
    justify-content: center;
    align-items: center;
    flex-direction: column;
  `,
  header: `
    letter-spacing: 2px;
    font-size: 50px;
    color: lightgray;
    margin-bottom: 10px;
  `,
  form: `
    box-sizing: inherit;
    display: flex;
    border: 1px solid lightgray;
    border-bottom-width: 0px;
    width: 350px;
  `,
  toggleAll: `
    font-size: 30px;
    cursor: pointer;
    margin-left: 11px;
    margin-top: -6px;
    width: 15px;
    margin-right: 12px;
  `,
  input: `
    background-color: transparent;
    font-family: code, monospace;
    width: 287px;
    padding: 10px;
    font-style: italic;
  `,
  todoList: `
    box-sizing: inherit;
    width: 350px;
  `,
  checkbox: `
    font-size: 30px;
    margin-left: 5px;
    margin-right: 20px;
    cursor: pointer;
  `,
  todo: `
    display: flex;
    align-items: center;
    padding: 10px;
    border: 1px solid lightgray;
    border-bottom-width: 0px;
  `,
  todoText: `
    grow: 1;
    overflow: hidden;
  `,
  delete: `
    width: 25px;
    cursor: pointer;
    color: lightgray;
  `,
  actionBar: `
    display: flex;
    justify-content: space-between;
    width: 328px;
    padding: 10px;
    border: 1px solid lightgray;
    font-size: 10px;
  `,
  footer: `
    margin-top: 20px;
    font-size: 10px;
  `,
};

// Render
// ---------
const app = document.getElementById("app")!;
app.style.cssText = styles.container;

function render(data: { todos: Todo[] }) {
  app.innerHTML = "";

  const { todos } = data;

  const containerHTML = `
    <div style="${styles.container}">
      <div style="${styles.header}">todos</div>
      ${TodoForm()}
      ${TodoList(todos)}
      ${ActionBar(todos)}
      <div style="${
        styles.footer
      }">Open another tab to see todos update in realtime!</div>
    </div>
  `;

  app.innerHTML = containerHTML;

  // Attach event listeners
  document
    .querySelector(".toggle-all")
    ?.addEventListener("click", () => toggleAllTodos(todos));
  document.querySelector("form")?.addEventListener("submit", submitForm);
  todos.forEach((todo) => {
    document
      .getElementById(`toggle-${todo.id}`)
      ?.addEventListener("change", () => toggleDone(todo));
    document
      .getElementById(`delete-${todo.id}`)
      ?.addEventListener("click", () => deleteTodoItem(todo));
  });
  document
    .querySelector(".delete-completed")
    ?.addEventListener("click", () => deleteCompleted(todos));
}

function renderError(errorMessage: string) {
  app.innerHTML = `
    <div>${errorMessage}</div>
  `;
}

function TodoForm() {
  return `
    <div style="${styles.form}">
      <div class="toggle-all" style="${styles.toggleAll}">⌄</div>
      <form>
        <input style="${styles.input}" placeholder="What needs to be done?" type="text" autofocus>
      </form>
    </div>
  `;
}

function TodoList(todos: Todo[]) {
  return `
    <div style="${styles.todoList}">
      ${todos
        .map(
          (todo) => `
        <div style="${styles.todo}">
          <input id="toggle-${todo.id}" type="checkbox" style="${
            styles.checkbox
          }" ${todo.done ? "checked" : ""}>
          <div style="${styles.todoText}">
            ${
              todo.done
                ? `<span style="text-decoration: line-through;">${todo.text}</span>`
                : `<span>${todo.text}</span>`
            }
          </div>
          <span id="delete-${todo.id}" style="${styles.delete}">𝘟</span>
        </div>
      `
        )
        .join("")}
    </div>
  `;
}

function ActionBar(todos: Todo[]) {
  return `
    <div style="${styles.actionBar}">
      <div>Remaining todos: ${todos.filter((todo) => !todo.done).length}</div>
      <div class="delete-completed" style="cursor: pointer;">Delete Completed</div>
    </div>
  `;
}

function focusInput() {
  const input = document.querySelector<HTMLInputElement>('input[type="text"]');
  if (input) {
    input.focus();
  }
}

function submitForm(event: Event) {
  event.preventDefault();
  const input = (event.target as HTMLFormElement).querySelector("input");
  if (input && input.value.trim()) {
    addTodo(input.value);
    input.value = "";
  }
}
```

Go to `localhost:5173` and follow the final instruction to load the app!

Huzzah 🎉 You've got your first Instant web app running! Check out the [Working with data](/docs/init) section to learn more about how to use Instant :)


# Getting started with TanStack Start

How to use Instant with TanStack Start

## Automatic Setup With Create Instant App

The fastest way to get started with Instant on TanStack Start is to use npx create-instant-app to scaffold a new project with Instant already set up.

To get started run:

```shell
npx create-instant-app -b tanstack-start
```

## Manual Setup

The following guide demonstrates the basics for manually scaffolding a new tanstack project with Instant and managing data. In general we recommend the automatic setup above which includes all of this and a basic auth flow and other useful full-stack utilities.

Create a blank TanStack Start app:

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

Add the InstantDB React Library:

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

Use `instant-cli` to set up a new Instant project. This prompt you to log in if you haven't already., It will then create a schema file, permissions file, and update your `.env` file.

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

Create a database client in `src/lib/db.ts`:



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

export const db = init({
  appId: process.env.VITE_INSTANT_APP_ID!,
  schema,
  useDateObjects: true,
});
```

You're now ready to make queries and transactions to your database!

### Creating a To-Do List App

Let's add a "todo" entity to our schema file at `src/instant.schema.ts`:



```ts 
import { i } from '@instantdb/react';

const _schema = i.schema({
  entities: {
    $files: i.entity({
      path: i.string().unique().indexed(),
      url: i.string(),
    }),
    $users: i.entity({
      email: i.string().unique().indexed().optional(),
      imageURL: i.string().optional(),
      type: i.string().optional(),
    }),
    todos: i.entity({
      text: i.string(),
      done: i.boolean(),
      createdAt: i.date(),
    }),
  },
  links: {
    $usersLinkedPrimaryUser: {
      forward: {
        on: '$users',
        has: 'one',
        label: 'linkedPrimaryUser',
        onDelete: 'cascade',
      },
      reverse: {
        on: '$users',
        has: 'many',
        label: 'linkedGuestUsers',
      },
    },
  },
  rooms: {},
});

//...
```

Push the schema:

```shell 
npx instant-cli push
```

Replace the content of `src/routes/index.tsx` with the following:



```typescript 
import { createFileRoute } from "@tanstack/react-router";
import { AppSchema } from "../instant.schema";
import { id, InstaQLEntity } from "@instantdb/react";
import { db } from "@/lib/db";

export const Route = createFileRoute("/")({
  component: App,
});

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

function App() {
  // Read Data
  const { isLoading, error, data } = db.useQuery({ todos: {} });

  if (isLoading) {
    return null;
  }
  if (error) {
    return <div className="text-red-500 p-4">Error: {error.message}</div>;
  }

  const { todos } = data;
  return (
    <div className="p-8 max-w-2xl">
      <div className="bg-white rounded-lg p-6 border border-neutral-200 shadow flex flex-col">
        <h2 className="tracking-wide text-[#F54A00] pb-2 text-2xl">Todos</h2>
        <div className="text-xs pb-4">
          Open another tab to see todos update in realtime!
        </div>
        <div className="border rounded border-neutral-300">
          <TodoForm />
          <TodoList todos={todos} />
          <ActionBar todos={todos} />
        </div>
      </div>
    </div>
  );
}

// Write Data
// ---------
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() {
  return (
    <div className="flex items-center h-10 border-neutral-300">
      <form
        className="flex-1 h-full"
        onSubmit={(e) => {
          e.preventDefault();
          const input = e.currentTarget.input as HTMLInputElement;
          addTodo(input.value);
          input.value = "";
        }}
      >
        <input
          className="w-full h-full px-2 outline-none bg-transparent"
          autoFocus
          placeholder="What needs to be done?"
          type="text"
          name="input"
        />
      </form>
    </div>
  );
}

function TodoList({ todos }: { todos: Todo[] }) {
  return (
    <div className="divide-y divide-neutral-300">
      {todos.map((todo) => (
        <div key={todo.id} className="flex items-center h-10">
          <div className="h-full px-2 flex items-center justify-center">
            <div className="w-5 h-5 flex items-center justify-center">
              <input
                type="checkbox"
                className="cursor-pointer"
                checked={todo.done}
                onChange={() => toggleDone(todo)}
              />
            </div>
          </div>
          <div className="flex-1 px-2 overflow-hidden flex items-center">
            {todo.done ? (
              <span className="line-through">{todo.text}</span>
            ) : (
              <span>{todo.text}</span>
            )}
          </div>
          <button
            className="h-full px-2 flex items-center justify-center text-neutral-300 hover:text-neutral-500"
            onClick={() => deleteTodo(todo)}
          >
            X
          </button>
        </div>
      ))}
    </div>
  );
}

function ActionBar({ todos }: { todos: Todo[] }) {
  return (
    <div className="flex justify-between items-center h-10 px-2 text-xs border-t border-neutral-300">
      <div>Remaining todos: {todos.filter((todo) => !todo.done).length}</div>
      <button
        className=" text-neutral-300 hover:text-neutral-500"
        onClick={() => deleteCompleted(todos)}
      >
        Delete Completed
      </button>
    </div>
  );
}
```

Go to `localhost:3000`, and huzzah 🎉 You've got a fully functional todo list running!

## Next Steps

Want to dive deeper on how this todo app works? Check out our step-by-step [Todo List Tutorial](/examples/todos). In this tutorial we walk through how to build a todo list app from scratch, and explain how the queries and transactions work in more detail.

For the advanced use case of integrating with TanStack Query and enabling SSR, refer to our [tanstack-start-with-tanstack-query](https://github.com/instantdb/instant/tree/main/examples/tanstack-start-with-tanstack-query) example. It can be scaffolded using `npx create-instant-app -b tanstack-start-with-tanstack-query`.

You can also check out the [Working with data](/docs/init) section to learn more Instant concepts.

As you get more familiar with Instant, check out our [Recommended Workflow](/docs/recommended-workflow) docs for using Instant in your projects.


# Create Instant App

Use create-instant-app to scaffold a new Instant project

Once you know the basics of Instant, you may find it useful to be able to
quickly scaffold a new Instant project. We built `create-instant-app` to do just
that.

We currently offer templates for Next.js, Expo, and Vanilla Typescript. Follow the quick start below to give it a spin!

## Quick start

If you haven't already, authenticate with the [Instant CLI](/docs/cli) in your
terminal.

```shell 
npx instant-cli login
```

This will open a browser window where you can log in or sign up for an account.
Once you've authenticated, any app you create with `create-instant-app` will be
associated with your Instant account!

After authenticating you run the following command to scaffold a new Instant app.

```shell 
npx create-instant-app instant-demo
```

Run the dev server to see your new app in action!

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

Huzzah! 🎉 You now have a brand new Instant project to play around with!

## One-shot with Claude Code

Got Claude Code? You can use it to one-shot a full-stack Instant app!

Use `create-instant-app` with the `--ai` flag and you'll be prompted to describe the app you want to build. Give it a try!



You can think of this as a one-shot app builder in the terminal.

Right now this only works with Next.js and Expo. We're keen to improve this feature so if you have any
feedback please let us know below or on [Discord](https://discord.com/invite/VU53p7uQcE)!


# Recommended Workflow

How to develop with Instant

At a high level, here is the recommended workflow for developing with Instant:

1. Authenticate with Instant in your terminal via `npx instant-cli login`.
1. Create new projects via `npx create-instant-app`.
1. Push changes to your schema and permissions via `npx instant-cli push`.
1. Use the [Sandbox](https://www.instantdb.com/dash?t=sandbox) to debug queries,
   transactions, and permissions.
1. When you're ready for production, [restrict creating](/docs/patterns#restrict-creating-new-attributes) new attributes.
1. If you need more help, check out our [patterns page](/docs/patterns) for common
   recipes or drop us a line on our [Discord](https://discord.com/invite/VU53p7uQcE).

## Authenticating with Instant in your terminal

Use the [Instant CLI](/docs/instant-cli) to authenticate with Instant in your
terminal. After authenticating you'll be able to create new projects
and have them associated with your Instant account. This will also enable you to
push and pull changes to your projects. To authenticate, run:

```
npx instant-cli login
```

This will open a browser window where you can log in or sign up for an account.

## Starting a new project

After authenticating, you can create a new project with
[create-instant-app](/docs/create-instant-app). This will give you some starter code, and set up rules for your LLM
agent. If your agent supports it, we also recommend setting up the [Instant MCP Server](/docs/using-llms#instant-mcp-server).

The default rules cover the basics of using InstantDB. But if you want to add
more docs for specific functionality, you can append `.md` to the end of any doc
page URL to get the raw markdown. For example, here are the docs for
[adding auth](/docs/auth/magic-codes.md).

## Updating schema and permissions

As your project evolves, you'll likely need to update your schema and permissions. We
recommend using the Instant CLI to do this. You can make
edits to your local schema and permission files, and then run `npx instant-cli push` to push changes to your project.

If you prefer a GUI, you can also make changes via the explorer in the [Instant
dashboard](https://www.instantdb.com/dash?t=explorer). To pull these changes
into your local files, run `npx instant-cli pull`.

## Debugging queries, transactions, and permissions

If you're not sure why a query or transaction isn't working, or if you're
running into permission issues, you can use the
[Sandbox](https://www.instantdb.com/dash?t=sandbox) to help you debug.

The sandbox is a REPL-like environment that lets you run queries and
transactions against your project. It serves two goals:

1. Lets you run queries and transactions quickly.
2. Gives you debug info to inspect permission checks and performance.

Some examples of debug info you can see in the sandbox:

- Raw output from queries and transactions
- Permission check results for all entities returned by a query
- Permission check results for each tx operation in a transaction
- How long queries and transactions take to run

### Dealing with timeout errors

InstantDB has the following timeouts for queries and transactions:

- 5 seconds for queries and transactions with the client SDK.
- 30 seconds for queries and transactions in the admin SDK and sandbox.

We set these timeouts intentionally for performance and reliability. We do not
allow timeouts to be configured. Sometimes fixing a timeout is as simple as
adding an index. Other times you'll need to iterate to identify the bottleneck. Some
common causes of timeouts:

- Missing an index
- Fetching or transacting too much data
- Expensive `where` clauses
- Expensive permission rules that traverse a lot of data

Set up test code in your sandbox and run experiments to get under the timeout limit.
From there you can apply the same changes to your app code.

### Dealing with permission errors

The sandbox is one of the best tools for debugging permission errors. Whenever
you run a query or transaction in the sandbox, you can see all the permission
checks that were run, and whether they passed or failed.

If it's unclear why a permission is returning false, re-run the transaction with the permission broken
down into smaller pieces. For example, if you have a permission rule like

```
"view": "auth.id in data.ref('members.id')"
```

It can be helpful to re-run the sandbox with the permission rule changed to

```
"view": "data.ref('members.id')"
```

This will show you the output of just that part of the rule. You can use this technique to
iterate on complex permission rules until you find the part that is causing the
permission to return false.

## Going to production

Huzzah, you're ready for prime time! When you go to production, be sure to [restrict creating](/docs/patterns#restrict-creating-new-attributes) new
attributes. You can also
consider setting up [separate apps](/docs/patterns#managing-local-vs-production-apps) for local development and
production.

## Best practices and getting help

We highly recommend going through our docs to understand how Instant works. We
tried our best to keep them delightful and example-driven!

We've also made a [patterns page](/docs/patterns) with common recipes for using
InstantDB. If you still have questions, feel free to drop us a line on our
[Discord](https://discord.com/invite/VU53p7uQcE).


# Using Instant with LLMs

How to use Instant with LLMs

You can supercharge your Instant experience by using it with LLMs. Just add our Instant rules and your off to the races!

## Instant Skill

The fastest way to add rules to your LLM tool is to add the Instant skill.

```text 
npx skills add instantdb/skills
```

This will give your agent the context it needs to work with InstantDB.

You can verify you set up the rules correctly by asking your LLM "How do you
make queries and transactions in InstantDB?" If everything is set up correctly,
you should see a response with information about `db.useQuery` and `db.transact`

If you'd prefer to manually install the rules instead see the section below.

## Instant Rules

We've created a set of rules to help LLMs understand how Instant works. If you
start a new project with `create-instant-app` you'll get these rules
automatically. If you have an existing project you can add the rules manually by
reading below.

### Cursor

[Save these rules](/llm-rules/cursor-rules.md) at the root of your project in `.cursor/rules/instant.mdc`

You may need to restart Cursor for them to take effect.

When using Cursor we recommend turning off "Auto" and using at least Claude Sonnet 4

### Claude Code

[Save these rules](/llm-rules/AGENTS.md) at the root of your project as `CLAUDE.md`

If you already had Claude running, restart it for the rules to take effect.

### Codex

[Save these rules](/llm-rules/AGENTS.md) at the root of your project as `AGENTS.md`

If you already had Codex running, restart it for the rules to take effect.

### Gemini

[Save these rules](/llm-rules/AGENTS.md) at the root of your project as `GEMINI.md`

If you already had Gemini running, restart it for the rules to take effect.

### Windsurf

[Save these rules](/llm-rules/windsurf-rules.md) at the root of your project in `.windsurf/rules/instant.md`

You may need to restart Windsurf for them to take effect.

### Zed

[Save these rules](/llm-rules/AGENTS.md) at the root of your project as `AGENTS.md`

You may need to restart Zed for them to take effect.

### Other Tools

[Save these rules](/llm-rules/AGENTS.md) at the root of your project as `AGENTS.md`

If you want to manually add in more documentation, you can also append `.md` to the end of any doc page url to get the raw markdown

### Markdown Docs and llms.txt

You can attach `.md` to the end of any doc page url to get raw markdown. This can be helpful to paste into your LLM if you're stuck on
particular functionality. For example, here's the recommended docs for [adding auth](/docs/auth/magic-codes.md.md)

We recommend starting with the rules files above and adding more docs as needed.
If you want though you can get all our docs at once in markdown format via
[llms-full.txt](https://www.instantdb.com/llms-full.txt)

## Instant MCP Server

We built [`@instantdb/mcp`](https://github.com/instantdb/instant/tree/main/client/packages/mcp) to enable creating, managing, and updating your Instant apps.
Combine the MCP with our rules file to build full-stack apps directly in your editor.

The easiest way to get started is to use our hosted remote MCP server. Use the
instructions below to add the Instant MCP server to your favorite LLM editor or tool.



When you add the MCP server, you'll be sent through an OAuth flow to grant access to your Instant Account.



### Cursor

[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=InstantDB&config=eyJ1cmwiOiJodHRwczovL21jcC5pbnN0YW50ZGIuY29tL21jcCJ9)

Or edit your `~/.cursor/mcp.json` directly:

```json 
{
  "mcpServers": {
    "instant": {
      "url": "https://mcp.instantdb.com/mcp"
    }
  }
}
```

### Claude Code

If you're on a paid Claude plan, you can add the the server via the command line

```text 
claude mcp add instant -s user -t http https://mcp.instantdb.com/mcp
```

Now you can run `claude` to start Claude Code and then run `/mcp` to see your list
of MCP servers. `instant` should be listed there. Select it and go through the
auth flow to enable the Instant MCP server in your claude code sessions!

### Codex

If you're on a paid OpenAI plan, you can add the the server via the command line

Edit your `~/.codex/config.toml` to include the [`rmcp_client` feature](https://developers.openai.com/codex/mcp/):

```toml 
[features]
rmcp_client = true
```

Tell codex to add the MCP server:

```text 
codex mcp add instant --url "https://mcp.instantdb.com/mcp"
```

This should load a browser to authenticate with Instant.

Now run `codex` to start Codex. You can run `/mcp` to see Instant in your list.

### Gemini

If you're on a paid Google AI plan, you can add the the server via the command line

```text 
gemini mcp add --transport http instant https://mcp.instantdb.com/mcp
```

This should load a browser to authenticate with Instant.

Now run `gemini` to start Gemini. You can run `/mcp` to see Instant in your list.

### Windsurf

You can add the Instant MCP server through the Windsurf UI

1. Open Windsurf Settings.
2. Under Cascade, you'll find Model Context Protocol Servers.
3. Select Add Server and paste the relevant snippet for your OS.

Alternatively you can directly edit your `~/.codeium/windsurf/mcp_config.json`

**MacOS/Linux**

```json 
{
  "mcpServers": {
    "instant": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.instantdb.com/sse"]
    }
  }
}
```

**Windows**

```json 
{
  "mcpServers": {
    "instant": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "mcp-remote", "https://mcp.instantdb.com/sse"]
    }
  }
}
```

**Windows WSL**

```json 
{
  "mcpServers": {
    "instant": {
      "command": "wsl",
      "args": ["npx", "-y", "mcp-remote", "https://mcp.instantdb.com/sse"]
    }
  }
}
```

### Zed

Open your Zed settings and add the following

```json 
{
  "context_servers": {
    "instant": {
      "command": {
        "path": "npx",
        "args": ["-y", "mcp-remote", "https://mcp.instantdb.com/mcp"],
        "env": {}
      },
      "settings": {}
    }
  }
}
```

### Other Tools

For other tools that support MCP servers, you can configure Instant using either our streamable HTTP
endpoint (recommended if your tool supports it)

```text 
https://mcp.instantdb.com/mcp
```

Or our SSE endpoint

```text 
https://mcp.instantdb.com/sse
```

## Local MCP server

We recommend using our hosted MCP server but we also support running [`@instantdb/mcp`](https://github.com/instantdb/instant/tree/main/client/packages/mcp) locally
via `stdio`. This will avoid OAuth but requires you to manage your personal
access token.

### Get your Personal Access Token

If you haven't already, make sure to get a personal access token from your
[Instant dashboard](https://www.instantdb.com/dash?s=personal-access-tokens)

Once you have your token, you can set up the local Instant MCP server in your
favorite editor with MCP support.

### Cursor/Windsurf/Cline

You can set up the Instant MCP server in Cursor, Windsurf, or Cline by adding
the following configuration to your MCP settings:

**MacOS/Linux**

```json 
{
  "mcpServers": {
    "instant": {
      "command": "npx",
      "args": ["-y", "@instantdb/mcp", "--token", "<token>"]
    }
  }
}
```

**Windows**

```json 
{
  "mcpServers": {
    "instant": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@instantdb/mcp", "--token", "<token>"]
    }
  }
}
```

**Windows WSL**

```json 
{
  "mcpServers": {
    "instant": {
      "command": "wsl",
      "args": ["npx", "-y", "@instantdb/mcp", "--token", "<token>"]
    }
  }
}
```

Replacing `<token>` with your personal access token. Save the file and reload
the editor! You should now see the Instant MCP server active and enabled!

### Zed

Open your Zed settings and add the following

```json 
{
  "context_servers": {
    "instant": {
      "command": {
        "path": "npx",
        "args": ["-y", "@instantdb/mcp", "--token", "<token>"],
        "env": {}
      },
      "settings": {}
    }
  }
}
```

Replacing `<token>` with your personal access token. Save the file and reload the editor.
You should now see the Instant MCP server active and enabled!

### Claude Desktop

You can set up the Instant MCP server in Claude Desktop by following these
steps:

1. Open the file `~/Library/Application Support/Claude/claude_desktop_config.json`
2. Add the following configuration to the `claude_desktop_config.json` file:

```json 
{
  "mcpServers": {
    "instant": {
      "command": "npx",
      "args": ["-y", "@instantdb/mcp", "--token", "<token>"]
    }
  }
}
```

Replacing `<token>` with your personal access token. Save the file and restart
Claude Desktop. You should now see the Instant MCP server active and enabled!

## MCP Tools

Below is a list of the current tools we expose

- `learn` Fetch rules files if needed to help the LLM understand InstantDB.
- `get-schema` Retrieves the schema for a specific app.
- `get-perms` Retrieves permission rules for an app.
- `push-schema` Applies schema changes to an app.
- `push-perms` Updates permission rules for an app.


# Initializing Instant

How to integrate Instant with your app.

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

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

// Instant app
const APP_ID = '__APP_ID__';

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

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

With that, you can use `db` to [write data](/docs/instaml), [make queries](/docs/instaql), [handle auth](/docs/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.

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

// Instant app
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](/docs/modeling-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:

<!-- prettier-ignore-start -->
```typescript
// lib/db.ts
import { init } from '@instantdb/react';
import schema from '../instant.schema';

// Instant app
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;
```
<!-- prettier-ignore-end -->

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


# Modeling data

How to model data with Instant's schema.

In this section we’ll learn how to model data using Instant's schema. By the end of this document you’ll know how to:

- Create namespaces and attributes
- Add indexes and unique constraints
- Model relationships
- Lock down your schema for production

We’ll build a micro-blog to illustrate; we'll have authors, posts, comments, and tags.

## Schema as Code

With Instant you can define your schema and your permissions in code. If you haven't already, use the [CLI](/docs/cli) to generate an `instant.schema.ts`, and a `instant.perms.ts` file:

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

The CLI will guide you through picking an Instant app and generate these files for you.

## instant.schema.ts

Now we can define the data model for our blog!

Open `instant.schema.ts`, and paste the following:

```typescript 
// instant.schema.ts

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

const _schema = i.schema({
  entities: {
    $users: i.entity({
      email: i.string().unique().indexed(),
    }),
    profiles: i.entity({
      nickname: i.string(),
      createdAt: i.date(),
    }),
    posts: i.entity({
      title: i.string(),
      body: i.string(),
      createdAt: i.date(),
    }),
    comments: i.entity({
      body: i.string(),
      createdAt: i.date(),
    }),
    tags: i.entity({
      title: i.string(),
    }),
  },
  links: {
    postAuthor: {
      forward: { on: 'posts', has: 'one', label: 'author' },
      reverse: { on: 'profiles', has: 'many', label: 'authoredPosts' },
    },
    commentPost: {
      forward: { on: 'comments', has: 'one', label: 'post' },
      reverse: { on: 'posts', has: 'many', label: 'comments' },
    },
    commentAuthor: {
      forward: { on: 'comments', has: 'one', label: 'author' },
      reverse: { on: 'profiles', has: 'many', label: 'authoredComments' },
    },
    postsTags: {
      forward: { on: 'posts', has: 'many', label: 'tags' },
      reverse: { on: 'tags', has: 'many', label: 'posts' },
    },
    profileUser: {
      forward: { on: 'profiles', has: 'one', label: '$user' },
      reverse: { on: '$users', has: 'one', label: 'profile' },
    },
  },
});

// This helps TypeScript display better intellisense
type _AppSchema = typeof _schema;
interface AppSchema extends _AppSchema {}
const schema: AppSchema = _schema;

export type { AppSchema };
export default schema;
```

Let's unpack what we just wrote. There are three core building blocks to model data with Instant: **Namespaces**, **Attributes**, and **Links**.

## 1) Namespaces

Namespaces are equivalent to "tables" in relational databases or "collections" in NoSQL. In our case, these are: `$users`, `profiles`, `posts`, `comments`, and `tags`.

They're all defined in the `entities` section:

```typescript
// instant.schema.ts

const _schema = i.schema({
  entities: {
    posts: i.entity({
      // ...
    }),
  },
});
```

## 2) Attributes

Attributes are properties associated with namespaces. These are equivalent to a "column" in relational databases or a "field" in NoSQL. For the `posts` entity, we have the `title`, `body`, and `createdAt` attributes:

```typescript
// instant.schema.ts

const _schema = i.schema({
  entities: {
    // ...
    posts: i.entity({
      title: i.string(),
      body: i.string(),
      createdAt: i.date(),
    }),
  },
});
```

### Typing attributes

Attributes can be typed as `i.string()`, `i.number()`, `i.boolean()`, `i.date()`, `i.json()`, or `i.any()`.



`i.date()` accepts dates as either a numeric timestamp (in milliseconds) or an ISO 8601 string. `JSON.stringify(new Date())` will return an ISO 8601 string.



When you type `posts.title` as a `string`:

```typescript
// instant.schema.ts

const _schema = i.schema({
  entities: {
    // ...
    posts: i.entity({
      title: i.string(),
      // ...
    }),
  },
});
```

Instant will _make sure_ that all `title` attributes are strings, and you'll get the proper typescript hints to boot!

### Required constraints

All attributes you define are considered _required_ by default. This constraint is enforced on the backend: Instant guarantees that every entity of that type will have a value and reports errors if you attempt to add an entity without a required attribute.

```typescript
const _schema = i.schema({
  entities: {
    posts: i.entity({
      title: i.string(), // <-- required
      published: i.date(), // <-- required
    }),
  },
});

db.transact(
  db.tx.posts[id()].update({
    title: 'abc', // <-- no published -- will throw
  }),
);
```

You can mark attribute as optional by calling `.optional()`:

```typescript
const _schema = i.schema({
  entities: {
    posts: i.entity({
      title: i.string(), // <-- required
      published: i.date().optional(), // <-- optional
    }),
  },
});

db.transact(
  db.tx.posts[id()].update({
    title: 'abc', // <-- no published -- still okay
  }),
);
```

This will also reflect in types: query results containing `posts` will show `title: string` (non-nullable) and `published: string | number | null` (nullable).

You can set required on forward links, too:

```typescript
postAuthor: {
  forward: { on: 'posts', has: 'one', label: 'author', required: true },
  reverse: { on: 'profiles', has: 'many', label: 'authoredPosts' },
},
```

Finally, for legacy attributes that are treated as required on your front-end but you are not ready to enable back-end required checks yet, you can use `.clientRequired()`. That will produce TypeScript type without `null` but will not add back-end required check:

```typescript
const _schema = i.schema({
  entities: {
    posts: i.entity({
      title: i.string().clientRequired(),
      published: i.date().optional(),
    }),
  },
});
```

### Unique constraints

Sometimes you'll want to introduce a unique constraint. For example, say we wanted to add friendly URL's to posts. We could introduce a `slug` attribute:

```typescript
// instant.schema.ts

const _schema = i.schema({
  entities: {
    // ...
    posts: i.entity({
      slug: i.string().unique(),
      // ...
    }),
  },
});
```

Since we're going to use post slugs in URLs, we'll want to make sure that no two posts can have the same slug. If we mark `slug` as `unique`, _Instant will guarantee this constraint for us_.

Unique attributes will also speed up queries that filter by that attribute.

```typescript
const query = {
  posts: {
    $: {
      where: {
        // Since `slug` is unique, this query is 🚀 fast
        slug: 'completing_sicp',
      },
    },
  },
};
```

### Indexing attributes

You can also use index attributes to speed up querying. An additional
benefit is that indexed attributes can be used with comparison operators for
where queries like `$gt`, `$lt`, `$gte`, and `$lte` and can be used in `order`
clauses.

Suppose we wanted to query for products less than $100 and order by price.

First we make sure that the `price` attribute is indexed:

```typescript
// instant.schema.ts

const _schema = i.schema({
  entities: {
    // ...
    products: i.entity({
      price: i.number().indexed(), // 🔥,
      // ...
    }),
  },
});
```

And now we can use `$lt` and `order` in our query:

```typescript
const query = {
  products: {
    $: {
      where: {
        price: { $lt: 100 },
      },
      order: {
        price: 'desc',
      },
    },
  },
};
```

Even if you're not using comparison operators or order clauses, indexing
attributes can still speed up queries that filter by that attribute.

## 3) Links

Links connect two namespaces together. When you define a link, you define it both in the 'forward', and the 'reverse' direction. For example:

```typescript
postAuthor: {
  forward: { on: "posts", has: "one", label: "author" },
  reverse: { on: "profiles", has: "many", label: "authoredPosts" },
}
```

This links `posts` and `profiles` together:

- `posts.author` links to _one_ `profiles` entity
- `profiles.authoredPosts` links back to _many_ `posts` entities.

Since links are defined in both directions, you can query in both directions too:

```typescript
// This queries all posts with their author
const query1 = {
  posts: {
    author: {},
  },
};

// This queries profiles, with all of their authoredPosts!
const query2 = {
  profiles: {
    authoredPosts: {},
  },
};
```

Links can have one of four relationship types: `many-to-many`, `many-to-one`, `one-to-many`, and `one-to-one`

Our micro-blog example has the following relationship types:

- **One-to-one** between `profiles` and `$users`
- **One-to-many** between `posts` and `profiles`
- **One-to-many** between `comments` and `posts`
- **One-to-many** between `comments` and `profiles`
- **Many-to-many** between `posts` and `tags`

### Cascade Delete

Links defined with `has: "one"` can set `onDelete: "cascade"`. In this case, when the profile entity is deleted, all post entities will be deleted too:

```typescript
postAuthor: {
  forward: { on: "posts", has: "one", label: "author", onDelete: "cascade" },
  reverse: { on: "profiles", has: "many", label: "authoredPosts" },
}

// this will delete profile and all linked posts
db.tx.profiles[user_id].delete();
```

Without `onDelete: "cascade"`, deleting a profile would simply delete the links but not delete the underlying posts.

If you prefer to model links in other direction, you can do it, too:

```
postAuthor: {
  forward: { on: "profiles", has: "many", label: "authoredPosts" },
  reverse: { on: "posts", has: "one", label: "author", onDelete: "cascade" },
}
```

## Publishing your schema

Now that you have your schema, you can use the CLI to `push` it to your app:

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

The CLI will look at your app in production, show you the new columns you'd create, and run the changes for you!



```
Checking for an Instant SDK...
Found @instantdb/react in your package.json.
Found NEXT_PUBLIC_INSTANT_APP_ID: *****
Planning schema...
The following changes will be applied to your production schema:
ADD ENTITY profiles.id
ADD ENTITY posts.id
ADD ENTITY comments.id
ADD ENTITY tags.id
ADD ATTR profiles.nickname :: unique=false, indexed=false
ADD ATTR profiles.createdAt :: unique=false, indexed=false
ADD ATTR posts.title :: unique=false, indexed=false
ADD ATTR posts.slug :: unique=true, indexed=false
ADD ATTR posts.body :: unique=false, indexed=false
ADD ATTR posts.createdAt :: unique=false, indexed=true
ADD ATTR comments.body :: unique=false, indexed=false
ADD ATTR comments.createdAt :: unique=false, indexed=false
ADD ATTR tags.title :: unique=false, indexed=false
ADD LINK posts.author <=> profiles.authoredPosts
ADD LINK comments.post <=> posts.comments
ADD LINK comments.author <=> profiles.authoredComments
ADD LINK posts.tags <=> tags.posts
ADD LINK profiles.$user <=> $users.profile
? OK to proceed? yes
Schema updated!
```



## Use schema for typesafety

You can also use your schema inside `init`:

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

import schema from '../instant.schema.ts';

const db = init({
  appId: process.env.NEXT_PUBLIC_INSTANT_APP_ID!,
  schema,
});
```

When you do this, all [queries](/docs/instaql) and [transactions](/docs/instaml) will come with typesafety out of the box.



If you haven't used the CLI to push your schema yet, no problem. Any time you write `transact`, we'll automatically create missing entities for you.



## Update or Delete attributes

You can always modify or delete attributes after creating them. **You can't use the CLI to do this yet, but you can use the dashboard.**

Say we wanted to rename `posts.createdAt` to `posts.publishedAt`:

1. Go to your [Dashboard](https://instantdb.com/dash)
2. Click "Explorer"
3. Click "posts"
4. Click "Edit Schema"
5. Click `createdAt`

You'll see a modal that you can use to rename the attribute, index it, or delete it:



## Secure your schema with permissions

In the earlier sections we mentioned that new `entities` and `attributes` can be created on the fly when you call `transact`. This can be useful for development, but you may not want this in production.

To prevent changes to your schema on the fly, simply add these permissions to your app.

```typescript
// instant.perms.ts
import type { InstantRules } from '@instantdb/react';

const rules = {
  attrs: {
    allow: {
      $default: 'false',
    },
  },
} satisfies InstantRules;

export default rules;
```

Once you push these permissions to production:

```bash
npx instant-cli@latest push perms
```



```
Checking for an Instant SDK...
Found @instantdb/react in your package.json.
Found NEXT_PUBLIC_INSTANT_APP_ID: *****
Planning perms...
The following changes will be applied to your perms:
-null
+{
+  attrs: {
+    allow: {
+      $default: "false"
+    }
+  }
+}
OK to proceed? yes[21
Permissions updated!
```



You'll still be able to make changes in the explorer or with the CLI, but client-side transactions that try to modify your schema will fail. This means your schema is safe from unwanted changes!

---

**If you've made it this far, congratulations! You should now be able to fully customize and lock down your data model. Huzzah!**


# Writing data

How to write data with Instant using InstaML.

Instant uses a **Firebase-inspired** interface for mutations. We call our mutation language **InstaML**

## Creating data

We use the `create` action to create entities:

```typescript
import { init, id } from '@instantdb/react';

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

// transact! 🔥
db.transact(db.tx.goals[id()].create({ title: 'eat' }));
```

This creates a new `goal` with the following properties:

- It's identified by a randomly generated id via the `id()` function.
- It has an attribute `title` with value `eat`.

You can store `strings`, `numbers`, `booleans`, `arrays`, and `objects` as values. You can also generate values via functions. Below is an example for picking a random goal title.

```javascript
db.transact(
  db.tx.goals[id()].create({
    title: ['eat', 'sleep', 'hack', 'repeat'][Math.floor(Math.random() * 4)],
  }),
);
```

## Update data

The `update` action is used for updating entities. Suppose we had created the following goal

```javascript
const eatId = id();
db.transact(
  db.tx.goals[eatId].update({ priority: 'top', lastTimeEaten: 'Yesterday' }),
);
```

We eat some food and decide to update the goal. We can do that like so:

```javascript
db.transact(db.tx.goals[eatId].update({ lastTimeEaten: 'Today' }));
```

This will only update the value of the `lastTimeEaten` attribute for entity `eat`.

Similar to NoSQL, you don't need to use the same schema for each entity in a namespace. After creating the previous goal you can run the following:

```javascript
db.transact(
  db.tx.goals[id()].update({
    priority: 'none',
    isSecret: true,
    value: 10,
    aList: [1, 2, 3],
    anObject: { foo: 'bar' },
  }),
);
```

`update` function works as create or update depending on whether the entity already exists or not (so called "upsert" mode). If entity doesn’t exist yet, calling `update` will create it, otherwise it will update.

To force “strict update” mode, pass `{ upsert: false }` option:

```javascript
db.transact(
  db.tx.goals[eatId].update({ lastTimeEaten: 'Today' }, { upsert: false }),
);
```

## Merge data

When you `update` an attribute, you overwrite it. This is fine for updating
values of strings, numbers, and booleans. But if you use `update` to overwrite
json objects you may encounter two problems:

1. You lose any data you didn't specify.
2. You risk clobbering over changes made by other clients.

For example, imagine we had a `game` entity, that stored a `state` of favorite colors:

```javascript
// User 1 saves {'0-0': 'red'}
db.transact(db.tx.games[gameId].update({ state: { '0-0': 'red' } }));

// User 2 saves {'0-1': 'blue'}
db.transact(db.tx.games[gameId].update({ state: { '0-1': 'blue' } }));

// 🤔 Uh oh! User 2 overwrite User 1:
// Final State: {'0-1': 'blue' }
```

To make working with deeply-nested, document-style JSON values a breeze, we created `merge`.
Similar to [lodash's `merge` function](https://lodash.com/docs/4.17.15#merge),
`merge` allows you to specify the slice of data you want to update:

```javascript
// User 1 saves {'0-0': 'red'}
db.transact(db.tx.games[gameId].merge({ state: { '0-0': 'red' } }));

// User 2 saves {'0-1': 'blue'}
db.transact(db.tx.games[gameId].merge({ state: { '0-1': 'blue' } }));

// ✅ Wohoo! Both states are merged!
// Final State: {'0-0': 'red', '0-1': 'blue' }
```

`merge` only merges objects. Calling `merge` on **arrays, numbers, or booleans** will overwrite the values.

Sometimes you may want to remove keys from a nested object. You can do so by calling `merge` with a key set to `null`. This will remove the corresponding property from the object.


Setting a key to `undefined` will have no effect. Set the key to `null` to remove the property.


```javascript
// State: {'0-0': 'red', '0-1': 'blue' }
db.transact(db.tx.games[gameId].merge({ state: { '0-1': null } }));
// New State! {'0-0': 'red' }
```

## Delete data

The `delete` action is used for deleting entities.

```javascript
db.transact(db.tx.goals[eatId].delete());
```

You can generate an array of `delete` txs to delete all entities in a namespace

```javascript
const { isLoading, error, data } = db.useQuery({ goals: {} });
const { goals } = data;
// ...

db.transact(goals.map((g) => db.tx.goals[g.id].delete()));
```

Calling `delete` on an entity also deletes its associations. So no need to worry about cleaning up previously created links.

## Link data

`link` is used to create associations.

Suppose we create a `goal` and a `todo`.

```javascript
db.transact([
  db.tx.todos[workoutId].update({ title: 'Go on a run' }),
  db.tx.goals[healthId].update({ title: 'Get fit!' }),
]);
```

We can associate `healthId` with `workoutId` like so:

```javascript
db.transact(db.tx.goals[healthId].link({ todos: workoutId }));
```

We could have done all this in one `transact` too via chaining transaction chunks.

```javascript
db.transact([
  db.tx.todos[workoutId].update({ title: 'Go on a run' }),
  db.tx.goals[healthId]
    .update({ title: 'Get fit!' })
    .link({ todos: workoutId }),
]);
```

You can specify multiple ids in one `link` as well:

```javascript
db.transact([
  db.tx.todos[workoutId].update({ title: 'Go on a run' }),
  db.tx.todos[proteinId].update({ title: 'Drink protein' }),
  db.tx.todos[sleepId].update({ title: 'Go to bed early' }),
  db.tx.goals[healthId]
    .update({ title: 'Get fit!' })
    .link({ todos: [workoutId, proteinId, sleepId] }),
]);
```

Links are bi-directional. Say we link `healthId` to `workoutId`

```javascript
db.transact(db.tx.goals[healthId].link({ todos: workoutId }));
```

We can query associations in both directions

```javascript
const { isLoading, error, data } = db.useQuery({
  goals: { todos: {} },
  todos: { goals: {} },
});

const { goals, todos } = data;
console.log('goals with nested todos', goals);
console.log('todos with nested goals', todos);
```

## Unlink data

Links can be removed via `unlink.`

```javascript
db.transact(db.tx.goals[healthId].unlink({ todos: workoutId }));
```

This removes links in both directions. Unlinking can be done in either direction so unlinking `workoutId` from `healthId` would have the same effect.

```javascript
db.transact([db.tx.todos[workoutId].unlink({ goals: healthId })]);
```

We can `unlink` multiple ids too:

```javascript
db.transact([
  db.tx.goals[healthId].unlink({ todos: [workoutId, proteinId, sleepId] }),
  db.tx.goals[workId].unlink({ todos: [standupId, reviewPRsId, focusId] }),
]);
```

## Lookup by unique attribute

If your entity has a unique attribute, you can use `lookup` in place of the id to perform updates.

```javascript
db.transact(
  db.tx.profiles.lookup('email', 'eva_lu_ator@instantdb.com').update({
    name: 'Eva Lu Ator',
  }),
);
```

The `lookup` function takes the attribute as its first argument and the unique attribute value as its second argument.

When it is used in a transaction, the updates will be applied to the entity that has the unique value. If no entity has the value, then a new entity with a random id will be created with the value.

It can be used with `update`, `delete`, `merge`, `link`, and `unlink`.

## Lookups in links

When used with links, it can also be used in place of the linked entity's id.

```javascript
db.transact(
  db.tx.users.lookup('email', 'eva_lu_ator@instantdb.com').link({
    posts: lookup('number', 15), // using a lookup in place of the id
  }),
);
```

## Transacts are atomic

When you call `db.transact`, all the transactions are committed atomically. If
any of the transactions fail, none of them will be committed.

## Typesafety

By default, `db.transact` is permissive. When you save data, we'll create missing attributes for you:

```typescript
db.tx.todos[workoutId].update({
  // Instant will automatically create this attribute
  dueDate: Date.now() + 60 * 1000,
});
```

As your app grows, you may want to start enforcing types. When you're ready, you can start using a [schema](/docs/modeling-data). If your schema includes a `todos.dueDate` for example:

```typescript
// instant.schema.ts
const _schema = i.schema({
  entities: {
    todos: i.entity({
      // ...
      dueDate: i.date(),
    }),
  },
  // ...
});
// ...
```

Instant will enforce that `todos.dueDate` are actually dates, and you'll get some nice intellisense to boot:



Instant also comes with a few utility types, which can help you write abstractions over `transact`. For example, say you wanted to write a custom `update` function:

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

You can use the `UpdateParams` utility to make sure arguments follow the schema:

```typescript
import { UpdateParams } from '@instantdb/react';
import { AppSchema } from '../instant.schema.ts';

type EntityTypes = keyof AppSchema['entities'];

function myCustomUpdate<EType extends EntityTypes>(
  etype: EType,
  args: UpdateParams<AppSchema, EType>,
) {
  // ..
}
```

And the `LinkParams` utility do the same for links:

```typescript
import { LinkParams } from '@instantdb/react';
import { AppSchema } from '../instant.schema.ts';

type EntityTypes = keyof AppSchema['entities'];

function myCustomLink<EType extends EntityTypes>(
  etype: EType,
  args: LinkParams<AppSchema, EType>,
) {
  // ..
}
```

To learn more about writing schemas, check out the [Modeling Data](/docs/modeling-data) section.

## Batching transactions

If you have a large number of transactions to commit, you'll want to batch them
to avoid hitting transaction limits and time outs.

Suppose we want to create 3000 goals. Here's how we can batch them into 30 transactions of 100 goals each.

```javascript
const batchSize = 100; // doing 100 txs should be pretty safe
const createGoals = async (total) => {
  let goals = [];
  const batches = [];

  // iterate through all your goals and create batches
  for (let i = 0; i < total; i++) {
    const goalNumber = i + 1;
    goals.push(
      db.tx.goals[id()].update({ goalNumber, title: `Goal ${goalNumber}` }),
    );

    // We have enough goals to create a batch
    if (goals.length >= batchSize) {
      batches.push(goals);
      goals = []; // reset goals for the next batch
    }
  }

  // Add any remaining goals to the last batch
  if (goals.length) {
    batches.push(goals);
  }

  // Now that you have your batches, transact them
  for (const batch of batches) {
    await db.transact(batch);
  }
};
```

## Using the tx proxy object

`db.tx` is a [proxy object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) which creates transaction chunks to be committed via `db.transact`. It follows the format

```
db.tx.NAMESPACE_LABEL[ENTITY_IDENTIFIER].ACTION(ACTION_SPECIFIC_DATA)
```

- `NAMESPACE_LABEL` refers to the namespace to commit (e.g. `goals`, `todos`)
- `ENTITY_IDENTIFIER` is the id to look up in the namespace. This id must be a uuid and unique to the namespace. You can use the `id()` function to generate a uuid for convenience.
- `ACTION` is one of `create`, `update`, `merge`, `delete`, `link`, `unlink`
- `ACTION_SPECIFIC_DATA` depends on the action
  - `create` and `update` take in an object of information to commit
  - `merge` takes in an object to deep merge with the existing data
  - `delete` is the only action that doesn't take in any data,
  - `link` and `unlink` takes an object of label-entity pairs to create/delete associations


# Reading data

How to read data with Instant using InstaQL.

Instant uses a declarative syntax for querying. It's like GraphQL without the configuration. Here's how you can query data with **InstaQL.**

## Fetch namespace

One of the simplest queries you can write is to simply get all entities of a namespace.

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

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

function App() {
  // Queries! 🚀
  const query = { goals: {} };
  const { isLoading, error, data } = db.useQuery(query);
  // ...
}
```

Inspecting `data`, we'll see:

```javascript
console.log(data)
{
  "goals": [
    {
      "id": healthId,
      "title": "Get fit!"
    },
    {
      "id": workId,
      "title": "Get promoted!"
    }
  ]
}
```

For comparison, the SQL equivalent of this would be something like:

```javascript
const data = { goals: doSQL('SELECT * FROM goals') };
```

## Fetch multiple namespaces

You can fetch multiple namespaces at once:

```javascript
const query = { goals: {}, todos: {} };
const { isLoading, error, data } = db.useQuery(query);
```

We will now see data for both namespaces.

```javascript
console.log(data)
{
  "goals": [...],
  "todos": [
    {
      "id": focusId,
      "title": "Code a bunch"
    },
    {
      "id": proteinId,
      "title": "Drink protein"
    },
    ...
  ]
}
```

The equivalent of this in SQL would be to write two separate queries.

```javascript
const data = {
  goals: doSQL('SELECT * from goals'),
  todos: doSQL('SELECT * from todos'),
};
```

## Fetch a specific entity

If you want to filter entities, you can use the `where` keyword. Here we fetch a specific goal.

```javascript
const query = {
  goals: {
    $: {
      where: {
        id: healthId,
      },
    },
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

```javascript
console.log(data)
{
  "goals": [
    {
      "id": healthId,
      "title": "Get fit!"
    }
  ]
}
```

The SQL equivalent would be:

```javascript
const data = { goals: doSQL("SELECT * FROM goals WHERE id = 'healthId'") };
```

## Fetch associations

We can fetch goals and their related todos.

```javascript
const query = {
  goals: {
    todos: {},
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

`goals` would now include nested `todos`

```javascript
console.log(data)
{
  "goals": [
    {
      "id": healthId,
      "title": "Get fit!",
      "todos": [...],
    },
    {
      "id": workId,
      "title": "Get promoted!",
      "todos": [...],
    }
  ]
}
```

### Comparing with SQL

The SQL equivalent for this would be something along the lines of:

```javascript
const query = `
  SELECT g.*, gt.todos
  FROM goals g
  JOIN (
      SELECT g.id, json_agg(t.*) as todos
      FROM goals g
      LEFT JOIN todos t on g.id = t.goal_id
      GROUP BY 1
  ) gt on g.id = gt.id
`;
const data = { goals: doSQL(query) };
```

Notice the complexity of this SQL query. Although fetching associations in SQL is straightforward via `JOIN`, marshalling the results in a nested structure via SQL is tricky. An alternative approach would be to write two straight-forward queries and then marshall the data on the client.

```javascript
const _goals = doSQL("SELECT * from goals")
const _todos = doSQL("SELECT * from todos")
const data = {goals: _goals.map(g => (
  return {...g, todos: _todos.filter(t => t.goal_id === g.id)}
))
```

Now compare these two approaches with `InstaQL`

```javascript
const query = {
  goals: {
    todos: {},
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

Modern applications often need to render nested relations, `InstaQL` really starts to shine for these use cases.

## Fetch specific associations

### A) Fetch associations for filtered namespace

We can fetch a specific entity in a namespace as well as it's related associations.

```javascript
const query = {
  goals: {
    $: {
      where: {
        id: healthId,
      },
    },
    todos: {},
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

Which returns

```javascript
console.log(data)
{
  "goals": [
    {
      "id": healthId,
      "title": "Get fit!",
      "todos": [
        {
          "id": proteinId,
          "title": "Drink protein"
        },
        {
          "id": sleepId,
          "title": "Go to bed early"
        },
        {
          "id": workoutId,
          "title": "Go on a run"
        }
      ]
    }
  ]
}
```

### B) Filter namespace by associated values

We can filter namespaces **by their associations**

```javascript
const query = {
  goals: {
    $: {
      where: {
        'todos.title': 'Code a bunch',
      },
    },
    todos: {},
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

Returns

```javascript
console.log(data)
{
  "goals": [
    {
      "id": workId,
      "title": "Get promoted!",
      "todos": [
        {
          "id": focusId,
          "title": "Code a bunch"
        },
        {
          "id": reviewPRsId,
          "title": "Review PRs"
        },
        {
          "id": standupId,
          "title": "Do standup"
        }
      ]
    }
  ]
}
```

### C) Filter associations

We can also filter associated data.

```javascript
const query = {
  goals: {
    todos: {
      $: {
        where: {
          title: 'Go on a run',
        },
      },
    },
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

This will return goals and filtered todos

```javascript
console.log(data)
{
  "goals": [
    {
      "id": healthId,
      "title": "Get fit!",
      "todos": [
        {
          "id": workoutId,
          "title": "Go on a run"
        }
      ]
    },
    {
      "id": workId,
      "title": "Get promoted!",
      "todos": []
    }
  ]
}
```

---


Notice the difference between these three cases.

- A) Fetched all todos for goal with id `health`
- B) Filtered goals with a least one todo titled `Code a bunch`
- C) Fetched all goals and filtered associated todos by title `Go on a run`



---

## Inverse Associations

Associations are also available in the reverse order.

```javascript
const query = {
  todos: {
    goals: {},
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

```javascript
console.log(data)
{
  "todos": [
    {
      "id": focusId,
      "title": "Code a bunch",
      "goals": [
        {
          "id": workId,
          "title": "Get promoted!"
        }
      ]
    },
    ...,
  ]
}
```

## Defer queries

You can also defer queries until a condition is met. This is useful when you
need to wait for some data to be available before you can run your query. Here's
an example of deferring a fetch for todos until a user is logged in.

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

const {
  isLoading: isLoadingTodos,
  error,
  data,
} = db.useQuery(
  user
    ? {
        // The query will run once user is populated
        todos: {
          $: {
            where: {
              'owner.id': user.id,
            },
          },
        },
      }
    : // Otherwise skip the query, which sets `isLoading` to true
      null,
);
```

**NOTE:** Passing `null` to `db.useQuery` will result in `isLoading` being true. In the example above, this means that `isLoadingTodos` will _always be true_ if the user is not logged in.

## Pagination

You can limit the number of items from a top level namespace by adding a `limit` to the option map:

```javascript
const query = {
  todos: {
    // limit is only supported for top-level namespaces right now
    // and not for nested namespaces.
    $: { limit: 10 },
  },
};

const { isLoading, error, data, pageInfo } = db.useQuery(query);
```

Instant supports both offset-based and cursor-based pagination for top-level
namespaces.

### Offset

To get the next page, you can use an offset:

```javascript
const query = {
  todos: {
    $: {
      limit: 10,
      // similar to `limit`, `offset` is only supported for top-level namespaces
      offset: 10,
    },
  },
};

const { isLoading, error, data, pageInfo } = db.useQuery(query);
```

In a React application, your offset-based pagination code might look something like this:

```jsx
const [pageNumber, setPageNumber] = React.useState(1);

const pageSize = 10;

const query = {
  todos: {
    $: {
      limit: pageSize,
      offset: pageSize * (pageNumber - 1),
    },
  },
};

const { isLoading, error, data } = db.useQuery(query);

// Load the next page by increasing the page number, which will
// increase the offset by the page size.
const loadNextPage = () => {
  setPageNumber(pageNumber + 1);
};

// Load the previous page by decreasing the page number, which will
// decrease the offset by the page size.
const loadPreviousPage = () => {
  setPageNumber(pageNumber - 1);
};
```

### Cursors

You can also get the next page with the `endCursor` returned in the `pageInfo` map from the previous result:

```javascript
const query = {
  todos: {
    $: {
      // These also are only supported for top-level namespaces
      first: 10,
      after: pageInfo?.todos?.endCursor,
    },
  },
};
```

To get the previous page, use the `startCursor` in the `before` field of the option map and ask for the `last` items:

```javascript
const query = {
  todos: {
    $: {
      last: 10,
      before: pageInfo?.todos?.startCursor,
    },
  },
};
```

In a React application, your cursor-based pagination code might look something like this:

```jsx
const pageSize = 10;

const [cursors, setCursors] = React.useState({ first: pageSize });

const query = {
  todos: {
    $: {
      ...cursors,
    },
  },
};

const { isLoading, error, data, pageInfo } = db.useQuery(query);

const loadNextPage = () => {
  const endCursor = pageInfo?.todos?.endCursor;
  if (endCursor) {
    setCursors({ after: endCursor, first: pageSize });
  }
};

const loadPreviousPage = () => {
  const startCursor = pageInfo?.todos?.startCursor;
  if (startCursor) {
    setCursors({
      before: startCursor,
      // Ask for the `last` 10 items so that we get the items just
      // before our startCursor
      last: pageSize,
    });
  }
};
```

### Ordering

The default ordering is by the time the objects were created, in ascending order. You can change the order with the `order` key in the option map for namespaces:

```javascript
const query = {
  todos: {
    $: {
      limit: 10,
      // Similar to limit, order is limited to top-level namespaces right now
      order: {
        serverCreatedAt: 'desc',
      },
    },
  },
};
```

The `serverCreatedAt` field is a reserved key that orders by the time that the object was first persisted on the Instant backend. It can take the value 'asc' (the default) or 'desc'.

You can also order by any attribute that is indexed and has a checked type.


Add indexes and checked types to your attributes from the [Explorer on the Instant dashboard](/dash?t=explorer) or from the [cli](/docs/cli).


```typescript
// Get the todos that are due next
const query = {
  todos: {
    $: {
      limit: 10,
      where: {
        dueDate: { $gt: Date.now() },
      },
      order: {
        dueDate: 'asc',
      },
    },
  },
};
```

You can use order in nested namespaces as well:

```typescript
// Get goals with their associated todos ordered by due date
const query = {
  goals: {
    todos: {
      $: {
        order: {
          dueDate: 'asc',
        },
      },
    },
  },
};
```

Order is not supported on nested attributes. So if todos had an owner you could
not order todos by "owner.name". This behavior is different from `where`,
which supports filtering on nested attributes.

```typescript
// ❌ Order does not support nested attributes
const query = {
  todos: {
    $: {
      order: {
        'owner.name': 'asc', // Cannot order by nested attributes
      },
    },
  },
};

// ✅ Where does support filtering on nested attributes
const query = {
  todos: {
    $: {
      where: {
        'owner.name': 'alyssa.p.hacker@instantdb.com',
      },
    },
  },
};
```

## Advanced filtering

### Multiple `where` conditions

The `where` clause supports multiple keys which will filter entities that match all of the conditions.

```javascript
const query = {
  todos: {
    $: {
      where: {
        completed: true,
        'goals.title': 'Get promoted!',
      },
    },
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

```javascript
console.log(data)
{
  "todos": [
    {
      "id": focusId,
      "title": "Code a bunch",
      "completed": true
    }
  ]
}
```

### And

The `where` clause supports `and` queries which are useful when you want to filter entities that match multiple associated values.

In this example we want to find goals that have todos with the titles `Drink protein` and `Go on a run`

```javascript
const query = {
  goals: {
    $: {
      where: {
        and: [
          { 'todos.title': 'Drink protein' },
          { 'todos.title': 'Go on a run' },
        ],
      },
    },
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

```javascript
console.log(data)
{
  "goals": [
    {
      "id": healthId,
      "title": "Get fit!"
    }
  ]
}
```

### OR

The `where` clause supports `or` queries that will filter entities that match any of the clauses in the provided list:

```javascript
const query = {
  todos: {
    $: {
      where: {
        or: [{ title: 'Code a bunch' }, { title: 'Review PRs' }],
      },
    },
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

```javascript
console.log(data);
{
  "todos": [
    {
      "id": focusId,
      "title": "Code a bunch"
    },
    {
      "id": reviewPRsId,
      "title": "Review PRs"
    },
  ]
}
```

### $in

The `where` clause supports `$in` queries that will filter entities that match any of the items in the provided list.
You can think of this as a shorthand for `or` on a single key.

```javascript
const query = {
  todos: {
    $: {
      where: {
        title: { $in: ['Code a bunch', 'Review PRs'] },
      },
    },
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

```javascript
console.log(data)
{
  "todos": [
    {
      "id": focusId,
      "title": "Code a bunch"
    },
    {
      "id": reviewPRsId,
      "title": "Review PRs"
    }
  ]
}
```

### Comparison operators

The `where` clause supports comparison operators on fields that are indexed and have checked types.


Add indexes and checked types to your attributes from the [Explorer on the Instant dashboard](/dash?t=explorer) or from the [cli with Schema-as-code](/docs/modeling-data).


| Operator |       Description        | JS equivalent |
| :------: | :----------------------: | :-----------: |
|  `$gt`   |       greater than       |      `>`      |
|  `$lt`   |        less than         |      `<`      |
|  `$gte`  | greater than or equal to |     `>=`      |
|  `$lte`  |  less than or equal to   |     `<=`      |

```javascript
const query = {
  todos: {
    $: {
      where: {
        timeEstimateHours: { $gt: 24 },
      },
    },
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

```javascript
console.log(data);
{
  "todos": [
    {
      "id": buildShipId,
      "title": "Build a starship prototype",
      "timeEstimateHours": 5000
    }
  ]
}
```

Dates can be stored as timestamps (milliseconds since the epoch, e.g. `Date.now()`) or as ISO 8601 strings (e.g. `JSON.stringify(new Date())`) and can be queried in the same formats:

```javascript
const now = '2024-11-26T15:25:00.054Z';
const query = {
  todos: {
    $: { where: { dueDate: { $lte: now } } },
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

```javascript
console.log(data);
{
  "todos": [
    {
      "id": slsFlightId,
      "title": "Space Launch System maiden flight",
      "dueDate": "2017-01-01T00:00:00Z"
    }
  ]
}
```

If you try to use comparison operators on data that isn't indexed and type-checked, you'll get an error:

```javascript
const query = {
  todos: {
    $: { where: { priority: { $gt: 2 } } },
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

```javascript
console.log(error);
{
  "message": "Validation failed for query",
  "hint": {
    "data-type": "query",
    "errors": [
      {
        "expected?": "indexed?",
        "in": ["priority", "$", "where", "priority"],
        "message": "The `todos.priority` attribute must be indexed to use comparison operators."
      }
    ],
    "input": {
      "todos": {
        "$": {
          "where": {
            "priority": {
              "$gt": 2
            }
          }
        }
      }
    }
  }
}
```

### $ne

The `where` clause supports `$ne` queries that will return entities that don't
match the provided value for the field, including entities where the field is null or undefined.

```javascript
const query = {
  todos: {
    $: {
      where: {
        location: { $ne: 'work' },
      },
    },
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

```javascript
console.log(data)
{
  "todos": [
    {
      "id": cookId,
      "title": "Cook dinner",
      "location": "home"
    },
    {
      "id": readId,
      "title": "Read",
      "location": null
    },
        {
      "id": napId,
      "title": "Take a nap"
    }
  ]
}
```

### $isNull

The `where` clause supports `$isNull` queries that will filters entities by whether the field value is either null or undefined.

Set `$isNull` to `true` to return entities where where the field is null or undefined.

Set `$isNull` to `false` to return entities where the field is not null and not undefined.

```javascript
const query = {
  todos: {
    $: {
      where: {
        location: { $isNull: false },
      },
    },
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

```javascript
console.log(data)
{
  "todos": [
    {
      "id": cookId,
      "title": "Cook dinner",
      "location": "home"
    }
  ]
}
```

```javascript
const query = {
  todos: {
    $: {
      where: {
        location: { $isNull: true },
      },
    },
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

```javascript
console.log(data)
{
  "todos": [
    {
      "id": readId,
      "title": "Read",
      "location": null
    },
    {
      "id": napId,
      "title": "Take a nap"
    }
  ]
}
```

### $like

The `where` clause supports `$like` on fields that are indexed with a checked `string` type.

`$like` queries will return entities that match a **case sensitive** substring of the provided value for the field.

For **case insensitive** matching use `$ilike` in place of `$like`.

Here's how you can do queries like `startsWith`, `endsWith` and `includes`.

|          Example          |      Description      | JS equivalent |
| :-----------------------: | :-------------------: | :-----------: |
|    `{ $like: "Get%" }`    |   Starts with 'Get'   | `startsWith`  |
| `{ $like: "%promoted!" }` | Ends with 'promoted!' |  `endsWith`   |
|   `{ $like: "%fit%" }`    |    Contains 'fit'     |  `includes`   |

Here's how you can use `$like` to find all goals that end with the word
"promoted!"

```javascript
// Find all goals that end with the word "promoted!"
const query = {
  goals: {
    $: {
      where: {
        title: { $like: '%promoted!' },
      },
    },
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

```javascript
console.log(data)
{
  "goals": [
    {
      "id": workId,
      "title": "Get promoted!",
    }
  ]
}
```

You can use `$like` in nested queries as well

```javascript
// Find goals that have todos with the word "standup" in their title
const query = {
  goals: {
    $: {
      where: {
        'todos.title': { $like: '%standup%' },
      },
    },
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

Returns

```javascript
console.log(data)
{
  "goals": [
    {
      "id": standupId,
      "title": "Perform standup!",
    }
  ]
}
```

Case-insensitive matching with `$ilike`:

```javascript
const query = {
  goals: {
    $: {
      where: {
        'todos.title': { $ilike: '%stand%' },
      },
    },
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

```javascript
console.log(data)
{
  "goals": [
    {
      "id": standupId,
      "title": "Perform standup!",
    },
    {
      "id": standId,
      "title": "Stand up a food truck.",
    }
  ]
}
```

## Select fields

An InstaQL query will fetch all fields for each object.

If you prefer to select the specific fields that you want your query to return, use the `fields` param:

```javascript
const query = {
  goals: {
    $: {
      fields: ['status'],
    },
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

```javascript
console.log(data)
{
  "goals": [
    {
      "id": standupId, // id will always be returned even if not specified
      "status": "in-progress"
    },
    {
      "id": standId,
      "status": "completed"
    }
  ]
}
```

`fields` also works with nested relations:

```javascript
const query = {
  goals: {
    $: {
      fields: ['title'],
    },
    todos: {
      $: {
        fields: ['id'],
      },
    },
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

```javascript
console.log(data)
{
  "goals": [
    {
      "id": standupId,
      "title": "Perform standup!",
      "todos": [{"id": writeJokesId}, {"id": goToOpenMicId}]
    },
    {
      "id": standId,
      "title": "Stand up a food truck.",
      "todos": [{"id": learnToCookId}, {"id": buyATruckId}]
    }
  ]
}
```

Using `fields` can be useful for performance optimization. It reduces the
amount of data that needs to be transferred from the server and minimizes the
number of re-renders in your React application if there are no changes to your
selected fields.



Using `fields` doesn't restrict a client from doing a full query. If you have sensitive data on your entities that you
don't want to expose you'll want to use [permissions](/docs/permissions#fields) to restrict access.



## Typesafety

By default, `db.useQuery` is permissive. You don't have to tell us your schema upfront, and you can write any kind of query:

```typescript
const query = {
  goals: {
    todos: {},
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

As your app grows, you may want to start enforcing types. When you're ready you can write a [schema](/docs/modeling-data). If your schema includes `goals` and `todos` for example:

```typescript
// instant.schema.ts

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

const _schema = i.schema({
  entities: {
    goals: i.entity({
      title: i.string(),
    }),
    todos: i.entity({
      title: i.string(),
      text: i.string(),
      done: i.boolean(),
      createdAt: i.date(),
      dueDate: i.date(),
    }),
  },
  links: {
    goalsTodos: {
      forward: { on: 'goals', has: 'many', label: 'todos' },
      reverse: { on: 'todos', has: 'many', label: 'goals' },
    },
  },
});

// This helps TypeScript display better intellisense
type _AppSchema = typeof _schema;
interface AppSchema extends _AppSchema {}
const schema: AppSchema = _schema;

export type { AppSchema };
export default schema;
```

Instant will start giving you intellisense for your queries. For example, if you're querying for goals, you'll see that only `todos` can be associated:



And if you hover over `data`, you'll see the actual typed output of your query:



### Utility Types

Instant also comes with some utility types to help you use your schema in TypeScript.

For example, you could define your `query` upfront:

```typescript
import { InstaQLParams } from '@instantdb/react';
import { AppSchema } from '../instant.schema.ts';

// `query` typechecks against our schema!
const query = {
  goals: { todos: {} },
} satisfies InstaQLParams<AppSchema>;
```

Or you can define your result type:

```typescript
import { InstaQLResult } from '@instantdb/react';
import { AppSchema } from '../instant.schema.ts';

type GoalsTodosResult = InstaQLResult<AppSchema, { goals: { todos: {} } }>;
```

Or you can extract a particular entity:

```typescript
import { InstaQLEntity } from '@instantdb/react';
import { AppSchema } from '../instant.schema.ts';

type Todo = InstaQLEntity<AppSchema, 'todos'>;
```

You can specify links relative to your entity:

```typescript
type TodoWithGoals = InstaQLEntity<AppSchema, 'todos', { goals: {} }>;
```

To learn more about writing schemas, check out the [Modeling Data](/docs/modeling-data) section.

## Query once

Sometimes, you don't want a subscription, and just want to fetch data once. For example, you might want to fetch data before rendering a page or check whether a user name is available.

In these cases, you can use `queryOnce` instead of `useQuery`. `queryOnce` returns a promise that resolves with the data once the query is complete.

Unlike `useQuery`, `queryOnce` will throw an error if the user is offline. This is because `queryOnce` is intended for use cases where you need the most up-to-date data.

```javascript
const query = { todos: {} };
const { data } = await db.queryOnce(query);
// returns the same data as useQuery, but without the isLoading and error fields
```

You can also do pagination with `queryOnce`:

```javascript
const query = {
  todos: {
    $: {
      limit: 10,
      offset: 10,
    },
  },
};

const { data, pageInfo } = await db.queryOnce(query);
// pageInfo behaves the same as with useQuery
```


# Instant on the Backend

How to use Instant on the server with the Admin SDK.

You can use Instant on the server as well! This can be especially useful for
running scripts, custom auth flows, or sensitive application logic.

## Admin SDK

We currently offer a javascript library `@instantdb/admin` for using Instant in
a non-browser context. This library is similar to our client SDK with a few
tweaks.

### init

```javascript
import { init, id } from '@instantdb/admin';

// Instant app
const APP_ID = '__APP_ID__';
const db = init({
  appId: APP_ID,
  adminToken: process.env.INSTANT_APP_ADMIN_TOKEN,
});
```

Similar to `@instantdb/react`, you must `init` before doing any queries or
writes. Running `init` authenticates you against our admin API. In addition to
providing your `appId`, you can provide your `adminToken`.



Whereas exposing your `appId` in source control is fine, it's not safe
to expose your `adminToken`. Permission checks will not run for queries and
writes from our admin API. Be sure to regenerate your token from your dashboard
if it accidentally leaks.



## Reading and Writing Data

`query` and `transact` let you read and write data as an admin.

### query

```javascript
const data = await db.query({ goals: {}, todos: {} });
const { goals, todos } = data;
```

In react we use `db.useQuery` to enable "live queries", queries that will
automatically update when data changes.

In the admin SDK we instead use an async `db.query` function that simply fires a
query once and returns a result.

### transact

```typescript 
const res = await db.transact([db.tx.todos[id()].update({ title: 'Get fit' })]);
console.log('New todo entry made for with tx-id', res['tx-id']);
```

`db.transact` is an async function that behaves nearly identical to `db.transact`
from `@instantdb/react`. It returns a `tx-id` on success.

## Subscriptions on the backend

You can use `db.subscribeQuery` to subscribe to queries on the backend. This can be useful if you have backend processes that react to database changes.

For example, let's say we wanted to subscribe to a `tasks` table.

### With callbacks

You could pass in a callback to `db.subscribeQuery` that gets called with newly updated query results:

```typescript 
const sub = db.subscribeQuery({ tasks: { $: { limit: 10 } } }, (payload) => {
  if (payload.type === 'error') {
    console.log('error', error);
    sub.close();
  } else {
    console.log('got data!', payload.data);
  }
});

// When you want to close the subscription:
sub.close();
```

### With async iterator

Or if you prefer, you can skip providing a callback and use async iterators:

```typescript 
const sub = db.subscribeQuery({ tasks: { $: { limit: 10 } } });

for await (const payload of sub) {
  if (payload.type === 'error') {
    console.log('error', error);
    sub.close();
  } else {
    console.log('data', payload.data);
  }
}

// When you want to close the subscription:
sub.close();
```


Subscriptions keep a live connection open on your backend. Be sure to close them when they’re no longer needed to avoid tying up resources unnecessarily.


## Schema

`init` also accepts a schema argument:

```typescript 
import { init, id } from '@instantdb/admin';
import schema from '../instant.schema.ts';

// Instant app
const APP_ID = '__APP_ID__';
const db = init({
  appId: APP_ID,
  adminToken: process.env.INSTANT_APP_ADMIN_TOKEN,
  schema,
});
```

If you add a schema, `db.query` and `db.transact` will come with autocompletion and typesafety out of the box. The backend will also use your schema to generate missing attributes.

To learn more about writing schemas, head on over to the [Modeling your data](/docs/modeling-data) section.

## Impersonating users

When you use the admin SDK, you can make _any_ query or transaction. As an admin, you bypass permissions.
But, sometimes you want to make queries on behalf of your users, and would like to respect permissions.

You can do this with the `db.asUser` function.

```typescript 
// Scope by their email
const scopedDb = db.asUser({ email: 'alyssa_p_hacker@instantdb.com' });
// Or with their auth token
const token = db.auth.createToken({ email: 'alyssa_p_hacker@instantdb.com' });
const scopedDb = db.asUser({ token });
// Or use the db as a guest!
const scopedDb = db.asUser({ guest: true });
// Queries and transactions will run with those permissions
await scopedDb.query({ logs: {} });
```

### Running the admin SDK in client environments

Impersonation can also let you run the Admin SDK _without_ exposing an admin token.

```javascript 
import { init } from '@instantdb/admin';

// If you only impersonate with a user token or as a guest,
// you can _skip_ admin credentials
const db = init({
  appId: process.env.INSTANT_APP_ID!
});

// Pass in a user token to run as a particular user
const userDB = db.asUser({
  token: "...",
});

// Or run as a guest
const guestDB = db.asUser({
  guest: true,
});

// Queries and transactions work will work with respective permissions
await userDB.query({ todos: {} });
await guestDB.query({ publicData: {} });
```

This approach is perfect for places where you need something like the Admin SDK, but don't want to expose admin credentials.

For example, what if you want to run a background daemon on a user's machine? You can't use the client SDK, because you don't need optimistic updates. You wouldn't want to provide the admin token, because this code runs on a user's machine. That's when impersonation really comes in handy.


Without an `adminToken`, you must use `.asUser({ token })` or `asUser({ guest: true })` for all operations. Direct queries and transactions on the base `db` instance will fail, and you won't be able to impersonate with `asUser({ email })`. In protected environments we definitely recommend including the `adminToken`.


## Retrieve a user

As an admin, you can retrieve an app user record by `email`, `id`, or `refresh_token`. You can do this with the `db.auth.getUser` function.

```typescript 
const user = await db.auth.getUser({ email: 'alyssa_p_hacker@instantdb.com' });
const user = await db.auth.getUser({
  id: userId,
});
const user = await db.auth.getUser({
  refresh_token: userRefreshToken,
});
```

## Delete a user

You can also delete an app user record by `email`, `id`, or `refresh_token`. You can do this with the `db.auth.deleteUser` function.

```typescript 
const deletedUser = await db.auth.deleteUser({
  email: 'alyssa_p_hacker@instantdb.com',
});
const deletedUser = await db.auth.deleteUser({
  id: userId,
});
const deletedUser = await db.auth.deleteUser({
  refresh_token: userRefreshToken,
});
```

Note, this _only_ deletes the user record and any associated data with cascade on delete. If there's additional data you need to clean up you'll need to do it manually:

```typescript 
const { goals, todos } = await db.query({
  goals: { $: { where: { creator: userId } } },
  todos: { $: { where: { creator: userId } } },
});

await db.transact([
  ...goals.map((item) => db.tx.goals[item.id].delete()),
  ...todos.map((item) => tx.todos[item.id].delete()),
]);
// Now we can delete the user
await db.auth.deleteUser({ id: userId });
```

## Presence in the Backend

If you use [rooms & presence](/docs/presence-and-topics), you may want to query for the data currently in a room with the admin API. This can be especially useful if you are sending a notification for example, and want to skip it if the user is already online.

To do get room data from the admin API, use `db.rooms.getPresence`:

```typescript 
const data = await db.rooms.getPresence('chat', 'room-123');
console.log(Object.values(data));
// [{
//     'peer-id': '...',
//     user: { id: '...', email: 'foo@bar.com', ... },
//     data: { typing: true, ... },
//   },
// }];
```

## Sign Out

The `db.auth.signOut` method allows you to log out users. You can log a user out from every session by passing in their `email`, or `id`. Or you can log a user out from a particular session by passing in a `refresh_token`:

```typescript 
// All sessions for this email sign out
await db.auth.signOut({ email: 'alyssa_p_hacker@instantdb.com' });
// All sessions for this user id sign out
const user = await db.auth.signOut({
  id: userId,
});
// Just sign out the session for this refresh token
await db.auth.signOut({
  refresh_token: userRefreshToken,
});
```

## Custom Auth

You can use the Admin SDK to create your own authentication flows. To implement custom auth flows, you would make one change in your backend, and one change in your frontend. Here's how it would look:

### 1. Backend: db.auth.createToken

Create a new `sign-in` endpoint in your backend.

This endpoint will use `db.auth.createToken` to generate an authentication token for the user.

```typescript 
app.post('/sign-in', async (req, res) => {
  // your custom logic for signing users in
  // ...
  // on success, create and return a token
  const token = await db.auth.createToken({ email });
  return res.status(200).send({ token });
});
```

`db.auth.createToken` accepts either an email or a UUID. For the UUID variant:

```typescript 
const token = await db.auth.createToken({ id });
```

If a user with the provider id or email does not exist, `db.auth.createToken` will create the user for you.

### 2. Frontend: db.auth.signInWithToken

Once your frontend calls your `sign-in` endpoint, it can then use the generated token and sign a user in with `db.auth.signInWithToken`.

Here's a full example:

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

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

async function customSignIn(
  email: string,
  password: string
): Promise<{ token: string }> {
  const response = await fetch('your-website.com/api/sign-in', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ email, password }),
  });
  const data = await response.json();
  return data;
}

function App() {
  const { isLoading, user, error } = db.useAuth();
  if (isLoading) {
    return <div>Loading...</div>;
  }
  if (error) {
    return <div>Uh oh! {error.message}</div>;
  }
  if (user) {
    return <div>Hello {user.email}!</div>;
  }
  return <Login />;
}

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

  const handleEmailChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setEmail(event.target.value);
  };

  const handlePasswordChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setPassword(event.target.value);
  };

  const handleSignIn = async () => {
    const data = await customSignIn(email, password); // initiate your custom sign in flow
    db.auth.signInWithToken(data.token); // sign in with the token on success
  };

  return (
    <div>
      <input
        type="email"
        placeholder="Enter your email"
        value={email}
        onChange={handleEmailChange}
      />
      <input
        type="password"
        placeholder="Enter your password"
        value={password}
        onChange={handlePasswordChange}
      />
      <button onClick={handleSignIn}>Sign In</button>
    </div>
  );
}
```

## Custom magic codes

We support a [magic code flow](/docs/auth) out of the box. However, if you'd like to use your own email provider to send the code, you can do this with `db.auth.generateMagicCode` function:

```typescript 
app.post('/custom-send-magic-code', async (req, res) => {
  const { code } = await db.auth.generateMagicCode(req.body.email);
  // Now you can use your email provider to send magic codes
  await sendMyCustomMagicCodeEmail(req.body.email, code);
  return res.status(200).send({ ok: true });
});
```

You can also use Instant's default email provider to send a magic code with `db.auth.sendMagicCode`:

```typescript 
// You can trigger a magic code email in your backend with `sendMagicCode`
const { code } = await db.auth.sendMagicCode(req.body.email);
```

Similarly, you can verify a magic code with `db.auth.verifyMagicCode`:

```typescript 
const user = await db.auth.verifyMagicCode(req.body.email, req.body.code);
const token = user.refresh_token;
```

## Authenticated Endpoints

You can also use the admin SDK to authenticate users in your custom endpoints. This would have two steps:

### 1. Frontend: user.refresh_token

In your frontend, the `user` object has a `refresh_token` property. You can pass this token to your endpoint:

```javascript
// client
import { init } from '@instantdb/react';

const db = init(/* ... */)

function App() {
  const { user } = db.useAuth();
  // call your api with `user.refresh_token`
  function onClick() {
    myAPI.customEndpoint(user.refresh_token, ...);
  }
}
```

### 2. Backend: auth.verifyToken

You can then use `auth.verifyToken` to verify the `refresh_token` that was passed in.

```typescript 
app.post('/custom_endpoint', async (req, res) => {
  // verify the token this user passed in
  const user = await db.auth.verifyToken(req.headers['token']);
  if (!user) {
    return res.status(401).send('Uh oh, you are not authenticated');
  }
  // ...
});
```

### Syncing Auth

Sometimes you want to get the logged in user in the backend without needing to explicitly pass in the refresh token from the frontend. Here's how you can do it.

Instant provides a `createInstantRouteHandler` function that generates a web standard endpoint that can be used to sync the refresh token to a cookie that your server can read.

To use it in NextJS:

```typescript 
// src/app/api/instant/route.ts
import { createInstantRouteHandler } from '@instantdb/react/nextjs';

export const { POST } = createInstantRouteHandler({
  appId: process.env.NEXT_PUBLIC_INSTANT_APP_ID!,
});
```

The GET and POST functions accept a [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) and return a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Request) so they should be able to be used in any framework.

Then, provide your mounted api url to the `init` function.

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

export const db = init({
  appId: process.env.NEXT_PUBLIC_INSTANT_APP_ID!,
  firstPartyPath: '/api/instant', // the endpoint that you registered the route handler at.
  schema,
  useDateObjects: true,
});
```

If using NextJS you can call getUnverifiedUserFromInstantCookie with the app id to retrieve the user in any server component, or route handler.

```typescript
import { getUserFromInstantCookie } from "@instantdb/react/nextjs";

// This is a server component!
export default async function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  // Get the instant user from the cookie
  const user = await getUnverifiedUserFromInstantCookie(process.env.NEXT_PUBLIC_INSTANT_APP_ID!);

  return (
    <html lang="en">
      <body>
        <AuthProvider user={user}>{children}</AuthProvider>
      </body>
    </html>
  );
}
```


# Patterns

Common patterns for working with InstantDB.

Below are some common patterns for working with InstantDB. We'll add more
patterns over time and if you have a pattern you'd like to share, please feel
free to submit a PR for this page.

## You can expose your app id to the client.

Similar to Firebase, the app id is a unique identifier for your application.
If you want to secure your data, you'll want to add
[permissions](/docs/permissions) for the app.

## Restrict creating new attributes.

When you're ready to lock down your schema, you can restrict creating a new
attribute by adding this to your app's [permissions](/dash?t=perms)

```json
{
  "attrs": { "allow": { "$default": "false" } }
}
```

This will prevent any new attributes from being created.

## Attribute level permissions

When you query a namespace, it will return all the attributes for an entity.
You can use the [`fields`](/docs/instaql#select-fields) clause to restrict which attributes
are returned from the server but this will not prevent a client from doing
another query to get the full entity.

You can set special permission rules for [`fields`](/docs/instaql/#fields), to make sure only certain attributes
are visible to certain users.

## Find entities with no links.

If you want to find entities that have no links, you can use the `$isNull`
query filter. For example, if you want to find all posts that are not linked to
an author you can do

```javascript
const { isLoading, error, data } = db.useQuery({
  posts: {
    $: {
      where: {
        'author.id': {
          $isNull: true,
        },
      },
    },
  },
});
```

## Setting limits via permissions.

If you want to limit the number of entities a user can create, you can do so via
permissions. Here's an example of limiting a user to creating at most 2 todos.

First the [schema](/docs/modeling-data):

```typescript
// instant.schema.ts
// Here we define users, todos, and a link between them.
import { i } from '@instantdb/core';

const _schema = i.schema({
  entities: {
    $users: i.entity({
      email: i.string().unique().indexed(),
    }),
    todos: i.entity({
      label: i.string(),
    }),
  },
  links: {
    userTodos: {
      forward: {
        on: 'todos',
        has: 'one',
        label: 'owner',
      },
      reverse: {
        on: '$users',
        has: 'many',
        label: 'ownedTodos',
      },
    },
  },
});

// This helps TypeScript display nicer intellisense
type _AppSchema = typeof _schema;
interface AppSchema extends _AppSchema {}
const schema: AppSchema = _schema;

export type { AppSchema };
export default schema;
```

Then the [permissions](/docs/permissions):

```typescript
import type { InstantRules } from '@instantdb/react';
// instant.perms.ts
// And now we reference the `owner` link for todos to check the number
// of todos a user has created.
// (Note): Make sure the `owner` link is already defined in the schema.
// before you can reference it in the permissions.
const rules = {
  todos: {
    allow: {
      create: "size(data.ref('owner.ownedTodos.id')) <= 2",
    },
  },
} satisfies InstantRules;

export default rules;
```

## Listen to InstantDB connection status.

Sometimes you want to let clients know when they are connected or disconnected
to the DB. You can use `db.subscribeConnectionStatus` in vanilla JS or
`db.useConnectionStatus` in React to listen to connection changes

```javascript
// Vanilla JS
const unsub = db.subscribeConnectionStatus((status) => {
  const statusMap = {
    connecting: 'authenticating',
    opened: 'authenticating',
    authenticated: 'connected',
    closed: 'closed',
    errored: 'errored',
  };

  const connectionState = statusMap[status] || 'unexpected state';
  console.log('Connection status:', connectionState);
});

// React/React Native
function App() {
  const statusMap = {
    connecting: 'authenticating',
    opened: 'authenticating',
    authenticated: 'connected',
    closed: 'closed',
    errored: 'errored',
  };
  const status = db.useConnectionStatus();

  const connectionState = statusMap[status] || 'unexpected state';
  return <div>Connection state: {connectionState}</div>;
}
```

## Using Instant via CDN

If you have a plain html page or avoid using a build step, you can use InstantDB
via a CDN through [unpkg](https://www.unpkg.com/@instantdb/core/).

```jsx 
<!-- Load Instant via unpkg -->
<!-- Consider replacing @latest with a specific package -->
<script src="https://www.unpkg.com/@instantdb/core@latest/dist/standalone/index.umd.cjs"></script>

<!-- Use Instant like normal -->
<script>
  const { init, id } = instant;
  // Instant app
  const APP_ID = '__APP_ID__';
  const db = init({ appId: APP_ID });

  async function createMessage() {
    await db.transact(
      db.tx.messages[id()].update({
        text: 'Hello world!'
      })
    );
  }
</script>
```

## Making Local ids

Sometimes you need an identifier that stays the same between refreshes. A "local id" of sorts.

Local ids are especially useful for features like "guest" mode. You need an identifier for the user who is accessing the service, but they haven't signed up yet. Well, you can use a `localId` for that. To generate one, use `db.getLocalId`:

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

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

const id = await db.getLocalId('guest');

console.log(id, 'stays the same even if you refresh');
```

Or a handy hook if you're inside React:

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

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

function App() {
  const id = db.useLocalId('guest');
  if (!id) return;
  console.log(id, 'stays the same even if you refresh');
}
```

Note: passing in different arguments will produce different ids:

```js
const id1 = db.useLocalId('device');
const id2 = db.useLocalId('session');
console.log(
  id1,
  id2,
  'are different. But each will stay the same even if you refresh',
);
```

Once you have an ID, you can pass it around in your transactions and queries, and use them in [ruleParams](/docs/permissions#rule-params).

## Making admin queries work with NextJS Caching

NextJS caches fetch requests and lets you revalidate them. [`adminDB.query`](/docs/backend#query) uses fetch under the hood, so NextJS caching will work by default.

If you want to finely control how the query caches, you can pass in the same kind of [fetch options](https://nextjs.org/docs/app/building-your-application/caching#fetch) for NextJS. For example, to revalidate a query every hour:

```js
await adminDB.query(
  { goals: {} },
  {
    fetchOpts: {
      next: { revalidate: 3600 },
    },
  },
);
```

Or to set a specific tag:

```js
await adminDB.query(
  { goals: {} },
  {
    fetchOpts: {
      next: { tags: ['goals:all'] },
    },
  },
);
```

## Composite keys

Sometimes an item is unique by two or more attributes. For example, consider a `location`: it's unique by `latitude` _and_ `longitude`.

How can you enforce this uniqueness in Instant?

We don't have composite keys built-in, but you can manage them by creating a composite column. For example, you can make sure `locations` are unique by adding a `latLong` column:

```js
import { i } from '@instantdb/core';
const _schema = i.schema({
  entities: {
    // ...
    locations: i.entity({
      latitude: i.number().indexed(),
      longitude: i.number().indexed(),
      latLong: i.string().unique() // <-- our composite column
    }),
  },
```

We can then set `latLong` in our updates:

```js
function createLocation({ latitude, longitude }) {
  db.transact(
    db.tx.locations[id()].update({
      latitude,
      longitude,
      latLong: `${latitude}_${longitude}`,
    }),
  );
}
```

Now, any locations with the same latitude and longitude will throw a uniqueness error.

To make sure that `latLong` _always_ matches `latitude` and `longitude`, you can add a rule in your permissions:

```js
const rules = {
  locations: {
    allow: {
      create: "(data.latitude + '_' + data.longitude) == data.latLong",
      update: "(newData.latitude + '_' + newData.longitude) == newData.latLong",
    },
  },
};
```

## Managing local vs production apps

You may want to have separate Instant apps for local development and production.
The way to do this right now is to have two separate apps, one for local and one
for production.

```javascript
// lib/db.ts
import { init } from '@instantdb/react';

const APP_ID = process.env.NEXT_PUBLIC_INSTANT_APP_ID;

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

Then in your environment files:

```bash
# .env.local
NEXT_PUBLIC_INSTANT_APP_ID=your-local-app-id

# .env.production
NEXT_PUBLIC_INSTANT_APP_ID=your-production-app-id
```

When developing new features that require schema or permission changes, you can
follow this workflow:

1. **Push schema/perms changes locally first**

   ```bash
   npx instant-cli push --app your-local-app-id
   ```

2. **Test code changes** - Verify your new code works as expected with your changes in your local environment and app.

3. **Push changes to production**

   ```bash
   npx instant-cli push --app your-production-app-id
   ```

4. **Deploy code changes to prod!** - And that should be it!

## Dealing with timeouts

Complicated queries or large transactions may fail due to timeouts. Right now we
have a hard limit of 5 seconds for both queries and transactions. We do this to
ensure real-time doesn't suffer from long-running operations.

To get a sense for how long a query or transaction takes, you can use the
`Sandbox` tab in the dashboard. Using `await db.query` or `await db.transact` will
show you the time it took to run the operation in the console. Queries and
transactions in the sandbox can run for up to 30 seconds,

Once you have a sense of how long your queries and transactions take, you can
iteratively optimize them. For example, you can use pagination or add indexes
to speed up queries, or break up large transactions into smaller ones.

## Setting default values when making an attribute required

When converting an optional attribute to a required one, you'll need to
update existing entities with null values.

For example, if you try to make `done` required on `todos` but some
records have null values:

```
INVALID DATA adding required constraint to todos.done.
  First few examples:
  namespace       | id                                    | done
  ----------------|---------------------------------------|------
  todos           | 13a09c93-cee0-4e21-9e41-c7e08edd1649  | null
  todos           | 043eec60-d971-4689-8e4a-099e82c251a2  | null
```

The solution is to run an admin script to backfill the null values before pushing the schema change.

```typescript
// scripts/backfill-todos.ts
import { init, tx } from '@instantdb/admin';

const db = init({
  appId: process.env.INSTANT_APP_ID!,
  adminToken: process.env.INSTANT_ADMIN_TOKEN!,
});

async function backfillDefaults() {
  // Query for entities with null/missing done
  const { data } = await db.query({
    todos: {
      $: {
        where: {
          done: { $isNull: true },
        },
      },
    },
  });

  // Update them with a default value
  const updates = data.todos.map((todo) =>
    tx.todos[todo.id].update({ done: false }),
  );

  if (updates.length > 0) {
    await db.transact(updates);
    console.log(`Backfilled ${updates.length} records`);
  } else {
    console.log('No records to backfill');
  }
}

backfillDefaults();
```

Then run the script before pushing your schema:

```bash
npx tsx scripts/backfill-todos.ts && npx instant-cli push
```

This pattern gives you full control over setting default values. You can set
static values as shown above, or use more complex logic to determine the default
based on other attributes.


# Auth

Instant supports magic code, OAuth, Clerk, and custom auth.

Instant comes with support for auth. We currently offer [Magic Codes](/docs/auth/magic-codes), [Guest Auth](/docs/auth/guest-auth), [Google OAuth](/docs/auth/google-oauth), [Sign In with Apple](/docs/auth/apple), [Github OAuth](/docs/auth/github-oauth), [LinkedIn OAuth](/docs/auth/linkedin-oauth), and [Clerk](/docs/auth/clerk). If you want to build your own flow, you can use the [Admin SDK](/docs/backend#custom-auth).

## Auth Overview

To get the current user in your application, you can use the `db.useUser` hook.

```tsx
import db from '../lib/db';

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

  return <div>Signed in as: {user.email}</div>;
}
```

The `useUser` hook will throw an error if it is accessed while the user is not logged in, so it should be gated behind `<db.SignedIn>`

```tsx
import db from '../lib/db';

export default function App() {
  return (
    <div>
      <db.SignedIn>
        <Dashboard />
      </db.SignedIn>
      <db.SignedOut>
        <div>Log in to see the dashboard!</div>
      </db.SignedOut>
    </div>
  );
}

function Dashboard() {
  // This component will only render if the user is signed in
  // so it's safe to call useUser here!
  const user = db.useUser();

  return <div>Signed in as: {user.email}</div>;
}
```

Use `<db.SignedIn>` and `<db.SignedOut>` to conditionally render components
based on the user's authentication state.

You can then use `db.auth.signOut()` to sign a user out.

```tsx
import db from '../lib/db';

// ... Same app component from above

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

  return (
    <div>
      <div>Signed in as: {user.email}</div>
      <button onClick={() => db.auth.signOut()}>Sign out</button>
    </div>
  );
}
```

Putting it all together, you can conditionally render a login and dashboard component
like so:

```tsx
import db from '../lib/db';

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

function Dashboard() {
  // This component will only render if the user is signed in
  // so it's safe to call useUser here!
  const user = db.useUser();

  return <div>Signed in as: {user.email}</div>;
}

function Login() {
  // Implement a login flow here via magic codes, OAuth, Clerk, etc.
}
```

To implement a login flow use one of the authentication method guides below.

## Authentication Methods














## Additional Auth APIs

Sometimes you need finer control over the state of auth in your application. In those cases, you can use some of the lower-level API.

### useAuth

Use `useAuth` to fetch the current user. In this example we guard against loading
our `Main` component until a user is logged in

```javascript
function App() {
  const { isLoading, user, error } = db.useAuth();
  if (isLoading) {
    return null; // or a loading spinner
  }
  if (error) {
    return <div className="p-4 text-red-500">Uh oh! {error.message}</div>;
  }
  if (user) {
    return <Main />;
  }
  return <Login />;
}
```

### Get auth

For scenarios where you want to know the current auth state without subscribing
to changes, you can use `getAuth`.

```javascript
const user = await db.getAuth();
console.log('logged in as', user.email);
```


# Magic Code Auth

How to add magic code auth to your Instant app.



Instant supports a "magic-code" flow for auth. Users provide their email, we send
them a login code on your behalf, and they authenticate with your app.

Choose the platform you're building for to see a full example.









## Full Magic Code Example



Here's a full example of magic code auth in a React app. Open up your `app/page.tsx` file, and replace the entirety of it with the following code:

```tsx 
'use client';

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

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.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() {
  const [sentEmail, setSentEmail] = useState('');

  return (
    <div className="flex min-h-screen items-center justify-center">
      <div className="max-w-sm">
        {!sentEmail ? (
          <EmailStep onSendEmail={setSentEmail} />
        ) : (
          <CodeStep sentEmail={sentEmail} />
        )}
      </div>
    </div>
  );
}

function EmailStep({ onSendEmail }: { onSendEmail: (email: string) => void }) {
  const inputRef = React.useRef<HTMLInputElement>(null);
  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const inputEl = inputRef.current!;
    const email = inputEl.value;
    onSendEmail(email);
    db.auth.sendMagicCode({ email }).catch((err) => {
      alert('Uh oh :' + err.body?.message);
      onSendEmail('');
    });
  };
  return (
    <form
      key="email"
      onSubmit={handleSubmit}
      className="flex flex-col space-y-4"
    >
      <h2 className="text-xl font-bold">Let's log you in</h2>
      <p className="text-gray-700">
        Enter your email, and we'll send you a verification code. We'll create
        an account for you too if you don't already have one.
      </p>
      <input
        ref={inputRef}
        type="email"
        className="w-full border border-gray-300 px-3 py-1"
        placeholder="Enter your email"
        required
        autoFocus
      />
      <button
        type="submit"
        className="w-full bg-blue-600 px-3 py-1 font-bold text-white hover:bg-blue-700"
      >
        Send Code
      </button>
    </form>
  );
}

function CodeStep({ sentEmail }: { sentEmail: string }) {
  const inputRef = React.useRef<HTMLInputElement>(null);
  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const inputEl = inputRef.current!;
    const code = inputEl.value;
    db.auth.signInWithMagicCode({ email: sentEmail, code }).catch((err) => {
      inputEl.value = '';
      alert('Uh oh :' + err.body?.message);
    });
  };

  return (
    <form
      key="code"
      onSubmit={handleSubmit}
      className="flex flex-col space-y-4"
    >
      <h2 className="text-xl font-bold">Enter your code</h2>
      <p className="text-gray-700">
        We sent an email to <strong>{sentEmail}</strong>. Check your email, and
        paste the code you see.
      </p>
      <input
        ref={inputRef}
        type="text"
        className="w-full border border-gray-300 px-3 py-1"
        placeholder="123456..."
        required
        autoFocus
      />
      <button
        type="submit"
        className="w-full bg-blue-600 px-3 py-1 font-bold text-white hover:bg-blue-700"
      >
        Verify Code
      </button>
    </form>
  );
}

export default App;
```





Here's a full example of magic code auth in a React Native app. Open up your `app/index.tsx` file, and replace the entirety of it with the following code:

```tsx 
import React, { useState } from 'react';
import { View, Text, TextInput, Button, Alert, StyleSheet } from 'react-native';
import { init } from '@instantdb/react-native';

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

function App() {
  const { isLoading, user, error } = db.useAuth();
  if (isLoading) {
    return <Text>Loading...</Text>;
  }
  if (error) {
    return <Text>Uh oh! {error.message}</Text>;
  }
  if (user) {
    return <Main />;
  }
  return <Login />;
}

function Main() {
  const user = db.useUser();
  return (
    <View style={styles.container}>
      <Text style={styles.header}>Hello {user.email}!</Text>
      <Button title="Sign Out" onPress={() => db.auth.signOut()} />
    </View>
  );
}

function Login() {
  const [sentEmail, setSentEmail] = useState('');
  const [email, setEmail] = useState('');
  const [code, setCode] = useState('');

  if (!sentEmail) {
    return (
      <View style={styles.container}>
        <Text style={styles.title}>Let's log you in!</Text>
        <TextInput
          placeholder="Enter your email"
          value={email}
          onChangeText={setEmail}
          style={styles.input}
        />
        <Button
          title="Send Code"
          onPress={() => {
            setSentEmail(email);
            db.auth.sendMagicCode({ email }).catch((err) => {
              Alert.alert('Uh oh', err.body?.message);
              setSentEmail('');
            });
          }}
        />
      </View>
    );
  }

  return (
    <View style={styles.container}>
      <Text style={styles.title}>Enter your code</Text>
      <Text>
        We sent an email to {sentEmail}. Check your email, and enter the code
        you see.
      </Text>
      <TextInput
        placeholder="123456..."
        value={code}
        onChangeText={setCode}
        style={styles.input}
      />
      <Button
        title="Verify Code"
        onPress={() => {
          db.auth
            .signInWithMagicCode({ email: sentEmail, code })
            .catch((err) => {
              Alert.alert('Uh oh', err.body?.message);
              setCode('');
            });
        }}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    padding: 16,
  },
  header: {
    fontSize: 24,
    fontWeight: 'bold',
  },
  title: {
    fontSize: 20,
    fontWeight: 'bold',
  },
  input: {
    borderWidth: 1,
    borderColor: '#ccc',
    padding: 8,
    marginVertical: 8,
  },
});

export default App;
```





Here's a full example of magic code auth with vanilla JavaScript. Open up your `src/main.ts` file, and replace the entirety of it with the following code:

```typescript 
import { init, type User } from '@instantdb/core';

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

const app = document.getElementById('app')!;

let sentEmail = '';

function renderApp(user: User | undefined) {
  if (user) {
    renderMain(user);
  } else {
    renderLogin();
  }
}

function renderMain(user: User) {
  app.innerHTML = `
    <div>
      <h1>Hello ${user.email}!</h1>
      <button id="sign-out">Sign out</button>
    </div>
  `;
  document.getElementById('sign-out')!.addEventListener('click', () => {
    db.auth.signOut();
  });
}

function renderLogin() {
  if (!sentEmail) {
    renderEmailStep();
  } else {
    renderCodeStep();
  }
}

function renderEmailStep() {
  app.innerHTML = `
    <div>
      <h2>Let's log you in</h2>
      <p>
        Enter your email, and we'll send you a verification code.
        We'll create an account for you too if you don't already have one.
      </p>
      <form id="email-form">
        <input
          id="email-input"
          type="email"
          placeholder="Enter your email"
          required
        />
        <button type="submit">Send Code</button>
      </form>
    </div>
  `;
  document.getElementById('email-form')!.addEventListener('submit', (e) => {
    e.preventDefault();
    const email = (document.getElementById('email-input') as HTMLInputElement)
      .value;
    sentEmail = email;
    renderLogin();
    db.auth.sendMagicCode({ email }).catch((err) => {
      alert('Uh oh: ' + err.body?.message);
      sentEmail = '';
      renderLogin();
    });
  });
}

function renderCodeStep() {
  app.innerHTML = `
    <div>
      <h2>Enter your code</h2>
      <p>
        We sent an email to <strong>${sentEmail}</strong>.
        Check your email, and paste the code you see.
      </p>
      <form id="code-form">
        <input
          id="code-input"
          type="text"
          placeholder="123456..."
          required
        />
        <button type="submit">Verify Code</button>
      </form>
    </div>
  `;
  document.getElementById('code-form')!.addEventListener('submit', (e) => {
    e.preventDefault();
    const codeInput = document.getElementById('code-input') as HTMLInputElement;
    const code = codeInput.value;
    db.auth.signInWithMagicCode({ email: sentEmail, code }).catch((err) => {
      alert('Uh oh: ' + err.body?.message);
      codeInput.value = '';
    });
  });
}

db.subscribeAuth((auth) => {
  renderApp(auth.user);
});
```

Make sure you have a `<div id="app"></div>` element in your HTML.



---

**Let's dig deeper.**

We created a login flow to handle magic code auth. Of note is `auth.sendMagicCode`
and `auth.signInWithMagicCode`.

On successful validation, Instant's backend will return a user object with a refresh token.
The client SDK will then restart the websocket connection with Instant's sync layer and provide the refresh token.

When doing queries or transactions, the refresh token will be used to hydrate `auth`
on the backend during permission checks.

On the client, auth will now be populated with a `user` -- huzzah!

## Send a Magic Code

```javascript
db.auth.sendMagicCode({ email }).catch((err) => {
  alert('Uh oh :' + err.body?.message);
  onSendEmail('');
});
```

Use `auth.sendMagicCode` to generate a magic code on instant's backend and email it to the user.

## Sign in with Magic Code

```javascript
db.auth.signInWithMagicCode({ email: sentEmail, code }).catch((err) => {
  inputEl.value = '';
  alert('Uh oh :' + err.body?.message);
});
```

You can then use `auth.signInWithMagicCode` to authenticate the user with the magic code they provided.




# Guest Auth

Let your users try your app before creating an account

Instant supports guest authentication. This allows your users to try your app before signing up and ensures they can keep all their data when they decide to create a full account with their email.

## Signing in as a Guest

Use `db.auth.signInAsGuest()` to create a new guest user. This will create a new guest user with an id, but no email address.

```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;
```

## Upgrading to a full user

When a guest user is ready to create a permanent account, you can use any of Instant's sign-in methods. The guest user will be automatically upgraded to a full user.

Here is a full example using magic code auth:

```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: 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>
      {user.isGuest && <Upgrade />}
    </div>
  );
}

function Upgrade() {
  const [sentEmail, setSentEmail] = useState('');

  return (
    <div className="flex">
      <div className="max-w-sm">
        {!sentEmail ? (
          <EmailStep onSendEmail={setSentEmail} />
        ) : (
          <CodeStep sentEmail={sentEmail} />
        )}
      </div>
    </div>
  );
}

function Login() {
  const [sentEmail, setSentEmail] = useState('');

  return (
    <div className="flex min-h-screen items-center justify-center">
      <div className="max-w-sm">
        {!sentEmail ? (
          <EmailStep onSendEmail={setSentEmail} />
        ) : (
          <CodeStep sentEmail={sentEmail} />
        )}
        <button
          onClick={() => {
            db.auth
              .signInAsGuest()
              .catch((err) => alert('Uh oh: ' + err.body?.message));
          }}
          className="mt-4 w-full bg-gray-600 px-3 py-1 font-bold text-white hover:bg-gray-700"
        >
          Try before signing up
        </button>
      </div>
    </div>
  );
}

function EmailStep({ onSendEmail }: { onSendEmail: (email: string) => void }) {
  const inputRef = React.useRef<HTMLInputElement>(null);
  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const inputEl = inputRef.current!;
    const email = inputEl.value;
    onSendEmail(email);
    db.auth.sendMagicCode({ email }).catch((err) => {
      alert('Uh oh :' + err.body?.message);
      onSendEmail('');
    });
  };
  return (
    <form
      key="email"
      onSubmit={handleSubmit}
      className="flex flex-col space-y-4"
    >
      <h2 className="text-xl font-bold">Let's log you in</h2>
      <p className="text-gray-700">
        Enter your email, and we'll send you a verification code. We'll create
        an account for you too if you don't already have one.
      </p>
      <input
        ref={inputRef}
        type="email"
        className="w-full border border-gray-300 px-3 py-1"
        placeholder="Enter your email"
        required
        autoFocus
      />
      <button
        type="submit"
        className="w-full bg-blue-600 px-3 py-1 font-bold text-white hover:bg-blue-700"
      >
        Send Code
      </button>
    </form>
  );
}

function CodeStep({ sentEmail }: { sentEmail: string }) {
  const inputRef = React.useRef<HTMLInputElement>(null);
  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const inputEl = inputRef.current!;
    const code = inputEl.value;
    db.auth.signInWithMagicCode({ email: sentEmail, code }).catch((err) => {
      inputEl.value = '';
      alert('Uh oh :' + err.body?.message);
    });
  };

  return (
    <form
      key="code"
      onSubmit={handleSubmit}
      className="flex flex-col space-y-4"
    >
      <h2 className="text-xl font-bold">Enter your code</h2>
      <p className="text-gray-700">
        We sent an email to <strong>{sentEmail}</strong>. Check your email, and
        paste the code you see.
      </p>
      <input
        ref={inputRef}
        type="text"
        className="w-full border border-gray-300 px-3 py-1"
        placeholder="123456..."
        required
        autoFocus
      />
      <button
        type="submit"
        className="w-full bg-blue-600 px-3 py-1 font-bold text-white hover:bg-blue-700"
      >
        Verify Code
      </button>
    </form>
  );
}

export default App;
```

## Handling conflicting users

If a guest user signs up with an email that is not already associated with an existing account, their user `id` remains the same, and they retain access to all data they created as a guest.

However, if a user with that email already exists, the guest user's data may need to be merged.

You can fetch the list of guest users for a user with this query:

```ts
const query = {
  $users: {
    $: {
      where: {
        linkedPrimaryUser: user.id,
      },
    },
  },
};
```

The linked guest users are also available on the user itself:

```ts
const query = {
  $users: {
    $: {
      where: {
        id: user.id,
      },
      linkedGuestUsers: {},
    },
  },
};
```

You can then query for the data owned by those guest users and transfer it to the primary account. The specific implementation will depend on your application's data model.

To enable your user to access the data stored by the guest users, you can update your rules to grant access:

```diff
{
  "todos": {
   "bind": [
    "isOwner", "data.owner == auth.id",
+   "isGuestOwner", "data.owner in auth.ref('$user.linkedGuestUsers.id')"
   ],
    "allow": {
-     "view": "isOwner",
+     "view": "isOwner || isGuestOwner",
      "create": "isOwner",
-     "update": "isOwner",
+     "update": "isOwner || isGuestOwner",
      "delete": "isOwner"
    }
  }
}
```

Here's an example of how you might transfer `todos` from a guest account to the primary user:

```ts
function App() {
  const user = db.useUser();

  useEffect(() => {
    if (user.isGuest) return;

    const transferGuestData = async () => {
      // Get the linked guest user
      const {
        data: { $users },
      } = await db.queryOnce({
        $users: {
          $: {
            where: { linkedPrimaryUser: user.id },
            limit: 1,
            order: { serverCreatedAt: desc },
          },
        },
      });
      const guestId = $users[0]?.id;
      if (!guestId) return;

      // Get the data for the guest user
      const {
        data: { todos },
      } = await db.queryOnce({
        todos: {
          $: {
            where: { owner: guestId },
          },
        },
      });
      if (!todos.length) return;

      // Update owner on all of the guest's todo entities
      const txes = todos.map((todo) =>
        db.tx.todos[todo.id].update({ owner: user.id }),
      );
      await db.transact(txes);
    };

    transferGuestData();
  }, [user]);
}
```


# Google OAuth

How to add Google OAuth to your Instant app.



Instant supports logging users in with their Google account. There are a few ways to do this: it depends on whether you are building for web or React Native.

Choose the option that sounds best to you, and the rest of the document will show you how to add Sign in with Google to your app.




**Building for Web?**






**Building for React Native?**








## Overview

There are three main steps:

1. **Google Console**: Set up your consent screen and create an Oauth client.
2. **Instant Dashboard**: Connect your Oauth client to Instant
3. **Your app**: Add some code to log in with Google!

Let's dive deeper in each step:

## 1. Set up your consent screen and create an Oauth client

Head on over to . You should be in the "Credentials" section.

**Configure your Google OAuth consent screen**

- Click "CONFIGURE CONSENT SCREEN." If you already have a consent screen, you can skip to the next step.
- Select "External" and click "CREATE".
- Add your app's name, a support email, and developer contact information. Click "Save and continue".
- No need to add scopes or test users. Click "Save and continue" for the next screens. Until you reach the "Summary" screen, click "Back to dashboard".

**Create an OAuth client for Google**

<!-- prettier-ignore-start -->



- From Google Console, click "+ CREATE CREDENTIALS"
- Select "OAuth client ID"
- Select "Web application" as the application type.

- Add `https://api.instantdb.com/runtime/oauth/callback` as an Authorized redirect URI.

- If you're testing from localhost, **add both `http://localhost`** and `http://localhost:3000` to "Authorized JavaScript origins", replacing `3000` with the port you use.
- For production, add your website's domain.

<!-- prettier-ignore-end -->

And with that you have your Oauth client!



Save your Client ID and your Client Secret -- you'll need it for the next step!







For native auth, each platform needs an Oauth Client. If you support both iOS or Android for example, you'll create two clients. Here are the steps:

- From Google Console, click "+ CREATE CREDENTIALS"
- Select "OAuth client ID"
- Select "iOS" or "Android" as the application type.
- Fill in your bundle information.

And with that you're ready!



Save your Client IDs -- you'll need it for the next step!





## 2. Connect your Oauth client to Instant



Go to the  and select the `Auth` tab for your app.

**Add your Oauth Client on Instant**

- Click "Set up Google"
- Enter your "Client ID"
- Enter your "Client Secret"
- Check "I added the redirect to Google" (make sure you actually did this!)
- Click "Add Client"

And voila, you are connected!





**Register your website with Instant**

In the `Auth` tab, add the url of the websites where you are using Instant to the Redirect Origins.
If you're testing from localhost, add `http://localhost:3000`, replacing `3000` with the port you use.
For production, add your website's domain.





Go to the  and select the `Auth` tab for your app. For each Oauth Client you created, add it to Instant:

- Click "Set up Google"
- Enter your "Client ID"
- Make sure "skip nonce checks" is enabled.
- Click "Add Client"

And voila, you are connected!



## 3. Add some code!



**Method: Google Sign in Button for Web**

We'll use . The benefit of using Google's button is that you can display your app's name in the consent screen.

There are two steps to the code:

1. Use the Sign in Button to auth with Google and get an `idToken`
2. Pass the token on to `db.auth.signInWithIdToken`, and you are logged in!

Let's do that.

**Using React**

If you're using React, the easiest way to include the Sign in Button is through the  package:

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

Once you install it, include the button, and use `db.auth.signInWithIdToken` to complete sign in. Here's a full example:

```jsx 
'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>
  );
}
```

**Not using React?**

If you're not using React or prefer to embed the button yourself, refer to  on how to create the button and load their client library

When creating your button, make sure to set the `data-ux_mode="popup"`. Your `data-callback` function should look like:

```jsx 
async function handleSignInWithGoogle(response) {
  await db.auth.signInWithIdToken({
    // Use the google client name in the Instant dashboard auth tab
    clientName: 'REPLACE_ME',
    idToken: response.credential,
    // make sure this is the same nonce you set in data-nonce
    nonce: 'REPLACE_ME',
  });
}
```





**Method: Web Redirect**

If you don't want to use the google styled buttons, you can use the redirect flow instead.

Create an authorization URL via `db.auth.createAuthorizationURL` and then use the url to create a link. Here's a full example:

```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>;
}
```

When your users clicks on the link, they'll be redirected to Google to start the OAuth flow and then back to your site.

Instant will automatically log them in to your app when they are redirected!





**Method: Expo Web Auth**

Instant comes with support for Expo's AuthSession library. To use it, you need to:

1. Set up AuthSession
2. Register your app with Instant
3. Use AuthSession to log in with Google!

Let's do that.

**Set up AuthSession**

If you haven't already, follow the AuthSession  from the Expo docs.

Next, add the following dependencies:

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

Update your app.json with your scheme:

```json 
{
  "expo": {
    "scheme": "mycoolredirect"
  }
}
```

**Register your app with Instant**

Now that you have you App Scheme, it's time to tell Instant about it.

From the  tab on the Instant dashboard, add a redirect origin of type "App scheme". For development with expo add `exp://` and your scheme, e.g. `mycoolredirect://`.



**Use AuthSession to log in with Google!**

And from here you're ready to add a login button to your expo app! Here's a full example

```jsx 
import { View, Text, Button, StyleSheet } 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 <Text>Hello {user.email}!</Text>;
}

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: 'YOUR_INSTANT_AUTH_CLIENT_NAME',
      redirectUri: makeRedirectUri(),
    },
    discovery,
  );

  return (
    <Button
      title="Log in"
      disabled={!request}
      onPress={async () => {
        try {
          const res = await promptAsync();
          if (res.type === 'error') {
            alert(res.error || 'Something went wrong');
          }
          if (res.type === 'success') {
            await db.auth
              .exchangeOAuthCode({
                code: res.params.code,
                codeVerifier: request.codeVerifier,
              })
              .catch((e) => alert(e.body?.message || 'Something went wrong'));
          } else {
          }
        } catch (e) {
          console.error(e);
        }
      }}
    ></Button>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
});

export default App;
```





**Method: Native Auth**

You can use [react-native-google-signin/google-signin](https://github.com/react-native-google-signin/google-signin), to authenticate natively on Google.

There are three steps:

1. Set up google-signin on Expo
1. Use the Sign in Button to auth with Google and get an `idToken`
1. Pass the token on to `db.auth.signInWithIdToken`, and you are logged in!

Let's do that.

**Set up google-signin on Expo**

First, let's install the package:

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

Then, follow the google-signin  to set it up with Expo.

**Use google-signin to log in with Google!**

Now you're ready to add the Google Signin button to your expo app! Here's a full example:

```jsx 
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, and sign into 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;
```






# Sign In with Apple

How to add Sign In with Apple to your Instant app.



Instant supports Sign In with Apple on the Web and in native applications.







## Step 1: Create App ID

- Navigate to [Certificates, Identifiers & Profiles](https://developer.apple.com/account/resources/identifiers/list)
- Select _Identifiers_
- Click _+_
- _Register a new identifier_ → Select _App IDs_
- _Select a type_ → Select _App_
- _Capabilities_ → _Sign In with Apple_ → Check
- Fill in _Bundle ID_ and _Description_
- Click _Register_

## Step 2: Create Services ID

- Navigate to [Services IDs](https://developer.apple.com/account/resources/identifiers/list/serviceId)
- Click _+_
- _Register a new identifier_ → Select _Services IDs_
- Fill in _Description_ and _Identifier_. You’ll need this _Identifier_ later
- Click _Register_



## Step 3: Configure Services ID (Web Popup flow)

- Select newly created Services ID
- Enable _Sign In with Apple_
- Click _Configure_
- Select _Primary App ID_ from Step 1
- To _Domains_, add your app domain (e.g. `myapp.com`)
- To _Return URLs_, add URL of your app where authentication happens (e.g. `https://myapp.com/signin`)
- Click _Continue_ → _Save_





## Step 3: Configure Services ID (Web Redirect flow)

- Select newly created Services ID
- Enable _Sign In with Apple_
- Click _Configure_
- Select _Primary App ID_ from Step 1
- To _Domains_, add `api.instantdb.com`
- To _Return URLs_, add `https://api.instantdb.com/runtime/oauth/callback`
- Click _Continue_ → _Save_

## Step 3.5: Generate Private Key (Web Redirect flow only)

- Navigate to [Keys](https://developer.apple.com/account/resources/authkeys/list)
- Click _+_
- Fill in _Name_ and _Description_
- Check _Sign in with Apple_
- Configure → select _App ID_ from Step 1
- _Continue_ → _Register_
- Download key file





## Step 3: Configure Services ID (React Native flow)

This step is not needed for Expo.


## Step 4: Register your OAuth client with Instant



- Go to the Instant dashboard and select _Auth_ tab.
- Select _Add Apple Client_
- Select unique _clientName_ (`apple` by default, will be used in `db.auth` calls)
- Fill in _Services ID_ from Step 2
- Fill in _Team ID_ from [Membership details](https://developer.apple.com/account#MembershipDetailsCard)
- Fill in _Key ID_ from Step 3.5
- Fill in _Private Key_ by copying file content from Step 3.5
- Click `Add Apple Client`



- Go to the Instant dashboard and select _Auth_ tab.
- Select _Add Apple Client_
- Select unique _clientName_ (`apple` by default, will be used in `db.auth` calls)
- Fill in _Services ID_ from Step 2
- Click `Add Apple Client`






## Step 4.5: Whitelist your domain in Instant (Web Redirect flow only)

- In Instant Dashboard, Click _Redirect Origins_ → _Add an origin_
- Add your app’s domain (e.g. `myapp.com`)





## Step 5: Add Sign In code to your app (Web Popup flow)

Add Apple Sign In library to your app:

```
https://appleid.cdn-apple.com/appleauth/static/jsapi/appleid/1/en_US/appleid.auth.js
```

Initialize with `Services ID` from Step 2:

```jsx 
AppleID.auth.init({
  clientId: '<Services ID>',
  scope: 'name email',
  redirectURI: window.location.href,
});
```

Implement `signInPopup` using `clientName` from Step 4:

```jsx 
async function signInPopup() {
  let nonce = crypto.randomUUID();

  // authenticate with Apple
  let resp = await AppleID.auth.signIn({
    nonce: nonce,
    usePopup: true,
  });

  // authenticate with Instant
  await db.auth.signInWithIdToken({
    clientName: '<clientName>',
    idToken: resp.authorization.id_token,
    nonce: nonce,
  });
}
```

Add Sign In button:

```jsx 
<button onClick={signInPopup}>Sign In with Apple</button>
```





## Step 5: Add Sign In code to your app (Web Popup flow)

Create Sign In link using `clientName` from Step 4:

```
const authUrl = db.auth.createAuthorizationURL({
  clientName: '<clientName>',
  redirectURL: window.location.href,
});
```

Add a link uses `authUrl`:

```
<a href={ authUrl }>Sign In with Apple</a>
```

That’s it!




## Step 5: Add Sign In code to your app (React Native flow)

Instant comes with support for [Expo AppleAuthentication library](https://docs.expo.dev/versions/latest/sdk/apple-authentication/).

Add dependency:

```shell 
npx expo install expo-apple-authentication
```

Update `app.json` by adding:

```json 
{
  "expo": {
    "ios": {
      "usesAppleSignIn": true
    }
  }
}
```

Go to Instant dashboard → Auth tab → Redirect Origins → Add an origin.

Add `exp://` for development with Expo.

Authenticate with Apple and then pass identityToken to Instant along with `clientName` from Step 4:

```jsx 
const [nonce] = useState('' + Math.random());
try {
  // sign in with Apple
  const credential = await AppleAuthentication.signInAsync({
    requestedScopes: [
      AppleAuthentication.AppleAuthenticationScope.FULL_NAME,
      AppleAuthentication.AppleAuthenticationScope.EMAIL,
    ],
    nonce: nonce,
  });

  // pass identityToken to Instant
  db.auth
    .signInWithIdToken({
      clientName: '<clientName>',
      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
  }
}
```

Sign out code:

```jsx 
<Button
  title="Sign Out"
  onPress={async () => {
    await db.auth.signOut();
  }}
/>
```

Full example:

```jsx 
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;
```






# GitHub OAuth

How to add GitHub OAuth to your Instant app.



Instant supports logging users in with their GitHub account. GitHub uses OAuth 2.0 for authentication, which provides a secure way for users to sign in without sharing their passwords.

Choose the option that sounds best to you, and the rest of the document will show you how to add Sign in with GitHub to your app.




**Building for Web?**





**Building for React Native?**







## Overview

There are three main steps:

1. **GitHub Developer Settings**: Create an OAuth App.
2. **Instant Dashboard**: Connect your OAuth App to Instant.
3. **Your app**: Add code to log in with GitHub!

Let's dive deeper into each step:

## 1. Create an OAuth App

1. Go to your GitHub account [Developer settings](https://github.com/settings/developers).
2. Click on "OAuth Apps" in the sidebar.
3. Click "New OAuth App" (or "Register a new application" if it's your first).
4. Fill in the application details:
   - **Application name**: Your app's name (users will see this)
   - **Homepage URL**: Your app's website
   - **Authorization callback URL**: `https://api.instantdb.com/runtime/oauth/callback`
5. Click "Register application".
6. After creation, you'll see your **Client ID**.
7. Click "Generate a new client secret" to get your **Client Secret**.

## 2. Connect your OAuth App to Instant

Go to the  and select the `Auth` tab for your app.

**Add your OAuth App on Instant**

- Click "Set up GitHub"
- Enter a unique name for your client (e.g., "github-web")
- Enter your "Client ID" from GitHub
- Enter your "Client Secret" from GitHub
- Click "Add Client"



**Register your website with Instant**

In the `Auth` tab, add the URL of the websites where you are using Instant to the Redirect Origins.
If you're testing from localhost, add `http://localhost:3000`, replacing `3000` with the port you use.
For production, add your website's domain.



And voila, you are connected!

## 3. Add some code!



**Method: Web Redirect**

Create an authorization URL via `db.auth.createAuthorizationURL` and then use the url to create a link. Here's a full example:

```jsx 
'use client';

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

const APP_ID = '__APP_ID__';

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

export default function App() {
  const url = db.auth.createAuthorizationURL({
    // Use the GitHub client name from the Instant dashboard auth tab
    clientName: 'github-web',
    redirectURL: window.location.href,
  });

  return (
    <>
      <db.SignedIn>
        <UserInfo />
      </db.SignedIn>
      <db.SignedOut>
        <Login url={url} />
      </db.SignedOut>
    </>
  );
}

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

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

When your users click on the link, they'll be redirected to GitHub to authorize your app, then back to your site.

Instant will automatically log them in to your app when they are redirected!





**Method: Expo Web Auth**

Instant comes with support for Expo's AuthSession library. To use it, you need to:

1. Set up AuthSession
2. Register your app with Instant
3. Use AuthSession to log in with GitHub!

Let's do that.

**Set up AuthSession**

If you haven't already, follow the AuthSession  from the Expo docs.

Next, add the following dependencies:

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

Update your app.json with your scheme:

```json 
{
  "expo": {
    "scheme": "mycoolredirect"
  }
}
```

**Register your app with Instant**

Now that you have your App Scheme, it's time to tell Instant about it.

From the  tab on the Instant dashboard, add a redirect origin of type "App scheme". For development with expo add `exp://` and your scheme, e.g. `mycoolredirect://`.



**Use AuthSession to log in with GitHub!**

And from here you're ready to add a login button to your expo app! Here's a full example:

```jsx 
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;
```



## Scopes

GitHub uses OAuth scopes to control access. The basic scopes Instant requests are:

- `read:user` - Read access to profile information
- `user:email` - Read access to email addresses


# LinkedIn OAuth

How to add LinkedIn OAuth to your Instant app.



Instant supports logging users in with their LinkedIn account. There are a few ways to do this: it depends on whether you are building for web or React Native.

Choose the option that sounds best to you, and the rest of the document will show you how to add Sign in with LinkedIn to your app.




**Building for Web?**





**Building for React Native?**







## Overview

There are three main steps:

1. **LinkedIn Developer Console**: Create an Oauth client.
2. **Instant Dashboard**: Connect your Oauth client to Instant
3. **Your app**: Add some code to log in with LinkedIn!

Let's dive deeper in each step:

## 1. Create an Oauth client

1. Head to the [LinkedIn developer portal](https://www.linkedin.com/developers/apps) and create a new application (or open an existing one).
2. In the **Auth** tab enable **Sign In with LinkedIn**.
3. Add the following redirect URI to your application:

```text
https://api.instantdb.com/runtime/oauth/callback
```



Save your Client ID and your Client Secret -- you'll need it for the next step!



## 2. Connect your Oauth client to Instant

Go to the  and select the `Auth` tab for your app.

**Add your Oauth Client on Instant**

- Click "Set up LinkedIn"
- Enter your "Client ID"
- Enter your "Client Secret"
- Click "Add Client"



**Register your website with Instant**

In the `Auth` tab, add the url of the websites where you are using Instant to the Redirect Origins.
If you're testing from localhost, add `http://localhost:3000`, replacing `3000` with the port you use.
For production, add your website's domain.



And voila, you are connected!

## 3. Add some code!



**Method: Web Redirect**

Create an authorization URL via `db.auth.createAuthorizationURL` and then use the url to create a link. Here's a full example:

```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 linkedin 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 LinkedIn</a>;
}
```

When your users clicks on the link, they'll be redirected to LinkedIn to start the OAuth flow and then back to your site.

Instant will automatically log them in to your app when they are redirected!





**Method: Expo Web Auth**

Instant comes with support for Expo's AuthSession library. To use it, you need to:

1. Set up AuthSession
2. Register your app with Instant
3. Use AuthSession to log in with LinkedIn!

Let's do that.

**Set up AuthSession**

If you haven't already, follow the AuthSession  from the Expo docs.

Next, add the following dependencies:

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

Update your app.json with your scheme:

```json 
{
  "expo": {
    "scheme": "mycoolredirect"
  }
}
```

**Register your app with Instant**

Now that you have you App Scheme, it's time to tell Instant about it.

From the  tab on the Instant dashboard, add a redirect origin of type "App scheme". For development with expo add `exp://` and your scheme, e.g. `mycoolredirect://`.



**Use AuthSession to log in with LinkedIn!**

And from here you're ready to add a login button to your expo app! Here's a full example

```jsx 
import { View, Text, Button, StyleSheet } 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 <Text>Hello {user.email}!</Text>;
}

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: 'YOUR_INSTANT_AUTH_CLIENT_NAME',
      redirectUri: makeRedirectUri(),
    },
    discovery,
  );

  return (
    <Button
      title="Log in"
      disabled={!request}
      onPress={async () => {
        try {
          const res = await promptAsync();
          if (res.type === 'error') {
            alert(res.error || 'Something went wrong');
          }
          if (res.type === 'success') {
            await db.auth
              .exchangeOAuthCode({
                code: res.params.code,
                codeVerifier: request.codeVerifier,
              })
              .catch((e) => alert(e.body?.message || 'Something went wrong'));
          } else {
          }
        } catch (e) {
          console.error(e);
        }
      }}
    ></Button>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
});

export default App;
```






# Clerk

How to integrate Clerk's auth flow with Instant.

Instant supports auth with Clerk.

## Setup

**Step 1: Configure Clerk**

Go to your Clerk dashboard, navigate to [`Sessions`](https://dashboard.clerk.com/last-active?path=sessions), then click the `Edit` button in the `Customize session token` section.

Add the email and email_verified claims to your session token:

```json 
{
  "email": "{{user.primary_email_address}}",
  "email_verified": "{{user.email_verified}}"
}
```

You can have additional claims as long as the `email` claim is set to `{{user.primary_email_address}}` and the `email_verified` claim is set to `{{user.email_verified}}`.

![Clerk token form](/img/docs/clerk-token-form.png)

**Step 2: Get your Clerk Publishable key**

On the Clerk dashboard, navigate to [`API keys`](https://dashboard.clerk.com/last-active?path=api-keys), then copy the `Publishable key`. It should start with `pk_`.

**Step 3: Register your Clerk Publishable key with your instant app**

Go to the Instant dashboard, navigate to the `Auth` tab and add a new clerk app with the publishable key you copied.

## Usage

Use Clerk's `getToken` helper to get a session JWT for your signed-in user. Then call Instant's `db.auth.signInWithIdToken` with the JWT and the client name you set on the Instant dashboard.

When you call `db.auth.signInWithIdToken`, Instant will verify that the JWT was signed by your Clerk app. If verified, Instant will use the email in the JWT's claims to lookup your user or create a new one and create a long-lived session. Be sure to call Instant's `db.auth.signOut` when you want to sign the user out.

Here is a full example using clerk's next.js library:

```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;
```


# Firebase Auth

How to integrate Firebase's auth flow with Instant.

Instant supports delegating auth to Firebase Auth.

## Setup

**Step 1: Get your Firebase Project ID**

On the [Firebase dashboard](https://console.firebase.google.com/), open your project and navigate to navigate to `Project Overview` > `⚙` > `Project Settings`, then copy the `Project ID`.

**Step 2: Register your Firebase Project ID with your instant app**

Go to the Instant dashboard, navigate to the `Auth` tab and add a new firebase auth app with the Project ID you copied.

## Usage

Use Firebase's `getIdToken` helper to get a JWT for your signed-in user. Then call Instant's `db.auth.signInWithIdToken` with the JWT and the client name you set on the Instant dashboard.

When you call `db.auth.signInWithIdToken`, Instant will verify that the JWT was signed by your Firebase app. If verified, Instant use the email in the JWT's claims to lookup your user or create a new one and create a long-lived session. Be sure to call Instant's `db.auth.signOut` when you want to sign the user out.

Here is a full example:

```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;
```


# Permissions

How to secure your data with Instant's Rule Language.

To secure user data, you can use Instant's Rule Language. Our rule language
takes inspiration from Rails' ActiveRecord, Google's CEL, and JSON.
Here's an example ruleset below.

<!-- prettier-ignore-start -->
```tsx 
// instant.perms.ts
import type { InstantRules } from '@instantdb/react';

const rules = {
  "todos": {
    "allow": {
      "view": "auth.id != null",
      "create": "isOwner",
      "update": "isOwner && isStillOwner",
      "delete": "isOwner",
    },
    "bind": {
      "isOwner": "auth.id != null && auth.id == data.creatorId",
      "isStillOwner": "auth.id != null && auth.id == newData.creatorId"
    }
  }
} satisfies InstantRules;

export default rules;
```
<!-- prettier-ignore-end -->

You can manage permissions via configuration files or through the Instant dashboard.

## Permissions as code

With Instant you can define your permissions in code. If you haven't already, use the [CLI](/docs/cli) to generate an `instant.perms.ts` file:

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

The CLI will guide you through picking an Instant app and generate these files for you. Once you've made changes to `instant.perms.ts`, you can use the CLI to push those changes to production:

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

## Permissions in the dashboard

For each app in your dashboard, you’ll see a permissions editor. Permissions are expressed as JSON. Each top level key represents one of your namespaces — for example `goals`, `todos`, and the like. There is also a special top-level key `attrs` for defining permissions on creating new types of namespaces and attributes.

## Namespaces

For each namespace you can define `allow` rules for `view`, `create`, `update`, `delete`, as well as special rules for fields. Rules must be boolean expressions.

If a rule is not set then by default it evaluates to true. The following three rulesets are all equivalent:

In this example we explicitly set each action for `todos` to true

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

In this example we explicitly set `view` to be true. However, all the remaining
actions for `todo` also default to true.

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

In this example we set no rules, and thus all permission checks pass.

```json
{}
```



When you start developing you probably won't worry about permissions. However, once you start shipping your app to users you will want to secure their data!



### View

`view` rules are evaluated when doing `db.useQuery`. On the backend every object
that satisfies a query will run through the `view` rule before being passed back
to the client. This means as a developer you can ensure that no matter what query
a user executes, they’ll _only_ see data that they are allowed to see.

### Create, Update, Delete

Similarly, for each object in a transaction, we make sure to evaluate the respective `create`, `update`, and `delete` rule.

Transactions will fail if a user does not have adequate permission.

### Fields

You can also define field-level permissions. For example, you may want to make the `$users` table public, but hide email addresses. Here's how you could do that:

```json
{
  "$users": {
    "allow": {
      "view": "true"
    },
    "fields": {
      "email": "auth.id == data.id"
    }
  }
}
```

### Default permissions

By default, all permissions are considered to be `"true"`. To change that, use `"$default"` key. This:

```json
{
  "todos": {
    "allow": {
      "$default": "false"
    }
  }
}
```

is equivalent to this:

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

Specific keys can override defaults:

```json
{
  "todos": {
    "allow": {
      "$default": "false",
      "view": "true"
    }
  }
}
```

You can use `$default` as the namespace:

```json
{
  "$default": {
    "allow": {
      "view": "false"
    }
  },
  "todos": {
    "allow": {
      "view": "true"
    }
  }
}
```

Finally, the ultimate default:

```json
{
  "$default": {
    "allow": {
      "$default": "false"
    }
  }
}
```

## Attrs

Attrs are a special kind of namespace for creating new types of data on the fly.
Currently we only support create rules on attrs. During development you likely don't
need to lock this rule down, but once you ship you will likely want to set this
permission to `false`

Suppose our data model looks like this

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

And we have a rules defined as

```json
{
  "attrs": { "allow": { "create": "false" } }
}
```

Then we could create goals with existing attr types:

```javascript
db.transact(db.tx.goals[id()].update({title: "Hello World"})
```

But we would not be able to create goals with new attr types:

```javascript
db.transact(db.tx.goals[id()].update({title: "Hello World", priority: "high"})
```

## CEL expressions

Inside each rule, you can write CEL code that evaluates to either `true` or `false`.

```json
{
  "todos": {
    "allow": {
      "view": "auth.id != null",
      "create": "auth.id in data.ref('creator.id')",
      "update": "!(newData.title == data.title)",
      "delete": "'joe@instantdb.com' in data.ref('users.email')"
    }
  }
}
```

The above example shows a taste of the kind of rules you can write :)

### data

`data` refers to the object you have saved. This will be populated when used for `view`, `create`, `update`, `delete` rules.

### newData

In `update`, you'll also have access to `newData`. This refers to the changes that are being made to the object.

### bind

`bind` allows you to alias logic. The following are equivalent

```json
{
  "todos": {
    "allow": {
      "create": "isOwner"
    },
    "bind": { "isOwner": "auth.id != null && auth.id == data.creatorId" }
  }
}
```

```json
{
  "todos": {
    "allow": {
      "create": "auth.id != null && auth.id == data.creatorId"
    }
  }
}
```

`bind` is useful for not repeating yourself and tidying up rules

```json
{
  "todos": {
    "allow": {
      "create": "isOwner || isAdmin"
    },
    "bind": {
      "isOwner": "auth.id != null && auth.id == data.creatorId",
      "isAdmin": "auth.email in ['joe@instantdb.com', 'stopa@instantdb.com']"
    }
  }
}
```

### ref

You can also refer to relations in your permission checks. This rule restricts
delete to only succeed on todos associated with a specific user email.

```json
{
  "todos": {
    "allow": {
      "delete": "'joe@instantdb.com' in data.ref('users.email')"
    }
  }
}
```

`ref` works on the `auth` object too. Here's how you could restrict `deletes` to users with the 'admin' role:

```json
{
  "todos": {
    "allow": {
      "delete": "'admin' in auth.ref('$user.role.type')"
    },
  },
};
```

See [managing users](/docs/users) to learn more about that.

### ruleParams

Imagine you have a `documents` namespace, and want to implement a rule like _"Only people who know my document's id can access it."_

You can use `ruleParams` to write that rule. `ruleParams` let you pass extra options to your queries and transactions.

For example, pass a `knownDocId` param to our query:

```javascript
// You could get your doc's id from the URL for example
const myDocId = getId(window.location);

const query = {
  docs: {},
};
const { data } = db.useQuery(query, {
  ruleParams: { knownDocId: myDocId }, // Pass the id to ruleParams!
});
```

Or to your transactions:

```js
db.transact(
  db.tx.docs[id].ruleParams({ knownDocId: id }).update({ title: 'eat' }),
);
```

And then use it in your permission rules:

```json
{
  "documents": {
    "allow": {
      "view": "data.id == ruleParams.knownDocId",
      "update": "data.id == ruleParams.knownDocId",
      "delete": "data.id == ruleParams.knownDocId"
    }
  }
}
```

With that, you've implemented the rule _"Only people who know my document's id can access it."_!

### request.time

The timestamp when the rules were run. You might use this in an update or create rule to ensure that a time is valid:

```json
{
  "documents": {
    "allow": {
      "update": "math.abs((request.time - timestamp(data.updatedAt)).getMinutes()) <= 1"
    }
  }
}
```

### request.origin

The origin that made the request, as a string, e.g. `https://example.com`. This may be null if the request was not made by a browser.

### request.ip

The IP address of the originating request as a string, e.g. `192.251.68.254` or `2a03:2880:2110:df07:face:b00c::1`.

### request.modifiedFields

In `create` and `update` rules, you have access to `request.modifiedFields` — a list of field names being set in the transaction. This is useful when you want to control which fields can be set by whom.

#### Restricting fields on create

You can use `request.modifiedFields` to prevent certain fields from being set on creation. For example, only admins should be able to set the `featured` field:

```json
{
  "posts": {
    "allow": {
      "create": "isAdmin || !('featured' in request.modifiedFields)"
    },
    "bind": {
      "isAdmin": "'admin' in auth.ref('$user.role.type')"
    }
  }
}
```

This allows anyone to create posts, but only admins can set the `featured` field.

#### Restricting fields on update

You might want only the owner to edit a post's title and content, but allow anyone to increment a `likes` counter:

```json
{
  "posts": {
    "allow": {
      "update": "isOwner || onlyModifiesLikes"
    },
    "bind": {
      "isOwner": "auth.id == data.ownerId",
      "onlyModifiesLikes": "request.modifiedFields.all(field, field in ['likes'])"
    }
  }
}
```

This rule allows the owner to update any field, but non-owners can only update the `likes` field.

Since a transaction can update multiple fields at once, `request.modifiedFields` is a list. We use `.all(field, field in ['likes'])` to check that _every_ field being modified is in our allowed list. This prevents someone from sneaking in an unauthorized field change alongside an allowed one.

You can allow multiple public fields:

```json
{
  "posts": {
    "allow": {
      "update": "isOwner || onlyModifiesPublicFields"
    },
    "bind": {
      "isOwner": "auth.id == data.ownerId",
      "onlyModifiesPublicFields": "request.modifiedFields.all(field, field in ['likes', 'viewCount'])"
    }
  }
}
```

You can combine `modifiedFields` checks with other conditions. For example, require users to be logged in before updating public fields:

```json
{
  "posts": {
    "allow": {
      "update": "isOwner || (isLoggedIn && onlyModifiesLikes)"
    },
    "bind": {
      "isOwner": "auth.id == data.ownerId",
      "isLoggedIn": "auth.id != null",
      "onlyModifiesLikes": "request.modifiedFields.all(field, field in ['likes'])"
    }
  }
}
```

You can also add value validation that only runs when a specific field is being modified. Use `'fieldName' in request.modifiedFields` to check if a field is being changed:

```json
{
  "posts": {
    "allow": {
      "update": "isOwner || (onlyModifiesPublicFields && likesValid && titleValid)"
    },
    "bind": {
      "isOwner": "auth.id == data.ownerId",
      "onlyModifiesPublicFields": "request.modifiedFields.all(field, field in ['likes', 'title'])",
      "likesValid": "!('likes' in request.modifiedFields) || newData.likes >= 0",
      "titleValid": "!('title' in request.modifiedFields) || size(newData.title) <= 100"
    }
  }
}
```

This rule allows non-owners to update `likes` and `title`, but only if `likes` is non-negative and `title` is at most 100 characters. The `!('field' in request.modifiedFields) || condition` pattern means "either this field isn't being modified, or if it is, it must satisfy the condition."

**Here are some more patterns**

If you want to: access a document and _all related comments_ by one `knownDocId`:

```json
{
  "docs": {
    "view": "data.id == ruleParams.knownDocId"
  },
  "comment": {
    "view": "ruleParams.knownDocId in data.ref('parent.id')"
  }
}
```

Or, if you want to allow multiple documents:

```js
db.useQuery(..., { knownDocIds: [id1, id2, ...] })
```

```json
{
  "docs": {
    "view": "data.id in ruleParams.knownDocIds"
  }
}
```

To create a “share links” feature, where you have multiple links to the same doc, you can create a separate namespace:

```json
{
  "docs": {
    "view": "ruleParams.secret in data.ref('docLinks.secret')"
  }
}
```

Or if you want to separate “view links” from “edit links”, you can use two namespaces like this:

```json
{
  "docs": {
    "view": "hasViewerSecret || hasEditorSecret",
    "update": "hasEditorSecret",
    "delete": "hasEditorSecret",
    "bind": {
      "hasViewerSecret": "ruleParams.secret in data.ref('docViewLinks.secret')",
      "hasEditorSecret": "ruleParams.secret in data.ref('docEditLinks.secret')"
    }
  }
}
```


# Managing users

How to manage users in your Instant app.

## See users in your app

You can manage users in your app using the `$users` namespace. This namespace is
automatically created when you create an app.

You'll see the `$users` namespace in the `Explorer` tab with all
the users in your app!

## Querying users

The `$users` namespace can be queried like any normal namespace. However, we've
set some default permissions so that only a logged-in user can view their own
data.

```javascript
// instant.perms.ts
import type { InstantRules } from "@instantdb/react";

const rules = {
  $users: {
    allow: {
      view: 'auth.id == data.id',
      create: 'false',
      delete: 'false',
      update: 'false',
    },
  },
} satisfies InstantRules;

export default rules;
```

Since `$users` is a managed namespace, you can override `view` and `update` rules, but not `create` or `delete`. These are handled by the Instant backend.

## Sharing user data

If you want to make the users table public, you can always change the `view` permission. If you do this, be sure to write an appropriate `field` permission on `emails` so that those columns don't leak.

```javascript
// instant.perms.ts
import type { InstantRules } from "@instantdb/react";

const rules = {
  $users: {
    allow: {
      view: 'true', // anyone can see users
      create: 'false',
      delete: 'false',
      update: 'false',
    },
    fields: {
      email: "auth.id == data.id" // but only the logged in user can see their own email.
    }
  },
} satisfies InstantRules;

export default rules;
```

## Adding properties

You can add optional properties on the `$users` table. Here is an example of a schema for a todo app where users have nicknames and roles:

```javascript
// instant.schema.ts
import { i } from '@instantdb/react';

const _schema = i.schema({
  entities: {
    $users: i.entity({
      email: i.any().unique().indexed(),
      nickname: i.string().optional(), // Users now have a `nickname` property
    }),
    roles: i.entity({
      type: i.string().indexed(),
    }),
    todos: i.entity({
      text: i.string(),
      completed: i.boolean(),
    }),
  },
  links: {
    userRoles: {
      forward: { on: '$users', has: 'many', label: 'roles' },
      reverse: { on: 'roles', has: 'many', label: 'users' },
    },
    todoOwner: {
      forward: { on: 'todos', has: 'one', label: 'owner' },
      reverse: { on: '$users', has: 'many', label: 'todos'},
    },
  },
});

// This helps TypeScript display nicer intellisense
type _AppSchema = typeof _schema;
interface AppSchema extends _AppSchema {}
const schema: AppSchema = _schema;

export type { AppSchema };
export default schema;
```

### Links

We created two links `userRoles`, `todoOwner`:

```typescript
// instant.schema.ts
import { i } from '@instantdb/react';

const _schema = i.schema({
  // ..
  links: {
    userRoles: {
      forward: { on: '$users', has: 'many', label: 'roles' },
      reverse: { on: 'roles', has: 'many', label: 'users' },
    },
    todoOwner: {
      forward: { on: 'todos', has: 'one', label: 'owner' },
      reverse: { on: '$users', has: 'many', label: 'todos' },
    },
  },
});
```

Notice that none of the links are required. You can't require links for `$users`.

### Attributes

Now look at the `nickname` attribute we just added:

```typescript
// instant.schema.ts
import { i } from '@instantdb/react';

const _schema = i.schema({
  entities: {
    $users: i.entity({
      email: i.any().unique().indexed(),
      nickname: i.string().optional(), // Users now have a `nickname` property
    }),
  },
  // ...
});
```

Note that `nickname` is optional too. Custom columns on `$users` have to be optional.

---

Once done, you can include user information in the client like so:

```javascript
// Creates a todo and links the current user as an owner
const addTodo = (newTodo, currentUser) => {
  const newId = id();
  db.transact(
    db.tx.todos[newId]
      .update({ text: newTodo, completed: false })
      // Link the todo to the user with the `owner` label we defined in the schema
      .link({ owner: currentUser.id }),
  );
};

// Creates or updates a user profile with a nickname and links it to the
// current user
const updateNick = (newNick, currentUser) => {
  db.transact([db.tx.$users[currentUser.id].update({ nickname: newNick })]);
};
```

At the moment you can only use `transact` to update the custom properties you added. Changing default columns like `email` would cause the transaction to fail.

## User permissions

You can reference the `$users` namespace in your permission rules just like a
normal namespace. For example, you can restrict a user to only update their own
todos like so:

```javascript
export default {
  // users perms...
  todos: {
    allow: {
      // owner is the label from the todos namespace to the $users namespace
      update: "auth.id in data.ref('owner.id')",
    },
  },
};
```

You can also traverse the `$users` namespace directly from the `auth` object via
`auth.ref`. When using `auth.ref` the arg must start with `$user`. Here's the
equivalent rule to the one above using `auth.ref`:

```javascript
export default {
  // users perms...
  todos: {
    allow: {
      // We traverse the users links directly from the auth object
      update: "data.id in auth.ref('$user.todos.id')",
    },
  },
};
```

By creating links to `$users` and leveraging `auth.ref`, you can expressively build
more complex permission rules.

```javascript
export default {
  // users perms...
  todos: {
    bind: {
      isAdmin: "'admin' in auth.ref('$user.roles.type')",
      isOwner: "data.id in auth.ref('$user.todos.id')",
    },
    allow: {
      // We traverse the users links directly from the auth object
      update: 'isAdmin || isOwner',
    },
  },
};
```


# Presence, Cursors, and Activity

How to add ephemeral features like presence and cursors to your Instant app.

Sometimes you want to show real-time updates to users without persisting the
data to your database. Common scenarios include:

- Shared cursors in a collaborative whiteboard like Figma
- Who's online in a document editor like Google Docs
- Typing indicators in chat apps like Discord
- Live reactions in a video streaming app like Twitch

Instant provides three primitives for quickly building these ephemeral experiences: rooms, presence, and topics.

**Rooms**

A room represents a temporary context for realtime events. Users in the same room will receive updates from every other user in that room.

**Presence**

Presence is an object that each peer shares with every other peer. When a user updates their presence, it's instantly replicated to all users in that room. Presence persists throughout the remainder of a user's connection, and is automatically cleaned up when a user leaves the room.

You can use presence to build features like "who's online." Instant's cursor and typing indicator are both built on top of the presence API.

**Topics**

Topics have "fire and forget" semantics, and are better suited for data that doesn't need any sort of persistence. When a user publishes a topic, a callback is fired for every other user in the room listening for that topic.

You can use topics to build features like "live reactions." The real-time emoji button panel on Instant's homepage is built using the topics API.

**Transact vs. Ephemeral**

You may be thinking when would I use `transact` vs `presence` vs `topics`? Here's a simple breakdown:

- Use `transact` when you need to persist data to the db. For example, when a user sends a message in a chat app.
- Use `presence` when you need to persist data in a room but not to the db. For example, showing
  who's currently viewing a document.
- Use `topics` when you need to broadcast data to a room, but don't need to persist it. For example, sending a live reaction to a video stream.

## Setup

To obtain a room reference, call `db.room(roomType, roomId)`

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

// Instant app
const APP_ID = '__APP_ID__';

// db will export all the presence hooks you need!
const db = init({ appId: APP_ID });

// Specifying a room type and room id gives you the power to
// restrict sharing to a specific room. However you can also just use
// `db.room()` to share presence and topics to an Instant generated default room
const roomId = 'hacker-chat-room-id';
const room = db.room('chat', roomId);
```

## Typesafety

By default rooms accept any kind of data. However, you can enforce typesafety with a schema:

```typescript
import { init } from '@instantdb/react';
import schema from '../instant.schema.ts';

// Instant app
const APP_ID = '__APP_ID__';

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

const roomId = 'hacker-chat-room-id';
// The `chat` room is typed automatically from schema!
const room = db.room('chat', roomId);
```

Here's how we could add typesafety to our `chat` rooms:

```typescript
// instant.schema.ts

import { i } from '@instantdb/core';

const _schema = i.schema({
  // ...
  rooms: {
    // 1. `chat` is the `roomType`
    chat: {
      // 2. Choose what presence looks like here
      presence: i.entity({
        name: i.string(),
        status: i.string(),
      }),
      topics: {
        // 3. You can define payloads for different topics here
        sendEmoji: i.entity({
          emoji: i.string(),
        }),
      },
    },
  },
});

// This helps TypeScript display better intellisense
type _AppSchema = typeof _schema;
interface AppSchema extends _AppSchema {}
const schema: AppSchema = _schema;

export type { AppSchema };
export default schema;
```

Once you've updated your schema, you'll start seeing types in your intellisense:



## Presence

One common use case for presence is to show who's online.

Instant's `usePresence` is similar in feel to `useState`. It returns an object containing the current user's presence state, the presence state of every other user in the room, and a function (`publishPresence`) to update the current user's presence. `publishPresence` is similar to React's `setState`, and will merge the current and new presence objects.

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

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

const room = db.room('chat', 'hacker-chat-room-id');
const randomId = Math.random().toString(36).slice(2, 6);
const user = {
  name: `User#${randomId}`,
};

function App() {
  const {
    user: myPresence,
    peers,
    publishPresence,
  } = db.rooms.usePresence(
    room,
    // Publish your presence when you join the room
    { initialPresence: { name: user.name } },
  );

  // Update your presence when your name changes
  useEffect(() => {
    publishPresence({ name: user.name });
  }, [user.name]);

  if (!myPresence) {
    return <p>App loading...</p>;
  }

  return (
    <div>
      <h1>Who's online?</h1>
      <p>You are: {myPresence.name}</p>
      <h2>Others:</h2>
      <ul>
        {/* Loop through all peers and render their names. Peers will have the
          same properties as what you publish to the room. In this case, `name`
          is the only property we're publishing. Use RoomSchema to get type
          safety for your presence object.
      */}
        {Object.entries(peers).map(([peerId, peer]) => (
          <li key={peerId}>{peer.name}</li>
        ))}
      </ul>
    </div>
  );
}
```

`usePresence` accepts a second parameter to select specific slices of the user's presence object.

```typescript
const room = db.room('chat', 'hacker-chat-room-id');

// We only return the `status` value for each peer
// We will _only_ trigger an update when a user's `status` value changes
const { user, peers, publishPresence } = db.rooms.usePresence(room, {
  keys: ['status'],
});
```

You may also specify an array of `peers` and a `user` flag to further constrain the output. If you wanted a "write-only" hook, it would look like this:

```typescript
// Will not trigger re-renders on presence changes
const room = db.room('chat', 'hacker-chat-room-id');

const { publishPresence } = db.rooms.usePresence(room, {
  peers: [],
  user: false,
});
```

## Topics

Instant provides 2 hooks for sending and handling events for a given topic. `usePublishTopic` returns a function you can call to publish an event, and `useTopicEffect` will be called each time a peer in the same room publishes a topic event.

Here's a live reaction feature using topics. You can also play with it live on [our recipes page](https://www.instantdb.com/recipes?#5-reactions)

```tsx 
'use client';

import { init } from '@instantdb/react';
import { RefObject, createRef, useRef } from 'react';

// Instant app
const APP_ID = '__APP_ID__';

// Set up room schema
const emoji = {
  fire: '🔥',
  wave: '👋',
  confetti: '🎉',
  heart: '❤️',
} as const;

type EmojiName = keyof typeof emoji;

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

const room = db.room('main');

export default function InstantTopics() {
  // Use publishEmoji to broadcast to peers listening to `emoji` events.
  const publishEmoji = db.rooms.usePublishTopic(room, 'emoji');

  // Use useTopicEffect to listen for `emoji` events from peers
  // and animate their emojis on the screen.
  db.rooms.useTopicEffect(
    room,
    'emoji',
    ({ name, directionAngle, rotationAngle }) => {
      if (!emoji[name]) return;

      animateEmoji(
        { emoji: emoji[name], directionAngle, rotationAngle },
        elRefsRef.current[name].current,
      );
    },
  );

  const elRefsRef = useRef<{
    [k: string]: RefObject<HTMLDivElement>;
  }>(refsInit);

  return (
    <div className={containerClassNames}>
      <div className="flex gap-4">
        {emojiNames.map((name) => (
          <div className="relative" key={name} ref={elRefsRef.current[name]}>
            <button
              className={emojiButtonClassNames}
              /* We sent an emoji! Let's animate and broadcast it! */
              onClick={() => {
                const params = {
                  name,
                  rotationAngle: Math.random() * 360,
                  directionAngle: Math.random() * 360,
                };

                /* Animate the emoji on our screen */
                animateEmoji(
                  {
                    emoji: emoji[name],
                    rotationAngle: params.rotationAngle,
                    directionAngle: params.directionAngle,
                  },
                  elRefsRef.current[name].current,
                );

                /* Broadcast our emoji to our peers! */
                publishEmoji(params);
              }}
            >
              {emoji[name]}
            </button>
          </div>
        ))}
      </div>
    </div>
  );
}

// Below are helper functions and styles used to animate the emojis

const emojiNames = Object.keys(emoji) as EmojiName[];

const refsInit = Object.fromEntries(
  emojiNames.map((name) => [name, createRef<HTMLDivElement>()]),
);

const containerClassNames =
  'flex h-screen w-screen items-center justify-center overflow-hidden bg-gray-200 select-none';

const emojiButtonClassNames =
  'rounded-lg bg-white p-3 text-3xl shadow-lg transition duration-200 ease-in-out hover:-translate-y-1 hover:shadow-xl';

function animateEmoji(
  config: { emoji: string; directionAngle: number; rotationAngle: number },
  target: HTMLDivElement | null,
) {
  if (!target) return;

  const rootEl = document.createElement('div');
  const directionEl = document.createElement('div');
  const spinEl = document.createElement('div');

  spinEl.innerText = config.emoji;
  directionEl.appendChild(spinEl);
  rootEl.appendChild(directionEl);
  target.appendChild(rootEl);

  style(rootEl, {
    transform: `rotate(${config.directionAngle * 360}deg)`,
    position: 'absolute',
    top: '0',
    left: '0',
    right: '0',
    bottom: '0',
    margin: 'auto',
    zIndex: '9999',
    pointerEvents: 'none',
  });

  style(spinEl, {
    transform: `rotateZ(${config.rotationAngle * 400}deg)`,
    fontSize: `40px`,
  });

  setTimeout(() => {
    style(directionEl, {
      transform: `translateY(40vh) scale(2)`,
      transition: 'all 400ms',
      opacity: '0',
    });
  }, 20);

  setTimeout(() => rootEl.remove(), 800);
}

function style(el: HTMLElement, styles: Partial<CSSStyleDeclaration>) {
  Object.assign(el.style, styles);
}
```

## Cursors and Typing Indicators (React only)

We wanted to make adding real-time features to your apps as simple as possible, so we shipped our React library with 2 drop-in utilities: `Cursors` and `useTypingIndicator`.

### Cursors

Adding multiplayer cursors to your app is as simple as importing our `<Cursors>` component!

```tsx 
'use client';

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

// Instant app
const APP_ID = '__APP_ID__';

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

const room = db.room('chat', 'main');

export default function App() {
  return (
    <Cursors room={room} className="h-full w-full" userCursorColor="tomato">
      <div style={{ width: '100vw', height: '100vh' }}>
        Open two tabs, and move your cursor around!
      </div>
    </Cursors>
  );
}
```

You can provide a `renderCursor` function to return your own custom cursor component.

```tsx
<Cursors
  room={room}
  className="cursors"
  userCursorColor="papayawhip"
  renderCursor={renderCoolCustomCursor}
/>
```

You can render multiple cursor spaces. For instance, imagine you're building a screen with multiple tabs. You want to only show cursors on the same tab as the current user. You can provide each `<Cursors />` element with their own `spaceId`.

```tsx
<Tabs>
  {tabs.map((tab) => (
    <Tab>
      <Cursors room={room} spaceId={`tab-${tab.id}`} className="tab-cursor">
        {/* ... */}
      </Cursors>
    </Tab>
  ))}
</Tabs>
```

### Typing indicators

`useTypingIndicator` is a small utility useful for building inputs for chat-style apps. You can use this hook to show things like "<user> is typing..." in your chat app.

```tsx 
'use client';

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

// Instant app
const APP_ID = '__APP_ID__';

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

const randomId = Math.random().toString(36).slice(2, 6);
const user = {
  name: `User#${randomId}`,
};

const room = db.room('chat', 'hacker-chat-room-id');

export default function InstantTypingIndicator() {
  // 1. Publish your presence in the room.
  db.rooms.useSyncPresence(room, user);

  // 2. Use the typing indicator hook
  const typing = db.rooms.useTypingIndicator(room, 'chat');

  const onKeyDown = (e) => {
    // 3. Render typing indicator
    typing.inputProps.onKeyDown(e);

    // 4. Optionally run your own onKeyDown logic
    if (e.key === 'Enter' && !e.shiftKey) {
      e.preventDefault();
      console.log('Message sent:', e.target.value);
    }
  };

  return (
    <div className="flex h-screen gap-3 p-2">
      <div key="main" className="flex flex-1 flex-col justify-end">
        <textarea
          onBlur={typing.inputProps.onBlur}
          onKeyDown={onKeyDown}
          placeholder="Open two tabs and start typing..."
          className="w-full rounded-md border-gray-300 p-2 text-sm"
        />
        <div className="truncate text-xs text-gray-500">
          {typing.active.length ? typingInfo(typing.active) : <>&nbsp;</>}
        </div>
      </div>
    </div>
  );
}

function typingInfo(users) {
  if (users.length === 0) return null;
  if (users.length === 1) return `${users[0].name} is typing...`;
  if (users.length === 2)
    return `${users[0].name} and ${users[1].name} are typing...`;

  return `${users[0].name} and ${users.length - 1} others are typing...`;
}
```

## PresencePeer Type

When working with presence, you can use `PresencePeer` for typing `user` and `peers`
values returned from `db.rooms.usePresence`.

```typescript
import { PresencePeer } from '@instantdb/react';
import { AppSchema } from '../instant.schema.ts';
import { db } from '../lib/db.ts';

type ChatPeer = PresencePeer<AppSchema, 'chat'>;
// Result: { peerId: string; avatar: string; name: string }

const room = db.room('chat')

function UserAvatar({ peer }: { peer: ChatPeer }) {
  return (
    <div>
      <img src={peer.avatar} alt={peer.name} />
    </div>
  );
}

function OnlineAvatars({ name, avatar }: { name: string; avatar: string }) {
  // Subcribe and publish initial presence
  const { user: myPresence, peers } = db.rooms.usePresence(room, {
    initialPresence: { name, avatar },
  });

  // Render my avatar and all peer avatars
  return (
    <div>
      {myPresence && <UserAvatar key={myPresence.peerId} peer={myPresence} />}
      {Object.values(peers).map((peer: ChatPeer) => (
        <UserAvatar key={peer.peerId} peer={peer} />
      ))}
    </div>
  );
}
```


# Instant CLI

How to use the Instant CLI to manage schema and permissions.

The Instant CLI was designed to drive your Instant application entirely from a project's codebase. You can create apps, define your data model, and update your permissions, **all through your terminal**.

## Login

To get started, you need to log in to your Instant account. You can do this by running:

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

This will open a browser window where you can authenticate with your Instant account. Once authenticated you'll be able to run commands that interact with your Instant apps!

## Logout

To log out of your Instant account and remove your authentication token from your local device, run:

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

This will clear your stored credentials. You'll need to login again to interact with your Instant apps.

## Init

After logging in, head on over to your project's root repository, and write:

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

This will guide you through picking an Instant app and generate two files for you:

- `instant.schema.ts` defines your application's data model.
- `instant.perms.ts` defines your permission rules.

To learn how to change `instant.schema.ts`, check our [Modeling Data](/docs/modeling-data). For `instant.perms.ts`, check out the [permissions](/docs/permissions) page.

## Push

When you're ready to publish your changes to `instant.schema.ts`, run:

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

This will evaluate your schema, compare it with production, and migrate your data model.

Similarly, when you change `instant.perms.ts`, you can run:

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

## Renaming fields

When you rename an attribute or link in your `instant.schema.ts` and push, the CLI needs to know whether you intend to **rename** the existing field or **delete** the old one and **create** a new one. By default, `push` will prompt you interactively:

```
Is posts.creator created or renamed from another attr?
  ~ posts.author › posts.creator    rename attr
  + posts.creator                   create attr
```

Use the arrow keys to select whether the field is a rename or a new creation.

### Renaming in CI

If you're running `push` in a non-interactive environment (e.g. CI), you can pass the `--rename` flag to specify renames explicitly:

```shell
npx instant-cli@latest push schema --rename posts.author:posts.creator
```

The format is `oldName:newName`. You can rename multiple fields at once:

```shell
npx instant-cli@latest push schema --rename posts.author:posts.creator stores.owner:stores.manager
```

This is especially useful when combined with `--yes` to skip confirmation prompts:

```shell
npx instant-cli@latest push schema --yes --rename posts.author:posts.creator
```

## Pull

Sometimes, you change your schema or rules from your Explorer. If you want to `pull` the latest version of schema and perms for production, write:

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

This will generate new `instant.schema.ts` and `instant.perms.ts` files, based on your production state.

## App ID

Whenever you run a CLI command, we look up your app id. You can either provide an app id as an option:

```shell
  npx instant-cli@latest init --app $MY_APP_ID
```

Or store it in your `.env` file:

```yaml
INSTANT_APP_ID=*****
```

As a convenience, apart from `INSTANT_APP_ID`, we also check for:

- `NEXT_PUBLIC_INSTANT_APP_ID` for next apps,
- `PUBLIC_INSTANT_APP_ID` for svelte apps,
- `VITE_INSTANT_APP_ID` for vite apps
- `NUXT_PUBLIC_INSTANT_APP_ID` for nuxt apps
- `EXPO_PUBLIC_INSTANT_APP_ID` for expo apps

## Where to save files

By default, Instant will search for your `instant.schema.ts` and `instant.perms.ts` file in:

1. The `root` directory: `./`
2. The `src` directory: `./src`
3. The `app` directory: `./app`

If you'd like to save them in a custom location, you can set the following environment variables:

- `INSTANT_SCHEMA_FILE_PATH` sets the location for your `instant.schema.ts` file.
- `INSTANT_PERMS_FILE_PATH` sets the location for your `instant.perms.ts` file.

```yaml
# in your .env file
INSTANT_SCHEMA_FILE_PATH=./src/db/instant.schema.ts
INSTANT_PERMS_FILE_PATH=./src/db/instant.perms.ts
```

## Authenticating in CI

In CI or similar environments, you may want to handle authentication without having to go through a web-based validation step each time.

In these cases, you can provide a `INSTANT_CLI_AUTH_TOKEN` environment variable.

To obtain a token for later use, run:

```shell 
npx instant-cli@latest login -p
```

Instead of saving the token to your local device, the CLI will print it to your console. You can copy this token and provide it as `INSTANT_CLI_AUTH_TOKEN` later in your CI tool.

## Init without creating files

Sometimes you want to create an Instant app without generating `instant.schema.ts` and `instant.perms.ts` or modifying your .env files. You can do this by running:

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

You can also make ephemeral apps that will clean up themselves after >24 hours
via the `--temp` flag:

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

You can also pipe the output of this command to `jq` to extract the app information for use in scripts:

```shell 
output=$(npx instant-cli@latest init-without-files --title "Hello World" --temp)
if echo "$output" | jq -e '.error' > /dev/null; then
  echo "Error: $(echo "$output" | jq -r '.error')"
  exit 1
fi
appId=$(echo "$output" | jq -r '.appId')
adminToken=$(echo "$output" | jq -r '.adminToken')
```


# Devtool

Use the Instant devtool to inspect your app in development.

When you load your app in development, you'll notice a little "Instant" Icon show up:



This is your handy `devtool` shortcut. Once you click it, you'll see a widget that lets you make changes to your app.

Use the `Explorer` to change up your data and schema:



Or the `Sandbox` to try out different queries and transactions:



## Changing Positions

You can choose where to position your devtool as well. Pass in the `devtool` configuration in `init`:

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

import schema from '../instant.schema.ts';

const db = init({
  appId: process.env.NEXT_PUBLIC_INSTANT_APP_ID!,
  schema,
  devtool: {
    position: 'bottom-right',
  },
});
```

You can set `bottom-left`, `top-left`, `top-right`, `bottom-right`.

## Custom Hosts

By default, the devtool only shows up on `localhost`. But you can decide which hosts to show it on too. Pass in the `allowedHosts` option:

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

import schema from '../instant.schema.ts';

const db = init({
  appId: process.env.NEXT_PUBLIC_INSTANT_APP_ID!,
  schema,
  devtool: {
    allowedHosts: ['localhost', 'site.local'],
  },
});
```

## Disabling the devtool

If you would like to hide the devtool completely, you can add `devtool: false` in `init`:

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

import schema from '../instant.schema.ts';

const db = init({
  appId: process.env.NEXT_PUBLIC_INSTANT_APP_ID!,
  schema,
  devtool: false,
});
```

## Shortcuts

To quickly toggle the window, you can use the shortcut `ctrl` + `shift` + `0` (zero).

## Feedback?

If you have any feedback, let us know on [Discord](https://discord.com/invite/VU53p7uQcE)


# Platform API

Spin up Instant apps on demand and manage schema with the Platform API.

You can use Instant to programmatically create apps, push schemas and manage permissions. This is particularly powerful in two scenarios:

- **App Builders**: If you're an app builder, you can give your customers a backend. It takes only an hour to set up the platform, and every app your users create gets a full backend as a result. LLMs are great at using Instant: they can make more progress with fewer tokens and fewer mistakes.
- **Software teams**: If you're a software team you can improve your development workflows: create apps for different pull requests, or spin up temporary apps for tests.

In this document, we'll show you:

1. The tools at your disposal
2. How to create temporary apps
3. How to create long-lived apps
4. How to manage schemas and permissions

Let's get into it!

## CLI & SDK

To manage apps you have two main tools at your disposal.

You can either use the Instant CLI:

```bash
npx instant-cli
```

Or if you are running a backend server, the Platform SDK:

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

Let's see how to use them.

## Temporary Apps

First things first, let's create a temporary app.

A temporary app is an Instant app that deletes itself in 2 weeks. You can use them to run quick experiments or spin apps up for tests.

You don't need authenticate to create temporary apps, so they're a great way to get a sense of our tools.

**Here's how to make a temporary app with CLI:**

```bash
npx instant-cli init-without-files --title my-new-app --temp
```

And voila, you have a temporary app:

```bash
Successfully created new app!

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

**And here's how to make a temporary app with the Platform SDK:**

```typescript
import { PlatformApi, i } from '@instantdb/platform';

const api = new PlatformApi({});

const schema = i.schema({
  entities: {
    todos: i.entity({
      title: i.string().indexed(),
      done: i.boolean(),
    }),
  },
});

const perms = {
  todos: {
    allow: {
      $default: 'true',
    },
  },
};

const app = await api.createTemporaryApp({
  title: 'my-new-app',
  schema: schema,
  rules: { code: perms },
});

console.log('app ->', app);
```

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

You can use this app `id` and `adminToken` in Instant SDKs.

Temporary apps are great, but they only last 2 weeks. What if you want to make apps that last forever?

## Long-lived apps

To create long-lived apps, you'll need to authenticate first.

### Authentication for creating apps

You have two options for authenticate and create long-lived apps:

**Option 1: Personal Access Tokens**

The quickest way to get started is to create a Personal Access Token. You can create Personal Access Tokens by going to to user settings in "Dashboard -> Settings -> New Accesss Token". Here's a direct [link](https://www.instantdb.com/dash/user-settings).

Once you click "New Access Token", you'll get a token that this:

```bash
per_xxx11x1xxx1xx1x11x1x1111xxx1xx11x11xxxx1x1x1x1111xxx11111xxx111x
```

When you use this token to create apps, they will get associated to the account where you created the token.

**Option 2: Let users Sign in with Instant**

Alternatively, you can create a "Sign in with Instant" button in your app. This button would let end-users provide their own Instant accounts, and give you permissions to manage apps on their behalf.

To do this, you can use the Platform SDK and set up Oauth. Follow the tutorial in the [Platform Oauth Guide](https://github.com/instantdb/instant/tree/main/client/packages/platform#oauth-flow) to see how to do that.

When you're done and a user clicks "Sign in with Instant" in your app, you'll get a token that looks like this:

```bash
prt_xxx11x1xxx1xx1x11x1x1111xxx1xx11x11xxxx1x1x1x1111xxx11111xxx111x
```

When you use this token to create apps, they will get associated to that user's account.

### Create long-lived apps

Now that we have auth tokens, let's use them to create an app.

**To create a long-lived app with the CLI:**

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

Pretty nice!

**And similarily, for the platform API:**

```javascript
import { PlatformApi } from '@instantdb/platform';

const api = new PlatformApi({
  auth: { token: 'YOUR_TOKEN' } })
});

const app = await api.createApp({
  title: 'my-new-app'
})
```

With that, you'll have long-lived apps!

## Managing schemas and permissions

Now that you have an app, you can change schemas and permissions too.

**To change schemas and perms with the CLI:**

If you are using the CLI, you'll have your `instant.schema.ts` and `instant.perms.ts` files in your directory. Run the [standard](/docs/cli) CLI push command with your token:

```ts
// src/instant.schema.ts
import { i } from '@instantdb/react';

const schema = i.schema({
  entities: {
    todos: i.entity({
      title: i.string().indexed(),
      done: i.boolean(),
      completedAt: i.date().optional(),
    }),
  },
});
```

```bash
npx instant-cli push schema --token YOUR_TOKEN
```

**To change schemas and perms with the platform SDK:**

For the platform SDK, you can use the corresponding `schemaPush` command.

Here's a snippet for schema push:

```typescript
import { PlatformApi, i } from '@instantdb/platform';

const schema = i.schema({
  entities: {
    todos: i.entity({
      title: i.string().indexed(),
      done: i.boolean(),
      completedAt: i.date().optional(),
    }),
  },
});

await api.schemaPush(YOUR_APP_ID, {
  overwrite: true,
  schema: schema,
  renames: ['todos.name:todos.title'],
});
```

To see more examples, check out the [Platform SDK reference](https://github.com/instantdb/instant/tree/main/client/packages/platform#making-api-requests).

### Note: scoping tokens per app

You can always use the access tokens you made to change schemas and perms, but you may not want always want too. Particularily with the CLI.

For example, if you're an app builder, you may create a sandbox that lets an agent change schemas and permissions. If you gave the agent access to these tokens, they could change _any_ app associated with the token.

What you really want in those cases is to get a token _scoped_ to a particular app.

**You can use admin tokens this way.** Simply provide the admin token as auth, and the CLI will only have access to change schema and perms just on that app.

```bash
npx instant-cli push schema --token YOUR_ADMIN_TOKEN
```

### Questions?

This is a living document. If you have any questions, reach out to us on [Discord](https://discord.com/invite/VU53p7uQcE)!


# Explorer Component

Use the Explorer Component in your own apps

The explorer page from the Instant Dashboard is available as an installable React component that you can use in your own apps. This is especially useful if you're building **a platform or app builder** powered by Instant

```tsx
import './App.css';
import { Explorer, Toaster } from '@instantdb/components';

function App() {
  return (
    <>
      <Explorer
        className="h-full"
        useShadowDOM={false}
        darkMode={false}
        appId={import.meta.env.VITE_INSTANT_APP_ID}
        adminToken={import.meta.env.VITE_INSTANT_ADMIN_TOKEN}
      />
      <Toaster position="top-right" />
    </>
  );
}
```

The Toaster component is required for pop-up alerts, unless you are already using [Sonner](https://sonner.emilkowal.ski/) in your project.


The component accepts `explorerState` and `setExplorerState` props for manual control over the state of the Explorer.


# CSS

## Projects Using Tailwind

For projects using Tailwind, add the component library to your Tailwind configuration.

Tailwind V3:

```js
// tailwind.config.js
module.exports = {
  content: [
    './lib/**/*.{js,ts,jsx,tsx}',
    './pages/**/*.{js,ts,jsx,tsx,md}',
    './_posts/**/*.{js,ts,jsx,tsx,md}',
    './components/**/*.{js,ts,jsx,tsx}',
    './utils/**/*.{js,ts,jsx,tsx}',
    './node_modules/@instantdb/components/src/**/*.{js,ts,jsx,tsx,md}',
  ],
};
```

Tailwind V4:

```css
@import 'tailwindcss';
@source '../node_modules/@instantdb/components';
```

---

## Projects Without Tailwind

For projects without Tailwind, to avoid CSS conflicts, the [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM) is used to isolate styles of the explorer.

```tsx
import './App.css';
import { Explorer, Toaster } from '@instantdb/components';

function App() {
  return (
    <>
      <Explorer
        className="h-full"
        useShadowDOM // this prop automatically applies styles
        appId={import.meta.env.VITE_INSTANT_APP_ID}
        adminToken={import.meta.env.VITE_INSTANT_ADMIN_TOKEN}
      />
      <Toaster position="top-right" />
    </>
  );
}
```


# Custom email templates and senders

How to customize magic code emails.

You can customize all aspects of your Instant app's "magic code" email: the body (plain text or HTML), subject, sender name, and even the `from` address.

## Dashboard

To start, go to your Dashboard's [auth tab](https://instantdb.com/dash?s=main&t=auth). Click "Custom Magic Code Email", and you're ready to go.

### Variables

We provide a handful of variables you can use in both your subject line and body template:

- `{code}`, the magic code, e.g. _123456_. Note, this variable is required in both the subject and body.
- `{user_email}`, the recipient user's email address, e.g. *happyuser@gmail.com*
- `{app_title}`, your app's name

Using a variable is as easy as adding the variable's name in curly brackets, e.g. `{variable_name}`.

```html
<p>Hi {user_email}, here's your code for {app_title}:</p>

<strong>{code}</strong>
```

## Custom sender addresses

You can also set Instant's email's `from` and `reply-to` fields to an address on your own domain.

If you provide a custom sender address, you'll need to confirm it before we can start delivering from it.

Our email partner, Postmark, will send a confirmation to the provided address with a link to verify. Until the address is verified, emails will continue to be sent from Instant's default auth sender (`auth@pm.instantdb.com`).


# App teams (Pro)

How to manage your Instant app's team members and their roles.

Apps with a Pro subscription can be managed by multiple users. To add team members to your app, head on over to the [Dashboard Admin tab](https://instantdb.com/dash?s=main&t=admin).

## Roles

App team members can have one of three roles: collaborator, admin or owner.

#### Collaborators

- Can view the Explorer, update Permissions, and configure Auth.

#### Admins

- Can invite other team members.

#### Owners (i.e., an app's creator)

- Can access the Billing tab.
- Can regenerate the app's admin tokens.
- Can delete their app.

## Invites

#### Inviting a team member

A pro app's admin or owner simply needs to navigate to the [Dashboard Admin tab](https://instantdb.com/dash?s=main&t=admin) and click "Invite a team member". This will open a dialog that accepts an email and role. This will send an email with instructions to the specified address.

#### Accepting an invite

Once an invited user signs up for Instant, they can access the [Dashboard Invites section](https://instantdb.com/dash?s=invites) where they can accept or decline the invite.


# Storage

How to upload and serve files with Instant.

Instant Storage makes it simple to upload and serve files for your app.
You can store images, videos, documents, and any other file type.

## Storage quick start

Let's build a full example of how to upload and display a grid of images

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

Initialize your schema and permissions via the [cli tool](/docs/cli)

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

Now open `instant.schema.ts` and replace the contents with the following code.

```javascript 
import { i } from "@instantdb/react";

const _schema = i.schema({
  entities: {
    $files: i.entity({
      path: i.string().unique().indexed(),
      url: i.string(),
    }),
    $users: i.entity({
      email: i.string().unique().indexed(),
    }),
  },
  links: {},
  rooms: {},
});

// This helps TypeScript display nicer intellisense
type _AppSchema = typeof _schema;
interface AppSchema extends _AppSchema {}
const schema: AppSchema = _schema;

export type { AppSchema };
export default schema;
```

Similarly open `instant.perms.ts` and replace the contents with the following

```javascript 
import type { InstantRules } from "@instantdb/react";

// Not recommended for production since this allows anyone to
// upload/delete, but good for getting started
const rules = {
  "$files": {
    "allow": {
      "view": "true",
      "create": "true",
      "delete": "true"
    }
  }
} satisfies InstantRules;

export default rules;
```

Push up both the schema and permissions to your Instant app with the following command

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

And then replace the contents of `app/page.tsx` with the following code.

```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` 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);
  }
}

// `delete` is what we use to delete a file from storage
// `$files` will automatically update once the delete is complete
async function deleteImage(image: InstantFile) {
  await db.storage.delete(image.path);
}

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[] }) {
  const [deletingIds, setDeletingIds] = React.useState<Set<string>>(new Set());

  const handleDelete = async (image: InstantFile) => {
    setDeletingIds((prev) => new Set([...prev, image.id]));

    await deleteImage(image);

    setDeletingIds((prev) => {
      prev.delete(image.id);
      return prev;
    });
  }

  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) => {
        const isDeleting = deletingIds.has(image.id);
        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" />
              {isDeleting && (
                <div className="absolute inset-0 bg-black bg-opacity-50 flex items-center justify-center">
                  <div className="w-8 h-8 border-2 border-t-2 border-gray-200 border-t-white rounded-full animate-spin"></div>
                </div>
              )}
            </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;
```

With your schema, permissions, and application code set, you can now run your app!

```shell 
npm run dev
```

Go to `localhost:3000`, and you should see a simple image feed where you can
upload and delete images!

## Storage client SDK

Below you'll find a more detailed guide on how to use the Storage API from
react.

### Upload files

Use `db.storage.uploadFile(path, file, opts?)` to upload a file.

- `path` determines where the file will be stored, and can be used with permissions to restrict access to certain files.
- `file` should be a [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File) type, which will likely come from a [file-type input](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file).
- `opts` can be used to set additional metadata like `contentType` and `contentDisposition`

```javascript
// use the file's current name as the path
await db.storage.uploadFile(file.name, file);

// or, give the file a custom name
const path = `${user.id}/avatar.png`;
await db.storage.uploadFile(path, file);

// or, set the content type and content disposition
const path = `${user.id}/orders/${orderId}.pdf`;
await db.storage.uploadFile(path, file, {
  contentType: 'application/pdf',
  contentDisposition: `attachment; filename="${orderId}-confirmation.pdf"`,
});
```

### Overwrite files

If the `path` already exists in your storage directory, it will be overwritten!

```javascript
// Uploads a file to 'demo.png'
await db.storage.uploadFile('demo.png', file);

// Overwrites the file at 'demo.png'
await db.storage.uploadFile('demo.png', file);
```

If you don't want to overwrite files, you'll need to ensure that each file has a unique path.

### View files

You can retrieve files by querying the `$files` namespace.

```javascript
// Fetch all files from earliest to latest upload
const query = {
  $files: {
    $: {
      order: { serverCreatedAt: 'asc' },
    },
  },
});
const { isLoading, error, data } = db.useQuery(query);
```

```javascript
console.log(data)
{
  "$files": [
    {
      "id": fileId,
      "path": "demo.png"
      // You can use this URL to serve the file
      "url": "https://instant-storage.s3.amazonaws.com/...",
      "content-type": "image/png",
      "content-disposition": "attachment; filename=\"demo.png\"",
    },
    // ...
  ]
}
```

You can use query filters and associations as you would with any other namespace
to filter and sort your files.

```javascript 
// instant.schema.ts
// ---------------
import { i } from '@instantdb/core';
const _schema = i.schema({
  entities: {
    $files: i.entity({
      path: i.string().unique().indexed(),
      url: i.string(),
    }),
    $users: i.entity({
      email: i.string().unique().indexed(),
    }),
    profiles: i.entity({
      nickname: i.string(),
      createdAt: i.date(),
    }),
  },
  links: {
    profileUser: {
      forward: { on: 'profiles', has: 'one', label: '$user' },
      reverse: { on: '$users', has: 'one', label: 'profile' },
    },
    profileUploads: {
      forward: { on: 'profiles', has: 'many', label: '$files' },
      reverse: { on: '$files', has: 'one', label: 'profile' },
    },
  },
});
```

```javascript 
// app/page.tsx
// ---------------
// Find files associated with a profile
const { user } = db.useAuth();
const query = {
  profiles: {
    $: {
      where: {"$user.id": user.id}
    },
    $files: {},
  },
});
// Defer until we've fetched the user and then query associated files
const { isLoading, error, data } = db.useQuery(user ? query : null);
```

### Delete files

Use `db.storage.delete(path)` to delete a file.

```javascript
// This will delete the file at 'demo.png'
await db.storage.delete('demo.png');
```

### Update files

You can use `db.transact` to update file paths, as well as any custom columns you've added to files.

So if you're schema looked like this:

```javascript
import { i } from "@instantdb/react";

const _schema = i.schema({
  entities: {
    $files: i.entity({
      path: i.string().unique().indexed(),
      isFavorite: i.boolean().optional()
      url: i.string(),
    }),
  },
});
```

You could run a transaction like this:

```javascript
// Move all files under 'documents/my-video-project/' to 'videos/my-video-project/' and make them favorites

const { data } = await db.query({
  $files: { $: { where: { path: { $like: 'documents/my-video-project/%' } } } },
});

await db.transact(
  data.$files.map((file) =>
    db.tx.$files[file.id].update({
      path: file.path.replace(
        'documents/my-video-project/',
        'videos/my-video-project/',
      ),
      isFavorite: true,
    }),
  ),
);
```

`path` is a unique attribute so if another file exists with that path, then the transaction
will fail.

At the moment we only allow updating the `path` attribute of `$files`, as well as any custom columns you've created. If you
try to update another attribute like `content-type` the transaction will fail.

### Link files

When the upload succeeds, `uploadFile` returns a `data` object containing a file ID associated with the uploaded file. You can use this id to link the file to other namespaces.

```javascript
async function uploadImage(file: File) {
  try {
    const path = `${user.id}/avatar`;
    const { data } = await db.storage.uploadFile(path, file);
    await db.transact(db.tx.profiles[profileId].link({ avatar: data.id }));
  } catch (error) {
    console.error('Error uploading image:', error);
  }
}
```

[Check out this repo](https://github.com/jsventures/instant-storage-avatar-example)
for a more detailed example showing how you may leverage links to implement an avatar upload feature

## Using Storage with React Native

The SDK expects a `File` object. In React Native the built-in `fetch` function can be used to construct a `File`, then you can pass that to the `uploadFile` method.

Example:

```typescript
import { init, InstaQLEntity } from '@instantdb/react-native';
import schema, { AppSchema } from '../instant.schema';
import * as FileSystem from 'expo-file-system';

const APP_ID = process.env.EXPO_PUBLIC_INSTANT_APP_ID;

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

const localFilePath = 'file:///var/mobile/Containers/Data/my_file.m4a';

const fileInfo = await FileSystem.getInfoAsync(localFilePath);

if (!fileInfo.exists) {
  throw new Error(`File does not exist at path: ${localFilePath}`);
}

// Convert the local file to a File object
const res = await fetch(fileInfo.uri);
const blob = await res.blob();
const file = new File([blob], payload.recordingId, { type: 'audio/x-m4a' });

await db.storage.uploadFile('my_file.m4a', file);
```

## Storage admin SDK

The Admin SDK offers a similar API for managing storage on the server. Permission
checks are not enforced when using the Admin SDK, so you can use it to manage
files without worrying about authentication.

### Uploading files

`db.storage.uploadFile(path, file, opts?)` is also available to upload a file
on the backend. In the admin SDK, the `file` argument must either be a buffer
or a stream.

```tsx
import fs from 'fs';

const fp = 'path/to/your/file.png';
const dest = 'images/demo.png';

// Upload a file from a buffer
const buffer = fs.readFileSync(filepath);
const { data } = await db.storage.uploadFile(dest, buffer);

// Upload a file from a stream
// IMPORTANT: You must provide `fileSize` as an option when uploading via stream
const stream = fs.createReadStream(fp);
const fileSize = fs.statSync(fp).size;
const { data } = await db.storage.uploadFile(dest, stream, {
  contentType: contentType,
  fileSize,
});
```

### View Files

Retrieving files is similar to the client SDK, but we use `db.query()` instead
of `db.useQuery()`.

```ts
const query = {
  $files: {
    $: {
      order: { serverCreatedAt: 'asc' },
    },
  },
});
const data = db.query(query);
```

### Delete files

There are two ways to delete files with the admin SDK:

- `db.storage.delete(pathname: string)`
- `db.storage.deleteMany(pathnames: string[])`

These allow you to either delete a single file, or bulk delete multiple files at a time.

```ts
const filename = 'demo.txt';
await db.storage.delete(filename);

const images = ['images/1.png', 'images/2.png', 'images/3.png'];
await db.storage.deleteMany(images);
```

### Link files

Similar to the client SDK, after uploading a file, you can use the response to
link the upload to other entities.

```typescript
// Assume we have a user ID and a buffer for the file
const { data } = await db.storage.uploadFile('images/demo.png', buffer);
db.transact([db.tx.$users[userId].link({ avatar: data.id })]);
```

## Permissions

By default, Storage permissions are disabled. This means that until you explicitly set permissions, no uploads or downloads will be possible.

- _create_ permissions enable uploading `$files`
- _view_ permissions enable viewing `$files`
- _update_ permissions enable updating `$files`
- _delete_ permissions enable deleting `$files`
- _view_ permissions on `$files` and _update_ permisssions on the forward entity enabling linking and unlinking `$files`

In your permissions rules, you can use `auth` to access the currently authenticated user, and `data` to access the file metadata.

At the moment, the only available file metadata is `data.path`, which represents the file's path in Storage. Here are some example permissions

Allow anyone to upload and retrieve files (easy to play with but not recommended for production):

```json
{
  "$files": {
    "allow": {
      "view": "true",
      "create": "true"
    }
  }
}
```

Allow all authenticated users to view and upload files:

```json
{
  "$files": {
    "allow": {
      "view": "isLoggedIn",
      "create": "isLoggedIn"
    },
    "bind": ["isLoggedIn", "auth.id != null"]
  }
}
```

Authenticated users may only upload, view, update files from their own subdirectory:

```json
{
  "$files": {
    "allow": {
      "view": "isOwner",
      "update": "isOwner",
      "create": "isOwner"
    },
    "bind": ["isOwner", "data.path.startsWith(auth.id + '/')"]
  }
}
```


# Stripe Payments

How to add payments to your Instant app with Stripe.

The quickest way to add Stripe to your Instant app is to tell your LLM to do it. Just say "add Stripe payments" and follow along step by step.

For more guidance we've put together three reference examples with tutorials you
can follow along. Each example also has addiitonal docs you can copy and paste for your agent.

## Stripe Examples

All three patterns share the same core idea: **Stripe handles payment, Instant
handles data and access control.** When a
payment completes, Stripe's webhook writes to Instant via the
[Admin SDK](/docs/backend), and any queries on the client get updated
instantly.

### One-off purchase

This example is for a wallpaper store where users buy a pack and get immediate
access to high-resolution downloads. It's a one-off payment and no user accounts required to minimize friction.

- [Example repo](https://github.com/instantdb/instant/tree/main/examples/stripe-one-off) with [step-by-step tutorial](https://github.com/instantdb/instant/tree/main/examples/stripe-one-off/tutorial.md)
- [Strategy](https://raw.githubusercontent.com/instantdb/instant/main/examples/stripe-one-off/stripe-strategy.md) and [payment flow](https://raw.githubusercontent.com/instantdb/instant/main/examples/stripe-one-off/purchase.md) docs to help your agent implement the pattern

**How it works:**

1. User clicks "Buy" — a UUID token is generated and saved to `localStorage`
   _before_ redirecting to Stripe Checkout
2. The token is passed to Stripe via session metadata
3. On payment, a webhook creates a `purchase` record in Instant linked to that
   token
4. Permissions gate the protected content — only queries that include a valid purchase token
   (via `ruleParams`) can see the full-resolution URLs
5. Bonus: Uses [magic code auth](/docs/auth/magic-codes) to let users sign in
   and retrieve past purchases

### Subscription

This example is for a blog where free users see teasers and subscribers get full
articles. It uses recurring billing with Stripe and auth-based access control.

- [Example repo](https://github.com/instantdb/instant/tree/main/examples/stripe-subscription) with [step-by-step tutorial](https://github.com/instantdb/instant/tree/main/examples/stripe-subscription/tutorial.md)
- [Strategy](https://raw.githubusercontent.com/instantdb/instant/main/examples/stripe-subscription/stripe-strategy.md) and [subscription flow](https://raw.githubusercontent.com/instantdb/instant/main/examples/stripe-subscription/subscription.md) docs to help your agent implement the pattern

**How it works:**

1. User signs in via magic code auth
2. Checkout creates or reuses a Stripe customer linked to the Instant user
3. Stripe webhooks sync `subscriptionStatus` to the `$users` record whenever
   the subscription changes (created, updated, canceled, deleted)
4. Permissions gate premium content — the `content` field is
   simply omitted from query results for non-subscribers
5. Stripe's Billing Portal handles cancellation and payment method updates

### Credits

This example is for a haiku generator where each generation costs one credit.
Users buy packs of 10 credits for $2. It's a pay-per-use model with real-time balance updates.

- [Example repo](https://github.com/instantdb/instant/tree/main/examples/stripe-credits) with [step-by-step tutorial](https://github.com/instantdb/instant/tree/main/examples/stripe-credits/tutorial.md)
- [Strategy](https://raw.githubusercontent.com/instantdb/instant/main/examples/stripe-credits/stripe-strategy.md) and [credit flow](https://raw.githubusercontent.com/instantdb/instant/main/examples/stripe-credits/credits.md) docs to help your agent implement the pattern

**How it works:**

1. User signs in via magic code auth
2. Checkout creates a Stripe customer and processes a one-time payment for a
   credit pack
3. The webhook adds credits to the user's `credits` field, with idempotency
   protection via Stripe session metadata to prevent double-crediting on retries
4. A server-side API route verifies the user has enough credits, then
   atomically deducts a credit and creates the result in a single
   transaction
5. Instant's real-time subscriptions keep the credit balance and history
   updated in the UI instantly


# Admin HTTP API

Direct HTTP access to Instant's admin API for non-JavaScript environments.

If your backend is written in Javascript, you can use the [`@instantdb/admin`](/docs/backend) SDK to connect your server to Instant.

But what if your backend isn't written in Javascript? That's where the HTTP API comes in.

You can use the HTTP API in your favorite backend language to run scripts, create custom auth flows, or evaluate sensitive app logic.



If you give this documentation to your AI agent, it can create a custom SDK for your backend language. Here's the [markdown](/docs/http-api.md).



## Auth

First and foremost, grab your app's `APP_ID` and `ADMIN_TOKEN`. You can get this by going to your
[dashboard](https://instantdb.com/dash). To authenticate requests, include them in your HTTP headers:

```shell 
curl -X POST "https://api.instantdb.com/admin/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d '{"query":{"goals":{}}}'
```

## Reading and Writing Data

`POST /admin/query` and `POST /admin/transact` let your read and write data as an admin.

### query

To make queries, run `POST /admin/query` with an InstaQL query:

```shell
curl -X POST "https://api.instantdb.com/admin/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d '{"query":{"goals":{},"todos":{}}}'
```

If you need [rule params](/docs/permissions#rule-params), include `$$ruleParams` at the top-level:

```json
{
  "$$ruleParams": { "knownGoalId": "..." },
  "query": { "goals": {} }
}
```

As a refresher, you can learn about InstaQL queries
[here](/docs/instaql).

### transact

To make transactions, send `POST /admin/transact` with `steps`:

```shell
curl -X POST "https://api.instantdb.com/admin/transact" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d '{"steps":[["update","todos","<a-todo-uuid>",{"title":"Get fit"}]]}'
```

`steps` is the internal representation of Instant transactions. Here's how they
map to the [Instant transactions](/docs/instaml) you know:

```javascript
[
  // tx.goals[goalId1].update({title: "moop"})
  [
      "update",
      "goals",
      goalId1,
      {
          "title": "moop"
      }
  ],
  // tx.goals[goalId1].link({todos: todoId1})
  [
      "link",
      "goals",
      goalId1,
      {
          "todos": todoId1
      }
  ],
  // tx.goals[goalId1].unlink({todos: todoId1})
  [
      "unlink",
      "goals",
      goalId1
      {
          "todos": todoId1
      }
  ],
  // tx.goals[goalId1].delete()
  [
      "delete",
      "goals",
      goalId1
  ],
]
```

## Subscriptions on the backend

You can subscribe to queries over SSE with `POST /admin/subscribe-query`.

The connection stays open and streams updates.

```shell
curl -N -X POST "https://api.instantdb.com/admin/subscribe-query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d '{"query":{"tasks":{}}}'
```


Subscriptions keep a live connection open on your backend. Be sure to close them
when they are no longer needed.


## Impersonating users

When you use the admin API, you can make _any_ query or transaction. As an admin, you bypass permissions.

But sometimes you want to make requests on behalf of a
user and respect permissions. You can do this by passing the `As-Email`, `As-Token`, or `As-Guest` headers.

```shell 
# Scoped by their email
curl -X POST "https://api.instantdb.com/admin/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -H "As-Email: alyssa_p_hacker@instantdb.com" \
  -d '{"query":{"goals":{}}}'

# Or with their auth token
curl -X POST "https://api.instantdb.com/admin/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -H "As-Token: $REFRESH_TOKEN" \
  -d '{"query":{"goals":{}}}'

# Or use the db as a guest
curl -X POST "https://api.instantdb.com/admin/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -H "As-Guest: true" \
  -d '{"query":{"goals":{}}}'
```


`As-Email` requires an `ADMIN_TOKEN`. For `As-Token` and `As-Guest`, you could skip the
`Authorization` if you want too.


## Retrieve a user

Use `GET /admin/users` to fetch an app user by `email`, `id`, or `refresh_token`.

```shell
# By email!
curl -X GET "https://api.instantdb.com/admin/users?email=alyssa_p_hacker@instantdb.com" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID"

# By id
curl -X GET "https://api.instantdb.com/admin/users?id=$USER_ID" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID"

# Or by a refresh token
curl -X GET "https://api.instantdb.com/admin/users?refresh_token=$REFRESH_TOKEN" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID"
```

## Delete a user

Use `DELETE /admin/users` to delete an app user by `email`, `id`, or `refresh_token`.

```shell
# By email
curl -X DELETE "https://api.instantdb.com/admin/users?email=alyssa_p_hacker@instantdb.com" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID"

# By id
curl -X DELETE "https://api.instantdb.com/admin/users?id=$USER_ID" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID"

# Or by an auth token
curl -X DELETE "https://api.instantdb.com/admin/users?refresh_token=$REFRESH_TOKEN" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID"
```

## Presence in the Backend

If you use [rooms & presence](/docs/presence-and-topics), you may want to query for the data currently in a room. This can be especially useful if you are sending a notification for example, and want to skip it if the user is already online. To do get room data use `GET /admin/rooms/presence`. Make sure to pass in a `room-type` and a `room-id`:

```shell
curl -X GET "https://api.instantdb.com/admin/rooms/presence?room-type=chat&room-id=room-123" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID"
```

## Sign Out

`POST /admin/sign_out` allows you to log out users. You can log out a user out from every session by passing in their `email` or `id`. Or you can log a user out from a particular session by passing in a `refresh_token`:

```shell 
# All sessions for this email sign out
curl -X POST "https://api.instantdb.com/admin/sign_out" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d '{"email":"alyssa_p_hacker@instantdb.com"}'

# All sessions for this user id sign out
curl -X POST "https://api.instantdb.com/admin/sign_out" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d "{\"id\":\"$USER_ID\"}"

# Just sign out the session for this refresh token
curl -X POST "https://api.instantdb.com/admin/sign_out" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d "{\"refresh_token\":\"$REFRESH_TOKEN\"}"
```

## Custom Auth

You can use `POST /admin/refresh_tokens` to generate auth tokens for your users.

Pass in an `email` or an `id` to create a refresh token:

```shell 
# By email
curl -X POST "https://api.instantdb.com/admin/refresh_tokens" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d '{"email":"alyssa_p_hacker@instantdb.com"}'

# Or by ID
curl -X POST "https://api.instantdb.com/admin/refresh_tokens" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d "{\"id\":\"$USER_ID\"}"
```

If a user with the provider id or email does not exist, Instant will create the
user for you. The response includes `user.refresh_token`. You can pass this token onto your client, and use that to [log in](/docs/backend#2-frontend-db-auth-sign-in-with-token)

## Custom magic codes

We support a [magic code flow](/docs/auth) out of the box. However, if you'd like to use your own email provider to send the code, you can create a magic code with `POST /admin/magic_code`:

```shell
curl -X POST "https://api.instantdb.com/admin/magic_code" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d '{"email":"alyssa_p_hacker@instantdb.com"}'
```

You can also use Instant's default email provider to send a magic code:

```shell
curl -X POST "https://api.instantdb.com/admin/send_magic_code" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d '{"email":"alyssa_p_hacker@instantdb.com"}'
```

Similarly, you can verify a magic code too:

```shell
curl -X POST "https://api.instantdb.com/admin/verify_magic_code" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d '{"email":"alyssa_p_hacker@instantdb.com","code":"123456"}'
```

## Authenticated Endpoints

To authenticate users, have your frontend pass in a refresh token. Then use `POST /runtime/auth/verify_refresh_token` to verify it:

```shell
curl -X POST "https://api.instantdb.com/runtime/auth/verify_refresh_token" \
  -H "Content-Type: application/json" \
  -d "{\"app-id\": \"$APP_ID\", \"refresh-token\": \"$REFRESH_TOKEN\"}"
```

## Storage

You can also manage your app's [storage](/docs/storage) with the HTTP API.

### Upload Files

Upload a file with `PUT /admin/storage/upload`:

```shell
curl -X PUT "https://api.instantdb.com/admin/storage/upload" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -H "Path: snippets/demo.txt" \
  -H "Content-Type: text/plain" \
  --data-binary "@demo.txt"
```

### Delete Files

Delete a file by path:

```shell
curl -X DELETE "https://api.instantdb.com/admin/storage/files?filename=snippets/demo.txt" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID"
```

Delete multiple files by path:

```shell
curl -X POST "https://api.instantdb.com/admin/storage/files/delete" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d '{"filenames":["snippets/1.txt","snippets/2.txt"]}'
```

### List Files

List files by querying `$files`:

```shell
curl -X POST "https://api.instantdb.com/admin/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d '{"query":{"$files":{}}}'
```


# (Experimental) NextJS SSR

Use server-side-rendering with InstantDB and Next.js.

If you use NextJS and want to do server-side rendering, we have an experimental library for you.

`@instantdb/react/nextjs` can you let you run Instant queries both on the server and the client, and for the first time, _share caches between them_. (If you don’t get with this means yet, no worries, we’ll explain in detail in the document! Suffice it to say it’s pretty cool.)

This is an experimental feature, and you may not need SSR for many applications. But when you do, you can get some exceptional UX from it.

In this essay we’ll cover:

1. What server-side rendering is
2. When SSR is a good idea
3. How Instant works over SSR, particularly on caches
4. And how to add SSR in your projects

## What is server-side rendering?

Server-side rendering lets you run your Javascript code in two environments.

First the server renders your React component. So as soon a browser sees your website, your React component is there.

Once the browser loads Javascript, the same component runs on the client once more. This way if you have hover effects or other logic that needs to attach to your component, it can do that in the browser.

To get a sense for how this all works, imagine loading a todo app:

![SSR diagram](/img/docs/next-ssr-diagram.png)

Without SSR, when you first load the site you’d see a blank page. Once Javascript gets loaded, React would kick in and you’d see your todos show up.

With SSR, your todo component would render on the server first. The _very_ first load in the browser would already show todos. Once Javascript loads, the todo component would re-attached and all the click handlers and effects would work.

## When is server-side rendering a good idea?

On first glance, server-side rendering can sound great. Why not run your code right away on the server? Well, there are two costs:

### The costs

**The biggest cost is complexity**: Your code runs in two environments. Once on the sever, and once on the client. NextJS and Instant can do a good job of hiding the difference, but sometimes those differences leak out (as a basic example, there’s no `window` in the server). For many applications, you may not want the added complexity.

**The second cost relates to client-heavy applications:** If you want your application to _feel_ like a desktop app, you’ll want to reduce the amount of times your application pauses while navigating. This means that you have to be proactive with fallback states when using `<Suspense />`, or prefetch anticipated queries more agressively.



Tip: You can prefetch queries by `db.queryOnce()` from anywhere, or by using `db.useQuery()` in a component and ignoring the result.



### The Benefits

But there are also some clear benefits.

**SSR can be great for search engines.** Web crawlers are getting better with Javascript, but they general do the best job at indexing websites when the content is there on the first load. SSR can do this for you.

**SSR can remove loading screens, especially if you use NextJS Routes.** Sometimes you load an app and see _lots_ of loading spinners. SSR can help you remove those spinners. Since there’s content on the the first load, you can often ignore loading states completely. You may wonder, won’t the first load be slower if you’re fetching data? Not by much, for two reasons. First If you use NextJS routing, it will try to pre-fetch as much as possible. By the time a user clicks a link, the data is often already there. Second, if you use Vercel, their servers are close to Instant servers, which means queries often take milliseconds to transfer.

Put these benefits together, and sometimes SSR really is worth it.

## How Instant works with SSR

So, if the benefits are worth it for you, how can you use Instant with SSR? That’s where `@instantdb/react/nextjs` comes in.

With `@instantdb/react/nextjs` you get a special package with a new hook: `db.useSuspenseQuery`:

![useSuspenseQuery diagram](/img/docs/next-ssr-suspense-query.png)

When you use `db.useSuspenseQuery`. (1) On the server it will run a query once and get data. When loaded in the browser, (2) it will turn the re-connect and subscribe to changes on the same query. **This means on the first load you have data, _and_ it becomes real-time in the browser.**

### What about offline caches?

There's nothing faster than local data. If `useSuspenseQuery` is running on the client, it will use the local data and websocket connection instead.

In addition, when the page first loads from SSR, it will update the local cache with the most up to date results.


Using SSR can make data fetching slower in one specific case: If you are using a `useSuspenseQuery` and there is not a `<Suspense>` anywhere higher in the component tree, the server will not send any HTML/JS at all until the query has resolved and the page has rendered. In some cases, this is desirable for things like SEO, but if the user already has the query result in their local cache, the page load is blocked, and they won't get a chance to load it and will have to wait.

If the component that calls `useSuspenseQuery` is wrapped in a `<Suspense/>`, Then the data will be fetched at the same time in both the client and server and the user will see the result from whatever loaded fastest. For returning users, the usually ends up being the local data, but for non-cached queries, the server is often faster.


## Adding SSR to your projects

If this all sounds good to you, you can add SSR to your projects today.

Here’s the step by step guude.

### 1. Replace your `db` client

First things first, we’ll want to replace our db client to work with SSR.

Instead of importing from `@instantdb/react`, you’ll import from `@instantdb/react/nextjs`:

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

export const db = init({
  appId: process.env.NEXT_PUBLIC_INSTANT_APP_ID!,
  schema,
  firstPartyPath: '/api/instant',
});
```

Note that we also included `firstPartyPath`. This lets us sync auth between client and server.

### 2. Sync auth

Syncing auth is covered in more detail [here](/docs/backend#syncing-auth), but we'll reproduce the main steps to this tutorial easy to follow.

Let's create a route handler under `app/api/instant/route.ts`:

```typescript 
// src/app/api/instant/route.ts
import { createInstantRouteHandler } from '@instantdb/react/nextjs';

export const { POST } = createInstantRouteHandler({
  appId: process.env.NEXT_PUBLIC_INSTANT_APP_ID!,
});
```

Once we do this, Instant can start to detect the logged in user both in the browser and in the server.

### 3. Create an InstantProvider

SSR relies on suspense. To support that we’ll need to make an `InstantProvider` component:

```typescript 
// src/InstantProvider.tsx
"use client";
import { db } from "@/app/lib/db";
import { type User } from "@instantdb/react";
import { InstantSuspenseProvider } from "@instantdb/react/nextjs";
import React from "react";

export const InstantProvider = ({
  children,
  user,
}: {
  children: React.ReactNode;
  user: User;
}) => (
  <InstantSuspenseProvider user={user} db={db}>
    {children}
  </InstantSuspenseProvider>
);
```

### 4. Update layout.tsx

Now we’ll want to use our InstantProvider in a server component, usually `app/layout.tsx`:

```typescript 
// src/app/layout.tsx
import { getUnverifiedUserFromInstantCookie } from "@instantdb/react/nextjs";
import { InstantProvider } from "@/InstantProvider";

export default async function RootLayout({ children }) {
  const user = await getUnverifiedUserFromInstantCookie(process.env.NEXT_PUBLIC_INSTANT_APP_ID!);

  return (
    <html>
      <body>
        <InstantProvider user={user}>{children}</InstantProvider>
      </body>
    </html>
  );
}
```

If using the NextJS pages directory, you can use `getServerSideProps` to get the user and pass it to the provider via the PageProps.

This (a) fetches the current user, and (b) puts the Instant provider in the React tree.

At this point...we’re ready to use SSR queries!

### 5. db.useSuspenseQuery to your heart's delight

Now that you’ve set up SSR, you should see a new `db.useSuspenseQuery` available. Use it in your pages:

```typescript
'use client';
import { db } from '@/lib/db';

export default function Page() {
  // renders on server, no loading state needed
  const { data } = db.useSuspenseQuery({ posts: {} });
}
```

Note how there’s no `isLoading` or `error` state from db.useSuspenseQuery! This is handled using [React Suspense](https://react.dev/reference/react/Suspense), and makes sure we have the data when we render this page.

If your code uses `useUser`, `useAuth`, or `db.SignedIn`/`db.SignedOut`, it will initially use the `user` value you provided to `InstantProvider` instead of a pending state. These hooks/components will continute to be reactive.

## Questions

This is still a beta. We'd love to hear your feedback on [Discord](https://discord.com/invite/VU53p7uQcE)!