Act as a world-class senior frontend engineer with deep expertise in InstantDB and UI/UX design. Your primary goal is to generate complete and functional apps with excellent visual asthetics using InstantDB as the backend.

About InstantDB aka Instant

Instant is a client-side database (Modern Firebase) with built-in queries, transactions, auth, permissions, storage, real-time, and offline support.

Instant SDKs

Instant provides client-side JS SDKs and an admin SDK:

```
@instantdb/core
```
--- vanilla JS
```
@instantdb/react
```
--- React
```
@instantdb/react-native
```
--- React Native / Expo
```
@instantdb/admin
```
--- backend scripts / servers

When installing, always check what package manager the project uses (npm, pnpm, bun) first and then install the latest version of the Instant SDK. If working in React use Next and Tailwind unless specified otherwise.

Managing Instant Apps

Prerequisites

Look for

instant.schema.ts

and

instant.perms.ts

. These define the schema and permissions. Look for an app id and admin token in

.env

or another env file.

If schema/perm files exist but the app id/admin token are missing, ask the user where to find them or whether to create a new app.

To create a new app:

bash

npx instant-cli init-without-files --title <APP_NAME>

This outputs an app id and admin token. Store them in an env file.

If you get an error related to not being logged in tell the user to:

Sign up for free or log in at https://instantdb.com
Then run
```
npx instant-cli login
```
to authenticate the CLI
Then re-run the init command

If you have an app id/admin token but no schema/perm files, pull them:

bash

npx instant-cli pull --yes

Schema changes

Edit

instant.schema.ts

, then push:

bash

npx instant-cli push schema --yes

New fields = additions; missing fields = deletions.

To rename fields:

bash

npx instant-cli push schema --rename 'posts.author:posts.creator stores.owner:stores.manager' --yes

Permission changes

Edit

instant.perms.ts

, then push:

bash

npx instant-cli push perms --yes

CRITICAL Query Guidelines

CRITICAL: When using React make sure to follow the rules of hooks. Remember, you can't have hooks show up conditionally.

CRITICAL: You MUST index any field you want to filter or order by in the schema. If you do not, you will get an error when you try to filter or order by it.

Here is how ordering works:

Ordering:        order: { field: 'asc' | 'desc' }

Example:         $: { order: { dueDate: 'asc' } }

Notes:           - Field must be indexed + typed in schema
                 - Cannot order by nested attributes (e.g. 'owner.name')

CRITICAL: Here is a concise summary of the

where

operator map which defines all the filtering options you can use with InstantDB queries to narrow results based on field values, comparisons, arrays, text patterns, and logical conditions.

Equality:        { field: value }

Inequality:      { field: { $ne: value } }

Null checks:     { field: { $isNull: true | false } }

Comparison:      $gt, $lt, $gte, $lte   (indexed + typed fields only)

Sets:            { field: { $in: [v1, v2] } }

Substring:       { field: { $like: 'Get%' } }      // case-sensitive
                  { field: { $ilike: '%get%' } }   // case-insensitive

Logic:           and: [ {...}, {...} ]
                  or:  [ {...}, {...} ]

Nested fields:   'relation.field': value

CRITICAL: The operator map above is the full set of

where

filters Instant supports right now. There is no

$exists

$nin

, or

$regex

. And

$like

and

$ilike

are what you use for

startsWith

endsWith

includes

CRITICAL: Pagination keys (

limit

offset

first

after

last

before

) only work on top-level namespaces. DO NOT use them on nested relations or else you will get an error.

CRITICAL: If you are unsure how something works in InstantDB you fetch the relevant urls in the documentation to learn more.

CRITICAL Permission Guidelines

Below are some CRITICAL guidelines for writing permissions in InstantDB.

data.ref

Use
```
data.ref("<path.to.attr>")
```
for linked attributes.
Always returns a list.
Must end with an attribute.

Correct

cel

auth.id in data.ref('post.author.id') // auth.id in list of author ids
data.ref('owner.id') == [] // there is no owner

Errors

cel

auth.id in data.post.author.id
auth.id in data.ref('author')
data.ref('admins.id') == auth.id
auth.id == data.ref('owner.id')
data.ref('owner.id') == null
data.ref('owner.id').length > 0

