TypeScript SDK

Official TypeScript/JavaScript SDK for InsForge with complete type safety and modern tooling

The InsForge TypeScript SDK provides a fully type-safe client for building web applications with InsForge services. It works seamlessly with JavaScript, TypeScript, React, Next.js, and other modern frameworks.

Installation

Install the SDK via npm:

npm install @insforge/sdk@latest

Quick Start

1. Create Client Instance

Create an InsForge client with your backend URL and anon key:

import { createClient } from '@insforge/sdk';

const insforge = createClient({
  baseUrl: 'https://your-app.region.insforge.app',
  anonKey: 'your-anon-key-here'  // Optional: for public/unauthenticated requests
});

Get your baseUrl and anonKey from your InsForge dashboard or by calling the get-backend-metadata MCP tool.

2. Use SDK Features

The SDK provides access to all InsForge services:

// Database operations
const { data: posts } = await insforge.database
  .from('posts')
  .select('*')
  .order('created_at', { ascending: false })
  .limit(10);

// Authentication
const { data, error } = await insforge.auth.signInWithPassword({
  email: '[e-mail]',
  password: 'secure_password'
});

// Storage
const { data: upload } = await insforge.storage
  .from('images')
  .upload('path/to/file.jpg', fileObject);

// AI operations
const completion = await insforge.ai.chat.completions.create({
  model: 'anthropic/claude-3.5-haiku',
  messages: [{ role: 'user', content: 'Hello!' }]
});

// Realtime subscriptions
await insforge.realtime.connect();
await insforge.realtime.subscribe('chat:room-1');
insforge.realtime.on('new_message', (msg) => console.log(msg));

Core Features

Database

Type-safe CRUD operations with PostgREST

Authentication

Email/password and OAuth authentication

Storage

File upload, download, and management

Functions

Invoke serverless edge functions

AI

Chat completions and image generation

Realtime

WebSocket pub/sub messaging

Framework-Specific Packages

For React and Next.js applications, InsForge provides additional packages with pre-built UI components:

@insforge/react

Pre-built authentication components for React + Vite (single-page apps):

npm install @insforge/react@latest

import { InsforgeProvider, SignInButton, useUser } from '@insforge/react';

// Wrap your app
<InsforgeProvider client={insforge}>
  <App />
</InsforgeProvider>

// Use authentication hooks
function Profile() {
  const { user } = useUser();
  return <div>Welcome {user?.email}</div>;
}

Learn more about React components →

@insforge/nextjs

Pre-built authentication components for Next.js with SSR support:

npm install @insforge/nextjs@latest

import { InsforgeProvider, SignInButton } from '@insforge/nextjs';

// Server-side rendering support
export default function RootLayout({ children }) {
  return (
    <InsforgeProvider>
      {children}
    </InsforgeProvider>
  );
}

Learn more about Next.js components →

Response Structure

All SDK methods return a consistent { data, error } structure:

const { data, error } = await insforge.database
  .from('posts')
  .select('*');

if (error) {
  console.error('Error:', error.message);
  return;
}

console.log('Data:', data);

Error Handling

Errors include detailed information for debugging:

if (error) {
  console.error(error.statusCode);   // HTTP status code
  console.error(error.error);        // Error code (e.g., 'INVALID_CREDENTIALS')
  console.error(error.message);      // Human-readable message
  console.error(error.nextActions);  // Suggested next steps
}

Type Safety

The SDK is fully typed for TypeScript projects:

interface Post {
  id: string;
  title: string;
  content: string;
  created_at: string;
}

const { data } = await insforge.database
  .from('posts')
  .select<Post>('*');

// data is typed as Post[]
data?.forEach(post => {
  console.log(post.title); // TypeScript knows this exists
});

Environment Variables

Store your InsForge credentials securely:

Vite

.env

VITE_INSFORGE_BASE_URL=https://your-app.region.insforge.app
VITE_INSFORGE_ANON_KEY=your-anon-key-here

src/lib/insforge.ts

import { createClient } from '@insforge/sdk';

export const insforge = createClient({
  baseUrl: import.meta.env.VITE_INSFORGE_BASE_URL,
  anonKey: import.meta.env.VITE_INSFORGE_ANON_KEY
});

Next.js

.env.local

NEXT_PUBLIC_INSFORGE_BASE_URL=https://your-app.region.insforge.app
NEXT_PUBLIC_INSFORGE_ANON_KEY=your-anon-key-here

lib/insforge.ts

import { createClient } from '@insforge/sdk';

export const insforge = createClient({
  baseUrl: process.env.NEXT_PUBLIC_INSFORGE_BASE_URL!,
  anonKey: process.env.NEXT_PUBLIC_INSFORGE_ANON_KEY!
});

Node.js

.env

INSFORGE_BASE_URL=https://your-app.region.insforge.app
INSFORGE_ANON_KEY=your-anon-key-here

import { createClient } from '@insforge/sdk';
import * as dotenv from 'dotenv';

dotenv.config();

export const insforge = createClient({
  baseUrl: process.env.INSFORGE_BASE_URL!,
  anonKey: process.env.INSFORGE_ANON_KEY!
});

Next Steps

Database Operations

Learn about CRUD operations, filters, and queries

Authentication

Implement user sign-up, sign-in, and OAuth

UI Components

Use pre-built auth components for React/Next.js

MCP Tools

Infrastructure management via MCP