insforge

What this skill does

# InsForge App Integration Skill

This skill covers application code and integration work with InsForge, primarily through `@insforge/sdk`. For backend infrastructure operations (creating tables, inspecting schema, deploying functions, secrets, managing storage buckets, configuring Stripe keys/catalog, website deployments, cron job and schedules, logs, etc.), use the **insforge-cli** skill.

## Quick Setup

### 1. Install the SDK

```bash
npm install @insforge/sdk@latest
```

### 2. Set up environment variables

Before using the SDK, create a `.env` file (or `.env.local` for Next.js) in your project root with your InsForge URL and anon key.

#### How to get your URL and anon key

1. **Ensure the project is linked.** Check for `.insforge/project.json` in the project root.
   - Generate it with `npx @insforge/cli link` for an existing project or `npx @insforge/cli create` for a new project.

2. **Get the anon key** via the CLI:

   ```bash
   npx @insforge/cli secrets get ANON_KEY
   ```

3. **Get the URL** from the `oss_host` field in `.insforge/project.json` (e.g., `https://myapp.us-east.insforge.app`).

4. **Write both values** to the `.env` file using the correct framework prefix (see table below).

> **Important:** Use the anon key for user-scoped SDK clients, including SSR. For privileged server-only app code that needs admin/service access, use `createAdminClient({ apiKey })`; the API key is a full-access admin key, equivalent to a service role key on other platforms.

Use the correct environment variable prefix and access pattern for your framework:

| Framework                     | `.env` file  | Variables                                                   | Access Pattern                              |
| ----------------------------- | ------------ | ----------------------------------------------------------- | ------------------------------------------- |
| **Next.js**                   | `.env.local` | `NEXT_PUBLIC_INSFORGE_URL`, `NEXT_PUBLIC_INSFORGE_ANON_KEY` | `process.env.NEXT_PUBLIC_*`                 |
| **Vite** (React, Vue, Svelte) | `.env`       | `VITE_INSFORGE_URL`, `VITE_INSFORGE_ANON_KEY`               | `import.meta.env.VITE_*`                    |
| **Astro**                     | `.env`       | `PUBLIC_INSFORGE_URL`, `PUBLIC_INSFORGE_ANON_KEY`           | `import.meta.env.PUBLIC_*`                  |
| **SvelteKit**                 | `.env`       | `PUBLIC_INSFORGE_URL`, `PUBLIC_INSFORGE_ANON_KEY`           | `import { env } from '$env/dynamic/public'` |
| **Create React App**          | `.env`       | `REACT_APP_INSFORGE_URL`, `REACT_APP_INSFORGE_ANON_KEY`     | `process.env.REACT_APP_*`                   |
| **Node.js / Server**          | `.env`       | `INSFORGE_URL`, `INSFORGE_ANON_KEY`                         | `process.env.*`                             |

Example `.env.local` for Next.js:

```bash
NEXT_PUBLIC_INSFORGE_URL=https://your-appkey.us-east.insforge.app
NEXT_PUBLIC_INSFORGE_ANON_KEY=eyJhbGciOiJIUzI1NiIs...
```

> **Important:** Keep `.env` files local. Add `.env`, `.env.local`, and `.env*.local` to your `.gitignore` and keep `.env.example` for documenting required variables.

### 3. Initialize the client

Next.js:

```javascript
import { createClient } from '@insforge/sdk'

const insforge = createClient({
  baseUrl: process.env.NEXT_PUBLIC_INSFORGE_URL,
  anonKey: process.env.NEXT_PUBLIC_INSFORGE_ANON_KEY
})
```

Vite:

```javascript
import { createClient } from '@insforge/sdk'

const insforge = createClient({
  baseUrl: import.meta.env.VITE_INSFORGE_URL,
  anonKey: import.meta.env.VITE_INSFORGE_ANON_KEY
})
```

Astro:

```javascript
import { createClient } from '@insforge/sdk'

const insforge = createClient({
  baseUrl: import.meta.env.PUBLIC_INSFORGE_URL,
  anonKey: import.meta.env.PUBLIC_INSFORGE_ANON_KEY
})
```

For trusted server-only code that needs project-admin access:

```javascript
import { createAdminClient } from "@insforge/sdk";

const admin = createAdminClient({
  baseUrl: process.env.INSFORGE_URL,
  apiKey: process.env.INSFORGE_API_KEY,
});
```

## Module Reference

| Module        | Integration Guide                                            |
| ------------- | ------------------------------------------------------------ |
| **Database**  | [database/sdk-integration.md](database/sdk-integration.md)   |
| **Auth**      | [auth/sdk-integration.md](auth/sdk-integration.md)           |
| **Storage**   | [storage/sdk-integration.md](storage/sdk-integration.md)     |
| **Functions** | [functions/sdk-integration.md](functions/sdk-integration.md) |
| **AI**        | [ai/overview.md](ai/overview.md)                             |
| **Real-time** | [realtime/sdk-integration.md](realtime/sdk-integration.md)   |
| **Email**     | [email/sdk-integration.md](email/sdk-integration.md)         |
| **Payments**  | [payments/sdk-integration.md](payments/sdk-integration.md)   |

### What Each Module Covers

| Module        | Content                                                                                                       |
| ------------- | ------------------------------------------------------------------------------------------------------------- |
| **Database**  | CRUD operations, filters, pagination, RPC calls                                                               |
| **Auth**      | Sign up/in, OAuth, sessions, profiles, password reset                                                         |
| **Storage**   | Upload, download, delete files; S3-compatible gateway for CI / backup tooling; write RLS policies for buckets |
| **Functions** | Invoke edge functions                                                                                         |
| **AI**        | OpenRouter AI calls for chat, images, video, audio, embeddings, and model discovery                           |
| **Email**     | Send custom transactional HTML emails (welcome, newsletter, notifications)                                    |
| **Payments**  | Stripe Checkout Sessions, subscriptions, and Billing Portal redirects                                         |
| **Real-time** | Connect, subscribe, publish events, and track presence snapshots plus join/leave deltas                       |

### Guides

| Guide                                                                                                          | When to Use                                                                                                                                                                                                                                                                                                                                                                                            |
| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [../insforge-cli/references/database/access-control.md](../insforge-cli/references/database/access-control.md) | Backend setup for application-table access control — covers RLS, infinite recursion prevention, `SECURITY DEFINER` patterns, performance tips, and common InsForge patterns                                                                                                                                                                                                                            |
| [storage/s3-gateway.md](storage/s3-gateway.md)                                                                 | Fallback path when the consumer is existing S3 tooling (aws CLI, AWS SDKs, rclone, Terraform, boto3) and ado