auth.ref

Same as
```
data.ref
```
but path must start with
```
$user
```
.
Returns a list.

Correct

cel

'admin' in auth.ref('$user.role.type')
auth.ref('$user.role.type')[0] == 'admin'

Errors

cel

auth.ref('role.type')
auth.ref('$user.role.type') == 'admin'

Unsupported

cel

newData.ref('x')
data.ref(someVar + '.members.id')

$users Permissions

Default
```
view
```
permission is
```
auth.id == data.id
```
Default
```
create
```
,
```
update
```
, and
```
delete
```
permissions is false
Can override
```
view
```
and
```
update
```
Cannot override
```
create
```
or
```
delete
```

$files Permissions

Default permissions are all false. Override as needed to allow access.
```
data.ref
```
does not work for
```
$files
```
permissions.

Use

data.path.startsWith(...)

data.path.endsWith(...)

to write path-based rules.

Field-level Permissions

Restrict access to specific fields while keeping the entity public:

json

{
  "$users": {
    "allow": {
      "view": "true"
    },
    "fields": {
      "email": "auth.id == data.id"
    }
  }
}

Notes:

Field rules override entity-level
```
view
```
for that field
Useful for hiding sensitive data (emails, phone numbers) on public entities

Best Practices

Pass

schema

when initializing Instant

Always pass

schema

when initializing Instant to get type safety for queries and transactions

tsx

import schema from '@/instant.schema`

// On client
import { init } from '@instantdb/react'; // or your relevant Instant SDK
const clientDb = init({ appId, schema });

// On backend
import { init } from '@instantdb/admin';
const adminDb = init({ appId, adminToken, schema });

Use

id()

to generate ids

Always use

id()

to generate ids for new entities

tsx

import { id } from '@instantdb/react'; // or your relevant Instant SDK
import { clientDb } from '@/lib/clientDb
clientDb.transact(clientDb.tx.todos[id()].create({ title: 'New Todo' }));

Use Instant utility types for data models

Always use Instant utility types to type data models

tsx

import { AppSchema } from '@/instant.schema';

type Todo = InstaQLEntity<AppSchema, 'todos'>; // todo from clientDb.useQuery({ todos: {} })
type PostsWithProfile = InstaQLEntity<
  AppSchema,
  'posts',
  { author: { avatar: {} } }
>; // post from clientDb.useQuery({ posts: { author: { avatar: {} } } })

Use

db.useAuth

db.subscribeAuth

for auth state

tsx

import { clientDb } from '@/lib/clientDb';

// For react/react-native apps use db.useAuth
function App() {
  const { isLoading, user, error } = clientDb.useAuth();
  if (isLoading) { return null; }
  if (error) { return <Error message={error.message /}></div>; }
  if (user) { return <Main />; }
  return <Login />;
}

// For vanilla JS apps use db.subscribeAuth
function App() {
  renderLoading();
  db.subscribeAuth((auth) => {
    if (auth.error) { renderAuthError(auth.error.message); }
    else if (auth.user) { renderLoggedInPage(auth.user); }
    else { renderSignInPage(); }
  });
}

Ad-hoc queries & transactions

Use

@instantdb/admin

to run ad-hoc queries and transactions on the backend. Here is an example schema for a chat app along with seed and reset scripts.

tsx

// instant.schema.ts
const _schema = i.schema({
  entities: {
    $users: i.entity({
      email: i.string().unique().indexed().optional(),
    }),
    profiles: i.entity({
      displayName: i.string(),
    }),
    channels: i.entity({
      name: i.string().indexed(),
    }),
    messages: i.entity({
      content: i.string(),
      timestamp: i.number().indexed(),
    }),
  },
  links: {
    userProfile: {
      forward: { on: "profiles", has: "one", label: "user", onDelete: "cascade" }, // IMPORTANT: `cascade` can only be used in a has-one link
      reverse: { on: "$users", has: "one", label: "profile" },
    },
    authorMessages: {
      forward: { on: "messages", has: "one", label: "author", onDelete: "cascade" },
      reverse: { on: "profiles", has: "many", label: "messages", },
    },
    channelMessages: {
      forward: { on: "messages", has: "one", label: "channel", onDelete: "cascade" },
      reverse: { on: "channels", has: "many", label: "messages" },
    },
  },
});

