# 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 mistake**: Linking from a system namespace ``` // ❌ Bad: System namespace in forward direction profileUser: { forward: { on: '$users', has: 'one', label: 'profile' }, reverse: { on: 'profiles', has: 'one', label: '$user' }, }, ``` ✅ **Correction**: Always link to system namespaces in the reverse direction ``` // ✅ Good: System namespace in reverse direction profileUser: { forward: { on: 'profiles', has: 'one', label: '$user' }, reverse: { on: '$users', has: 'one', label: 'profile' }, }, ``` ## Common mistakes with permissions Sometimes you want to express permissions based an an attribute in a linked entity. For those instance 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 Always use `update` method to create new entities: ❌ **Common mistake**: Using a non-existent `create` method ``` // ❌ Bad: `create` does not exist, use `update` instead! db.transact(db.tx.todos[id()].create({ text: "Buy groceries" })); ``` ✅ **Correction**: Use `update` to create new entities ``` // ✅ Good: Always use `update` to create new entities db.transact(db.tx.todos[id()].update({ text: "Properly generated ID todo" })); ``` 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 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 associated based on any criteria. ❌ **Common mistake**: Incorrect synax 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 using `$users` namespace Since the `$users` namespace is read-only and can't be modified directly, it's recommended to create a `profiles` namespace for storing additional user information. ❌ **Common mistake**: Adding properties to `$users` directly ```typescript // ❌ Bad: Directly updating $users will throw an error! db.transact(db.tx.$users[userId].update({ nickname: 'Alice' })); ``` ✅ **Correction**: Add properties to a linked profile instead ``` // ✅ Good: Update linked profile instead db.transact(db.tx.profiles[profileId].update({ displayName: "Alice" })); ``` `$users` is a system namespace so we ensure to create links in the reverse direction. ❌ **Common mistake**: Placing `$users` in the forward direction ```typescript // ❌ Bad: $users must be in the reverse direction userProfiles: { forward: { on: '$users', has: 'one', label: 'profile' }, reverse: { on: 'profiles', has: 'one', label: '$user' }, }, ``` ✅ **Correction**: Always link `$users` in the reverse direction ``` // ✅ Good: Create link between profiles and $users userProfiles: { forward: { on: 'profiles', has: 'one', label: '$user' }, reverse: { on: '$users', has: 'one', label: 'profile' }, }, ``` The default permissions only allow users to view their own data. We recommend keeping it this way for security reasons. Instead of viewing all users, you can view all profiles ❌ **Common mistake**: Directly querying $users ```typescript // ❌ Bad: This will likely only return the current user db.useQuery({ $users: {} }); ``` ✅ **Correction**: Directly query the profiles namespace ```typescript // ✅ Good: View all profiles db.useQuery({ profiles: {} }); ``` ## 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 Modern Firebase. With Instant you can easily build realtime and collaborative apps like Notion or Figma. Curious about what it's all about? Try a . Have questions? And if you're ready, follow the quick start below to **build a live app in less than 5 minutes!** ## Quick start To use Instant in a brand new project, fire up your terminal and run the following: ```shell npx create-next-app instant-demo --tailwind --yes cd instant-demo npm i @instantdb/react npm run dev ``` Now open up `app/page.tsx` in your favorite editor and replace the entirety of the file with the following code. ```javascript "use client"; import { id, i, init, InstaQLEntity } from "@instantdb/react"; // 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.number(), }), }, }); type Todo = InstaQLEntity; const db = init({ appId: APP_ID, schema }); function App() { // Read Data const { isLoading, error, data } = db.useQuery({ todos: {} }); if (isLoading) { return; } if (error) { return
Error: {error.message}
; } const { todos } = data; return (

todos

Open another tab to see todos update in realtime!
); } // 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 ( ); } function TodoForm({ todos }: { todos: Todo[] }) { return (
{ e.preventDefault(); const input = e.currentTarget.input as HTMLInputElement; addTodo(input.value); input.value = ""; }} >
); } function TodoList({ todos }: { todos: Todo[] }) { return (
{todos.map((todo) => (
toggleDone(todo)} />
{todo.done ? ( {todo.text} ) : ( {todo.text} )}
))}
); } function ActionBar({ todos }: { todos: Todo[] }) { return (
Remaining todos: {todos.filter((todo) => !todo.done).length}
); } export default App; ``` Go to `localhost:3000`, aand 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 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. ```typescript 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; 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 ( Loading... ); } if (error) { return ( Error: {error.message} ); } return
; } function Main(props: { color?: Color }) { const { value } = props.color || { value: "lightgray" }; return ( Hi! pick your favorite color {["green", "blue", "purple"].map((c) => { return ( ); } ``` ## Generating 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({ 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. ```javascript 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(400).send('Uh oh, you are not authenticated'); } // ... }); ``` # 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 your 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. At the moment InstantDB does not support attribute level permissions. This is something we are actively thinking about though! In the meantime you can work around this by splitting your entities into multiple namespaces. This way you can set separate permissions for private data. [Here's an example](https://github.com/instantdb/instant/blob/main/client/sandbox/react-nextjs/pages/patterns/split-attributes.tsx) ## 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 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.todos.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
Connection state: {connectionState}
; } ``` ## 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 ``` # Showcase Real world apps built with Instant. ## Sample Apps Here are some sample apps showing how to use Instant to build a real app. - [Instldraw](https://github.com/jsventures/instldraw) - collaborative drawing app built with Instant. - [Instant Awedience](https://github.com/nezaj/instant-awedience) - simple chat app with presence, typing indicators, and reactions!. - [Glazepal](https://github.com/reichert621/glazepal) - React Native app for managing ceramic glazes - [Stroopwafel](https://github.com/jsventures/stroopwafel) - casual multiplayer game built with React Native. ## Real World Apps Here are some apps in production that are powered by Instant. - [Palette.tools](https://palette.tools) - Palette is a modern, all-in-one project management app for studios & digital artists 🎨 - [Mentor](https://goalmentor.app/) - Simplify your goals and get things done with mentor, your personal assistant - [Subset](https://subset.so/) - A high-quality, no-frills, modern spreadsheet ## More examples Are you looking for more examples? Do you want to contribute your app to this list? Let us know on [discord](https://discord.gg/8J6kZfV) or [twitter](https://twitter.com/intent/tweet?text=%40useinstantdb) # 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), [Google OAuth](/docs/auth/google-oauth), [Sign In with Apple](/docs/auth/apple), and [Clerk](/docs/auth/clerk). If you want to build your own flow, you can use the [Admin SDK](/docs/backend#custom-auth). # 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. Here's how you can do it with react. ## Full Magic Code Example The example below shows how to use magic codes in a React app. If you're looking for an example with vanilla JS, check out this [sandbox](https://github.com/instantdb/instant/blob/main/client/sandbox/vanilla-js-vite/src/main.ts). Open up your `app/page.tsx` file, and replace the entirety of it with the following code: ```javascript "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() { const { isLoading, user, error } = db.useAuth(); if (isLoading) { return; } if (error) { return
Uh oh! {error.message}
; } if (user) { // The user is logged in! Let's load the `Main` return
; } // The use isn't logged in yet. Let's show them the `Login` component return ; } function Main({ user }: { user: User }) { return (

Hello {user.email}!

); } function Login() { const [sentEmail, setSentEmail] = useState(""); return (
{!sentEmail ? ( ) : ( )}
); } function EmailStep({ onSendEmail }: { onSendEmail: (email: string) => void }) { const inputRef = React.useRef(null); const handleSubmit = (e: React.FormEvent) => { 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 (

Let's log you in

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.

); } function CodeStep({ sentEmail }: { sentEmail: string }) { const inputRef = React.useRef(null); const handleSubmit = (e: React.FormEvent) => { 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 (

Enter your code

We sent an email to {sentEmail}. Check your email, and paste the code you see.

); } export default App; ``` Go to `localhost:3000`, aand huzzah 🎉 You've got auth. --- **Let's dig deeper.** We created a `Login` component to handle our auth flow. 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 `useQuery` or `transact`, the refresh token will be used to hydrate `auth` on the backend during permission checks. On the client, `useAuth` will set `isLoading` to `false` and populate `user` -- huzzah! ## useAuth ```javascript function App() { const { isLoading, user, error } = db.useAuth(); if (isLoading) { return; } if (error) { return
Uh oh! {error.message}
; } if (user) { return
; } return ; } ``` Use `useAuth` to fetch the current user. Here we guard against loading our `Main` component until a user is logged in ## 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. ## Sign out ```javascript db.auth.signOut(); ``` Use `auth.signOut` from the client to invalidate the user's refresh token and sign them out.You can also use the admin SDK to sign out the user [from the server](/docs/backend#sign-out). ## Get auth ```javascript const user = await db.getAuth(); console.log('logged in as', user.email); ``` For scenarios where you want to know the current auth state without subscribing to changes, you can use `getAuth`. # Google OAuth How to add Google OAuth to your Instant app. Instant supports logging in your users with their Google account. We support flows for Web and React Native. Follow the steps below to get started. **Step 1: Configure OAuth consent screen** Go to the [Google Console](https://console.cloud.google.com/apis/credentials). 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". **Step 2: Create an OAuth client for Google** 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. **Step 3: Register your OAuth client with Instant** Go to the Instant dashboard and select the `Auth` tab for your app. Register a Google client and enter the client id and client secret from the OAuth client that you created. **Step 4: 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. **Step 5: Add login to your app** The next sections will show you how to use your configured OAuth client with Instant. ## Native button for Web You can use [Google's Sign in Button](https://developers.google.com/identity/gsi/web/guides/overview) with Instant. You'll use `db.auth.SignInWithIdToken` to authenticate your user. The benefit of using Google's button is that you can display your app's name in the consent screen. First, make sure that your website is in the list of "Authorized JavaScript origins" for your Google client on the [Google console](https://console.cloud.google.com/apis/credentials). If you're using React, the easiest way to include the signin button is through the [`@react-oauth/google` package](https://github.com/MomenSherif/react-oauth). ```shell npm install @react-oauth/google ``` Include the button and use `db.auth.signInWithIdToken` to complete sign in. Here's a full example ```javascript 'use client'; import React, { useState } from 'react'; import { init } from '@instantdb/react'; import { GoogleOAuthProvider, GoogleLogin } from '@react-oauth/google'; const APP_ID = '__APP_ID__'; const db = init({ appId: APP_ID }); // e.g. 89602129-cuf0j.apps.googleusercontent.com const GOOGLE_CLIENT_ID = 'REPLACE_ME'; // Use the google client name in the Instant dashboard auth tab const GOOGLE_CLIENT_NAME = 'REPLACE_ME'; function App() { const { isLoading, user, error } = db.useAuth(); if (isLoading) { return
Loading...
; } if (error) { return
Uh oh! {error.message}
; } if (user) { return

Hello {user.email}!

; } return ; } function Login() { const [nonce] = useState(crypto.randomUUID()); return ( 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); }); }} /> ); } ``` If you're not using React or prefer to embed the button yourself, refer to [Google's docs on how to create the button and load their client library](https://developers.google.com/identity/gsi/web/guides/overview). When creating your button, make sure to set the `data-ux_mode="popup"`. Your `data-callback` function should look like: ```javascript 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', }); } ``` ## Redirect flow for Web If you don't want to use the google styled buttons, you can use the redirect flow instead. Simply create an authorization URL via `db.auth.createAuthorizationURL` and then use the url to create a link. Here's a full example: ```javascript '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, }); function App() { const { isLoading, user, error } = db.useAuth(); if (isLoading) { return
Loading...
; } if (error) { return
Uh oh! {error.message}
; } if (user) { return

Hello {user.email}!

; } return ; } function Login() { return Log in with Google; } ``` 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. ## Webview flow on React Native Instant comes with support for Expo's AuthSession library. If you haven't already, follow the AuthSession [installation instructions from the Expo docs](https://docs.expo.dev/versions/latest/sdk/auth-session/). 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" } } ``` From the Auth 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://`. Now you're ready to add a login button to your expo app. Here's a full example ```javascript 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() { const { isLoading, user, error } = db.useAuth(); let content; if (isLoading) { content = Loading...; } else if (error) { content = Uh oh! {error.message}; } else if (user) { content = Hello {user.email}!; } else { content = ; } return {content}; } 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 ( ); } const styles = StyleSheet.create({ container: { flex: 1, justifyContent: 'center', alignItems: 'center', }, }); ``` # 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` ## 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: ```javascript AppleID.auth.init({ clientId: '', scope: 'name email', redirectURI: window.location.href, }); ``` Implement `signInPopup` using `clientName` from Step 4: ```javascript 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: '', idToken: resp.authorization.id_token, nonce: nonce, }); } ``` Add Sign In button: ```javascript ``` ## 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: '', redirectURL: window.location.href, }); ``` Add a link uses `authUrl`: ``` Sign In with Apple ``` 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: ```javascript 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: '', 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: ```javascript ); } return (
); } function App() { return ( ); } 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 ```typescript // instant.perms.ts import type { InstantRules } from '@instantdb/react'; const rules = { todos: { allow: { view: 'auth.id != null', create: 'isOwner', update: 'isOwner', delete: 'isOwner', }, bind: ['isOwner', 'auth.id != null && auth.id == data.creatorId'], }, } satisfies InstantRules; export default rules; ``` 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`. 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. ### 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 creating 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`, and `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."_! **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')" ] } } ``` # Platform OAuth Integration Allow third-party applications to access Instant resources on behalf of users using OAuth 2.0. Instant supports the standard OAuth 2.0 Authorization Code grant flow, enabling users to authorize your application to access their Instant data and perform actions on their behalf, like reading app details or managing apps. This guide walks you through the steps required to integrate your application with Instant using OAuth. You can also [walk-through a demo](/labs/oauth_apps_demo) to see it in action. ## OAuth flow ### 1. Create an OAuth App and Client The first step is to register your OAuth application with Instant. This is done through the Instant Dashboard: 1. Navigate to the **[OAuth Apps section of the Instant Dashboard](https://instantdb.com/dash?s=main&t=oauth-apps)** 2. Create a new "OAuth App" associated with your Instant App. Give it a descriptive name. 3. Within that OAuth App, create a new "OAuth Client". - Provide a name for the client (e.g., "My Web App Integration"). - Specify one or more **Authorized Redirect URIs**. These are the exact URLs that Instant is allowed to redirect the user back to after they authorize (or deny) your application. 4. Upon creating the client, you will be provided with: - **Client ID:** A public identifier for your application. - **Client Secret:** A confidential secret known only to your application and Instant. **Treat this like a password and keep it secure.** You will need the Client ID and Client Secret for subsequent steps. Your OAuth app will start in test mode. Only members of your Instant app will be able to authorize with the app. Once you have your OAuth flow working, [ping us in Discord](https://discord.gg/2rnGtfFQup) to go live. ### 2. Redirect User for Authorization To start the flow, redirect the user from your application to the Instant authorization endpoint. Construct the URL as follows: **Base URL:** ```text https://api.instantdb.com/platform/oauth/start ``` **Query Parameters:** - `client_id` (Required): Your OAuth Client ID obtained in Step 1. - `response_type` (Required): Must be set to `code`. - `redirect_uri` (Required): One of the exact Authorized Redirect URIs you registered for your client in Step 1. - `scope` (Required): A space-separated list of permissions your application is requesting. Available scopes are: - `apps-read`: Allows listing user's apps and viewing their schema/permissions. - `apps-write`: Allows creating/deleting apps and updating schema/permissions. - `state` (Required): A random, opaque string generated by your application. This value is used to prevent Cross-Site Request Forgery (CSRF) attacks. You should generate a unique value for each authorization request and store it (e.g., in the user's session) to verify later. **Example Authorization URL:** ```text https://api.instantdb.com/platform/oauth/start?client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=YOUR_REDIRECT_URI&scope=apps-read%20apps-write&state=RANDOM_STATE_STRING ``` When the user visits this URL, they will be prompted by Instant to log in (if they aren't already) and asked to grant your application the requested permissions (scopes). ### 3. Handle the Redirect from Instant After the user grants or denies authorization, Instant redirects them back to the `redirect_uri` you specified. **If Successful:** The redirect URL will include `code` and `state` query parameters: ```text YOUR_REDIRECT_URI?code=AUTHORIZATION_CODE&state=RANDOM_STATE_STRING ``` - **Verify the `state` parameter:** Check that the received `state` value matches the one you generated in Step 2 for this user. If they don't match, reject the request to prevent CSRF attacks. - **Extract the `code`:** This is a short-lived, single-use authorization code. **If Unsuccessful:** The redirect URL will include `error` and potentially `error_description` parameters: ```text YOUR_REDIRECT_URI?error=access_denied&state=RANDOM_STATE_STRING ``` Handle these errors appropriately (e.g., display a message to the user). ### 4. Exchange Authorization Code for Tokens Once you have verified the `state` and obtained the `code`, exchange the code for an access token and a refresh token by making a `POST` request from your backend server to the Instant token endpoint. **Endpoint:** ```text https://api.instantdb.com/platform/oauth/token ``` **Method:** `POST` **Headers:** - `Content-Type: application/json` **Request Body (JSON):** ```json { "grant_type": "authorization_code", "code": "YOUR_AUTHORIZATION_CODE", // The code from Step 3 "redirect_uri": "YOUR_REDIRECT_URI", // The same redirect URI used in Step 2 "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET" } ``` **Example `curl`:** ```bash export CLIENT_ID="YOUR_CLIENT_ID" export CLIENT_SECRET="YOUR_CLIENT_SECRET" export REDIRECT_URI="YOUR_REDIRECT_URI" export CODE="YOUR_AUTHORIZATION_CODE" curl -v -X POST "https://api.instantdb.com/platform/oauth/token" \ -H "Content-Type: application/json" \ -d "{ \"client_id\": \"$CLIENT_ID\", \"client_secret\": \"$CLIENT_SECRET\", \"redirect_uri\": \"$REDIRECT_URI\", \"grant_type\": \"authorization_code\", \"code\": \"$CODE\" }" ``` **Successful Response (JSON):** ```json { "access_token": "ACCESS_TOKEN_VALUE", "refresh_token": "REFRESH_TOKEN_VALUE", "expires_in": 1209600, // Lifetime in seconds (e.g., 2 weeks) "scope": "apps-read apps-write", // Scopes granted "token_type": "Bearer" } ``` - **`access_token`**: The token used to authenticate API requests on behalf of the user. It has a limited lifetime (`expires_in`). - **`refresh_token`**: A long-lived token used to obtain new access tokens when the current one expires. Store this securely, associated with the user. - **`expires_in`**: The number of seconds until the `access_token` expires. - **`scope`**: The actual scopes granted by the user (may be different from requested). Store the `access_token`, `refresh_token`, and expiration time securely on your backend, associated with the user who authorized your application. ### 5. Use the Access Token To make authenticated API calls to Instant on behalf of the user, include the `access_token` in the `Authorization` header of your requests: ```text Authorization: Bearer ACCESS_TOKEN_VALUE ``` **Example `curl` (Fetching User's Apps):** ```bash export ACCESS_TOKEN="ACCESS_TOKEN_VALUE" curl -v "https://api.instantdb.com/superadmin/apps" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` This allows you to perform actions permitted by the granted scopes. ### 6. Refresh the Access Token Access tokens expire. When an access token expires, or shortly before it does, use the `refresh_token` obtained in Step 4 to get a new `access_token` without requiring the user to go through the authorization flow again. Make a `POST` request from your **backend server** to the token endpoint: **Endpoint:** ```text https://api.instantdb.com/platform/oauth/token ``` **Method:** `POST` **Headers:** - `Content-Type: application/json` **Request Body (JSON):** ```json { "grant_type": "refresh_token", "refresh_token": "REFRESH_TOKEN_VALUE", // The refresh token stored earlier "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET" } ``` **Example `curl`:** ```bash export CLIENT_ID="YOUR_CLIENT_ID" export CLIENT_SECRET="YOUR_CLIENT_SECRET" export REFRESH_TOKEN="REFRESH_TOKEN_VALUE" curl -v -X POST "[https://api.instantdb.com/platform/oauth/token](https://api.instantdb.com/platform/oauth/token)" \ -H "Content-Type: application/json" \ -d "{ \"client_id\": \"$CLIENT_ID\", \"client_secret\": \"$CLIENT_SECRET\", \"grant_type\": \"refresh_token\", \"refresh_token\": \"$REFRESH_TOKEN\" }" ``` **Successful Response (JSON):** The response format is similar to the code exchange, providing a _new_ access token and potentially a _new_ refresh token: ```json { "access_token": "NEW_ACCESS_TOKEN_VALUE", "refresh_token": "NEW_REFRESH_TOKEN_VALUE", // May or may not be included/changed "expires_in": 1209600, "scope": "apps-read apps-write", "token_type": "Bearer" } ``` - Update the stored access token and expiration time for the user. - If the refresh token request fails (e.g., the refresh token was revoked), you will need to direct the user through the authorization flow (Step 2) again. ### 7. Invalidate a token You can invalidate an access token or a refresh token through the `revoke` endpoint. **Endpoint:** ```text https://api.instantdb.com/platform/oauth/revoke ``` **Method:** `POST` **Query Parameters:** - `token` (Required): The token you want to invalidate **Example URL:** ```text https://api.instantdb.com/platform/oauth/revoke?token=YOUR_TOKEN ``` ## Endpoints ### List Apps - **Description:** Retrieves a list of all applications created by the authenticated user. - **Method:** `GET` - **Path:** `/superadmin/apps` - **Authentication:** Required (Bearer Token) - **Required OAuth Scope:** `apps-read` - **Success Response:** - Code: `200 OK` - Body: ```json { "apps": [ { "id": "uuid", "title": "string", "creator_id": "uuid", "created_at": "timestamp" } // ... more apps ] } ``` ### Get App Details - **Description:** Retrieves details for a specific application. - **Method:** `GET` - **Path:** `/superadmin/apps/:app_id` - **Authentication:** Required (Bearer Token) - **Required OAuth Scope:** `apps-read` - **Path Parameters:** - `app_id` (UUID, required): The ID of the application to retrieve. The authenticated user must be the creator. - **Success Response:** - Code: `200 OK` - Body: ```json { "app": { "id": "uuid", "title": "string", "creator_id": "uuid", "created_at": "timestamp" } } ``` - **Error Responses:** - `404 Not Found`: If the app doesn't exist or doesn't belong to the user. ### Create App - **Description:** Creates a new application. - **Method:** `POST` - **Path:** `/superadmin/apps` - **Authentication:** Required (Bearer Token) - **Required OAuth Scope:** `apps-write` - **Request Body:** ```json { "title": "New App Name" } ``` - `title` (string, required): The desired name for the new application. Must not be blank. - **Success Response:** - Code: `200 OK` - Body: ```json { "app": { "id": "uuid", "title": "string", "creator_id": "uuid", "created_at": "timestamp" } } ``` ### Update App (Rename) - **Description:** Updates the details of a specific application (currently only supports renaming). - **Method:** `POST` - **Path:** `/superadmin/apps/:app_id` - **Authentication:** Required (Bearer Token) - **Required OAuth Scope:** `apps-write` - **Path Parameters:** - `app_id` (UUID, required): The ID of the application to update. The authenticated user must be the creator. - **Request Body:** ```json { "title": "New App Name" } ``` - `title` (string, required): The new desired name for the application. Must not be blank. - **Success Response:** - Code: `200 OK` - Body: ```json { "app": { "id": "uuid", "title": "string", "creator_id": "uuid", "created_at": "timestamp" } } ``` - **Error Responses:** - `404 Not Found`: If the app doesn't exist or doesn't belong to the user. - `400 Bad Request`: If the title is blank or invalid. ### Delete App - **Description:** Marks an application for deletion. The app data may be retained for a period before permanent removal. - **Method:** `DELETE` - **Path:** `/superadmin/apps/:app_id` - **Authentication:** Required (Bearer Token) - **Required OAuth Scope:** `apps-write` - **Path Parameters:** - `app_id` (UUID, required): The ID of the application to delete. The authenticated user must be the creator. - **Success Response:** - Code: `200 OK` - Body: ```json { "app": { "id": "uuid", "title": "string", "creator_id": "uuid", "created_at": "timestamp" } } ``` - **Error Responses:** - `404 Not Found`: If the app doesn't exist or doesn't belong to the user. ### Get Permissions (Rules) - **Description:** Retrieves the current permission rules for the application. - **Method:** `GET` - **Path:** `/superadmin/apps/:app_id/perms` - **Authentication:** Required (Bearer Token) - **Required OAuth Scope:** `apps-read` - **Path Parameters:** - `app_id` (UUID, required): The ID of the application. - **Success Response:** - Code: `200 OK` - Body: ```json { "perms": { // Permissions code object // e.g., {"posts": {"allow": {"read": "true", "create": "auth.id != null"}}} } } ``` ### Set Permissions (Rules) - **Description:** Overwrites the existing permission rules for the application with the provided definition. - **Method:** `POST` - **Path:** `/superadmin/apps/:app_id/perms` - **Authentication:** Required (Bearer Token) - **Required OAuth Scope:** `apps-write` - **Path Parameters:** - `app_id` (UUID, required): The ID of the application. - **Request Body:** ```json { "code": { // Permissions code object // e.g., {"posts": {"allow": {"read": "true", "create": "false"}}} } } ``` - `code` (object, required): The complete permission rules definition. - **Success Response:** - Code: `200 OK` - Body: ```json { "rules": { // Permissions code object // e.g., {"posts": {"allow": {"read": "true", "create": "false"}}} } } ``` - **Error Responses:** - `400 Bad Request`: If the provided `code` object fails validation. ### Get schema - **Description:** Views the schema for the app. - **Method:** `POST` - **Path:** `/superadmin/apps/:app_id/schema` - **Authentication:** Required (Bearer Token) - **Required OAuth Scope:** `apps-read` - **Path Parameters:** - `app_id` (UUID, required): The ID of the application. - **Success Response:** - Code: `200 OK` - Body: An object detailing the planned schema changes. ```json { "schema": { "blobs": { "namespace-name": { "attribute-name": { "id": "uuid", "cardinality": "one | many", "forward-identity": ["uuid", "namespace-name", "attribute-name"], "index?": "boolean", "unique?": "boolean", "checked-data-type": "'string' | 'number' | 'boolean' | 'date' | null" } } // Rest of blob attrs }, "refs": { "ref-string": { "id": "uuid", "cardinality": "one | many", "forward-identity": ["uuid", "namespace-name", "attribute-name"], "reverse-identity": [ "uuid", "linked-namespace-name", "linked-attribute-name" ], "index?": "boolean", "unique?": "boolean" } // Rest of ref attrs } } } ``` ### Plan Schema Push - **Description:** Calculates the changes required to apply a new schema definition without actually applying them. Useful for previewing migrations. - **Method:** `POST` - **Path:** `/superadmin/apps/:app_id/schema/push/plan` - **Authentication:** Required (Bearer Token) - **Required OAuth Scope:** `apps-read` - **Path Parameters:** - `app_id` (UUID, required): The ID of the application. - **Request Body:** ```json { "schema": { "entities": { "namespace-name": { "attrs": { "attribute-name": { "valueType": "'string' | 'number' | 'boolean' | 'date' | 'json'", "config": { "indexed": "boolean", "unique": "boolean" } } } } // Rest of entities }, "links": { "unique-string": { "forward": { "on": "forward-namespace-name", "label": "forward-attr-label", "has": "many | one", "onDelete": "cascade | null" }, "reverse": { "on": "reverse-namespace-name", "label": "reverse-attr-label", "has": "many | one" "onDelete": "cascade | null" } } // Rest of link attrs } } } ``` - `schema` (object, required): An object with `entities` and `links` that matches the structure of [instant.schema.ts](/docs/modeling-data#instant-schema-ts) - **Success Response:** - Code: `200 OK` - Body: ```json { "current-schema": "schema object (same structure as GET schema)", "new-schema": "schema object (same structure as GET schema)", "steps": [ [ "add-attr", { "id": "uuid", "cardinality": "one | many", "forward-identity": ["uuid", "namespace-name", "attribute-name"], "index?": "boolean", "unique?": "boolean", "checked-data-type": "'string' | 'number' | 'boolean' | 'date' | null" } ], [ "add-attr", { "id": "uuid", "cardinality": "one | many", "forward-identity": ["uuid", "namespace-name", "attribute-name"], "index?": "boolean", "unique?": "boolean", "checked-data-type": "'string' | 'number' | 'boolean' | 'date' | null" } ], [ "index", { "attr-id": "uuid", "forward-identity": ["uuid", "namespace-name", "attribute-name"] } ], [ "remove-index", { "attr-id": "uuid", "forward-identity": ["uuid", "namespace-name", "attribute-name"] } ], [ "unique", { "attr-id": "uuid", "forward-identity": ["uuid", "namespace-name", "attribute-name"] } ], [ "remove-unique", { "attr-id": "uuid", "forward-identity": ["uuid", "namespace-name", "attribute-name"] } ], [ "check-data-type", { "attr-id": "uuid",, "checked-data-type": "'string' | 'boolean' | 'number' | 'date'", "forward-identity": ["uuid", "namespace-name", "attribute-name"] } ], [ "remove-data-type", { "attr-id": "uuid", "forward-identity": ["uuid", "namespace-name", "attribute-name"] } ] ] } ``` ### Apply Schema Push - **Description:** Calculates and applies the schema changes based on the provided definition. - **Method:** `POST` - **Path:** `/superadmin/apps/:app_id/schema/push/apply` - **Authentication:** Required (Bearer Token) - **Required OAuth Scope:** `apps-write` - **Path Parameters:** - `app_id` (UUID, required): The ID of the application. - **Request Body:** Same as "Plan Schema Push". ```json { "schema": { "entities": { "namespace-name": { "attrs": { "attribute-name": { "valueType": "'string' | 'number' | 'boolean' | 'date' | 'json'", "config": { "indexed": "boolean", "unique": "boolean" } } } } // Rest of entities }, "links": { "unique-string": { "forward": { "on": "forward-namespace-name", "label": "forward-attr-label", "has": "many | one", "onDelete": "cascade | null" }, "reverse": { "on": "reverse-namespace-name", "label": "reverse-attr-label", "has": "many | one" "onDelete": "cascade | null" } } // Rest of link attrs } } } ``` - `schema` (object, required): An object with `entities` and `links` that matches the structure of [instant.schema.ts](/docs/modeling-data#instant-schema-ts) - **Success Response:** - Code: `200 OK` - Body: ```json { "current-schema": "schema object (same structure as GET schema)", "new-schema": "schema object (same structure as GET schema)", "steps": [ [ "add-attr", { "id": "uuid", "cardinality": "one | many", "forward-identity": ["uuid", "namespace-name", "attribute-name"], "index?": "boolean", "unique?": "boolean", "checked-data-type": "'string' | 'number' | 'boolean' | 'date' | null" } ], [ "add-attr", { "id": "uuid", "cardinality": "one | many", "forward-identity": ["uuid", "namespace-name", "attribute-name"], "index?": "boolean", "unique?": "boolean", "checked-data-type": "'string' | 'number' | 'boolean' | 'date' | null" } ], [ "index", { "attr-id": "uuid", "forward-identity": ["uuid", "namespace-name", "attribute-name"] } ], [ "remove-index", { "attr-id": "uuid", "forward-identity": ["uuid", "namespace-name", "attribute-name"] } ], [ "unique", { "attr-id": "uuid", "forward-identity": ["uuid", "namespace-name", "attribute-name"] } ], [ "remove-unique", { "attr-id": "uuid", "forward-identity": ["uuid", "namespace-name", "attribute-name"] } ], [ "check-data-type", { "attr-id": "uuid",, "checked-data-type": "'string' | 'boolean' | 'number' | 'date'", "forward-identity": ["uuid", "namespace-name", "attribute-name"] } ], [ "remove-data-type", { "attr-id": "uuid", "forward-identity": ["uuid", "namespace-name", "attribute-name"] } ] ] } ``` # 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; ``` Right now `$users` is a read-only namespace. You can override the `view` permission to whatever you like, but `create`, `delete`, and `update` are restricted. ## Adding properties Although you cannot directly add properties to the `$users` namespace, you can create links to other namespaces. Here is an example of a schema for a todo app that has users, roles, profiles, and todos: ```javascript // instant.schema.ts import { i } from '@instantdb/react'; const _schema = i.schema({ entities: { $users: i.entity({ email: i.any().unique().indexed(), }), profiles: i.entity({ nickname: i.string(), // We can't add this directly to `$users` userId: i.string().unique(), }), roles: i.entity({ type: i.string().unique(), // We couldn't add this directly to `$users` either }), todos: i.entity({ text: i.string(), userId: i.string(), completed: i.boolean(), }), }, links: { // `$users` is in the reverse direction for all these links! todoOwner: { forward: { on: 'todos', has: 'one', label: 'owner' }, reverse: { on: '$users', has: 'many', label: 'todos'}, }, userRoles: { forward: { on: 'roles', has: 'many', label: 'users' }, reverse: { on: '$users', has: 'one', label: 'role' }, }, userProfiles: { forward: { on: 'profiles', has: 'one', label: 'user' }, reverse: { on: '$users', has: 'one', label: 'profile' }, }, }, }); // 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 three links `todoOwner`, `userRoles`, and `userProfiles` to link the `$users` namespace to the `todos`, `roles`, and `profiles` namespaces respectively: ```typescript // instant.schema.ts import { i } from '@instantdb/react'; const _schema = i.schema({ // .. links: { // `$users` is in the reverse direction for all these links! todoOwner: { forward: { on: 'todos', has: 'one', label: 'owner' }, reverse: { on: '$users', has: 'many', label: 'todos' }, }, userRoles: { forward: { on: 'roles', has: 'many', label: 'users' }, reverse: { on: '$users', has: 'one', label: 'role' }, }, userProfiles: { forward: { on: 'profiles', has: 'one', label: 'user' }, reverse: { on: '$users', has: 'one', label: 'profile' }, }, }, }); ``` Notice that the `$users` namespace is in the reverse direction for all links. If you try to create a link with `$users` in the forward direction, you'll get an error. ### Attributes Now take a look at the `profiles` namespace: ```typescript // instant.schema.ts import { i } from '@instantdb/react'; const _schema = i.schema({ entities: { // ... profiles: i.entity({ nickname: i.string(), // We can't add this directly to `$users` }), }, // ... }); ``` You may be wondering why we didn't add `nickname` directly to the `$users` namespace. This is because the `$users` namespace is read-only and we cannot add properties to it. If you want to add additional properties to a user, you'll need to create a new namespace and link it to `$users`. --- 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( tx.todos[newId] .update({ text: newTodo, userId: currentUser.id, 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) => { const profileId = lookup('email', currentUser.email); db.transact([ tx.profiles[profileId] .update({ userId: currentUser.id, nickname: newNick }) // Link the profile to the user with the `user` label we defined in the schema .link({ user: currentUser.id }), ]); }; ``` If attr creation on the client [is enabled](/docs/permissions#attrs), you can also create new links without having to define them in the schema. In this case you can only link to `$users` and not from `$users`. ```javascript // Comments is a new namespace! We haven't defined it in the schema. // ✅ This works! const commentId = id() db.transact( tx.comments[commentId].update({ text: 'Hello world', userId: currentUser.id }) .link({ $user: currentUser.id })); // ❌ This will not work! Cannot create a forward link on the fly const commentId = id() db.transact([ tx.comments[id()].update({ text: 'Hello world', userId: currentUser.id }), tx.$users[currentUser.id].link({ comment: commentId }))]); // ❌ This will also not work! Cannot create new properties on `$users` db.transact(tx.$users[currentUser.id].update({ nickname: "Alyssa" })) ``` ## 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.role.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 don'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. ```typescript 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 to the room useEffect(() => { publishPresence({ name: user.name }); }, []); if (!myPresence) { return

App loading...

; } return (

Who's online?

You are: {myPresence.name}

Others:

    {/* 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]) => (
  • {peer.name}
    • ))}
); } ``` `usePresence` accepts a second parameter to select specific slices of 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 examples page](https://www.instantdb.com/examples?#5-reactions) ```typescript '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; }>(refsInit); return (
{emojiNames.map((name) => (
))}
); } // 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()]) ); 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) { 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 `` component! ```typescript '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 (
Open two tabs, and move your cursor around!
); } ``` You can provide a `renderCursor` function to return your own custom cursor component. ```typescript ``` 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 `` element with their own `spaceId`. ```typescript {tabs.map((tab) => ( {/* ... */} ))} ``` ### Typing indicators `useTypingIndicator` is a small utility useful for building inputs for chat-style apps. You can use this hook to show things like " is typing..." in your chat app. ```javascript '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 (