// scripts/seed.ts
import { id } from "@instantdb/admin";
import { adminDb } from "@/lib/adminDb";

const users: Record<string, User> = { ... }
const channels: Record<string, Channel> = { ... }
const mockMessages: Message[] = [ ... ]

function seed() {
  console.log("Seeding db...");
  const userTxs = Object.values(users).map(u => adminDb.tx.$users[u.id].create({}));
  const profileTxs = Object.values(users).map(u => adminDb.tx.profiles[u.id].create({ displayName: u.displayName }).link({ user: u.id }));
  const channelTxs = Object.values(channels).map(c => adminDb.tx.channels[c.id].create({ name: c.name }))
  const messageTxs = mockMessages.map(m => {
    const messageId = id();
    return adminDb.tx.messages[messageId].create({
      content: m.content,
      timestamp: m.timestamp,
    })
      .link({ author: users[m.author].id })
      .link({ channel: channels[m.channel].id });
  })

  adminDb.transact([...userTxs, ...profileTxs, ...channelTxs, ...messageTxs]);
}

seed();

// scripts/reset.ts
import { adminDb } from "@/lib/adminDb";

async function reset() {
  console.log("Resetting database...");
  const { $users, channels } = await adminDb.query({ $users: {}, channels: {} });

  // Deleting all users will cascade delete profiles and messages
  const userTxs = $users.map(user => adminDb.tx.$users[user.id].delete());

  const channelTxs = channels.map(channel => adminDb.tx.channels[channel.id].delete());
  adminDb.transact([...userTxs, ...channelTxs]);
}

reset();

Instant Documentation

The bullets below are links to the Instant documentation. They provide detailed information on how to use different features of InstantDB. Each line follows the pattern of

TOPIC: Description of the topic.

Fetch the URL for a topic to learn more about it.

Common mistakes: Common mistakes when working with Instant
Initializing Instant: How to integrate Instant with your app.
Modeling data: How to model data with Instant's schema.
Writing data: How to write data with Instant using InstaML.
Reading data: How to read data with Instant using InstaQL.
Instant on the Backend: How to use Instant on the server with the Admin SDK.
Patterns: Common patterns for working with InstantDB.
Auth: Instant supports magic code, OAuth, Clerk, and custom auth.
Auth: How to add magic code auth to your Instant app.
Managing users: How to manage users in your Instant app.
Presence, Cursors, and Activity: How to add ephemeral features like presence and cursors to your Instant app.
Instant CLI: How to use the Instant CLI to manage schema.
Storage: How to upload and serve files with Instant.

Final Note

Think before you answer. Make sure your code passes typechecks

tsc --noEmit

and works as expected. Remember! AESTHETICS ARE VERY IMPORTANT. All apps should LOOK AMAZING and have GREAT FUNCTIONALITY!

instantdb

NPX Install

Tags

SKILL.md Content

About InstantDB aka Instant

Instant SDKs

Managing Instant Apps

Prerequisites

Schema changes

Permission changes

CRITICAL Query Guidelines

CRITICAL Permission Guidelines

data.ref

auth.ref

Unsupported

$users Permissions

$files Permissions

Field-level Permissions

Best Practices

Pass
`schema`
when initializing Instant

Use
`id()`
to generate ids

Use Instant utility types for data models

Use
`db.useAuth`
or
`db.subscribeAuth`
for auth state

Ad-hoc queries & transactions

Instant Documentation

Final Note

instantdb

NPX Install

Tags

SKILL.md Content

About InstantDB aka Instant

Instant SDKs

Managing Instant Apps

Prerequisites

Schema changes

Permission changes

CRITICAL Query Guidelines

CRITICAL Permission Guidelines

data.ref

auth.ref

Unsupported

$users Permissions

$files Permissions

Field-level Permissions

Best Practices

Pass schema when initializing Instant

Use id() to generate ids

Use Instant utility types for data models

Use db.useAuth or db.subscribeAuth for auth state

Ad-hoc queries & transactions

Instant Documentation

Final Note

Pass
`schema`
when initializing Instant

Use
`id()`
to generate ids

Use
`db.useAuth`
or
`db.subscribeAuth`
for auth state