InsForge SDK Skill

This skill covers client-side SDK integration using @insforge/sdk. For backend infrastructure operations (creating tables, inspecting schema, deploying functions, secrets, managing storage buckets, website deployments, cron job and schedules, logs, etc.), use the insforge-cli skill.

Quick Setup

npm install @insforge/sdk@latest

import { createClient } from '@insforge/sdk'

const insforge = createClient({
  baseUrl: 'https://your-project.region.insforge.app',
  anonKey: 'your-anon-key'
})

Module Reference

What Each Module Covers

Guides

Real-time Configuration

For real-time channels and database triggers, use insforge db query with SQL to create triggers that publish to channels. The real-time SDK is for frontend event handling and messaging, not backend configuration.

Create Database Triggers

Automatically publish events when database records change.

-- Create trigger function
CREATE OR REPLACE FUNCTION notify_order_changes()
RETURNS TRIGGER AS $$
BEGIN
  PERFORM realtime.publish(
    'order:' || NEW.id::text,    -- channel
    TG_OP || '_order',           -- event: INSERT_order, UPDATE_order
    jsonb_build_object(
      'id', NEW.id,
      'status', NEW.status,
      'total', NEW.total
    )
  );
  RETURN NEW;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;

-- Attach to table
CREATE TRIGGER order_realtime
  AFTER INSERT OR UPDATE ON orders
  FOR EACH ROW
  EXECUTE FUNCTION notify_order_changes();

Conditional Trigger (Status Changes Only)

CREATE OR REPLACE FUNCTION notify_order_status()
RETURNS TRIGGER AS $$
BEGIN
  PERFORM realtime.publish(
    'order:' || NEW.id::text,
    'status_changed',
    jsonb_build_object('id', NEW.id, 'status', NEW.status)
  );
  RETURN NEW;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;

CREATE TRIGGER order_status_trigger
  AFTER UPDATE ON orders
  FOR EACH ROW
  WHEN (OLD.status IS DISTINCT FROM NEW.status)
  EXECUTE FUNCTION notify_order_status();

Access Control (RLS)

RLS is disabled by default. To restrict channel access:

• Enable RLS

ALTER TABLE realtime.channels ENABLE ROW LEVEL SECURITY;
ALTER TABLE realtime.messages ENABLE ROW LEVEL SECURITY;

• Restrict Subscribe (SELECT on channels)

CREATE POLICY "users_subscribe_own_orders"
ON realtime.channels FOR SELECT
TO authenticated
USING (
  pattern = 'order:%'
  AND EXISTS (
    SELECT 1 FROM orders
    WHERE id = NULLIF(split_part(realtime.channel_name(), ':', 2), '')::uuid
      AND user_id = auth.uid()
  )
);

• Restrict Publish (INSERT on messages)

CREATE POLICY "members_publish_chat"
ON realtime.messages FOR INSERT
TO authenticated
WITH CHECK (
  channel_name LIKE 'chat:%'
  AND EXISTS (
    SELECT 1 FROM chat_members
    WHERE room_id = NULLIF(split_part(channel_name, ':', 2), '')::uuid
      AND user_id = auth.uid()
  )
);

• Quick Reference

Best Practices

1. Create channel patterns first before subscribing from frontend

   • Insert channel patterns into realtime.channels table
   • Ensure enabled is set to true

2. Use specific channel patterns

   • Use wildcard % patterns for dynamic channels (e.g., order:% for order:123)
   • Use exact patterns for global channels (e.g., notifications)

Common Mistakes

Recommended Workflow

1. Create channel patterns   → INSERT INTO realtime.channels
2. Ensure enabled = true     → Set enabled to true
3. Create triggers if needed → Auto-publish on database changes
4. Proceed with SDK subscribe → Use channel name matching pattern

Backend Configuration (Not Yet in CLI)

These modules still require HTTP API calls because the CLI does not yet support them:

SDK Quick Reference

All SDK methods return { data, error }.

Important Notes

• Database inserts require array format: insert([{...}]) not insert({...})
• Next.js / SSR auth: Use createClient({ isServerMode: true }), keep tokens in httpOnly cookies, and perform auth flows on the server. See auth/sdk-integration.md
• Storage: Save both url AND key to database for download/delete operations
• Functions invoke URL: /functions/{slug} (without /api prefix)
• Use Tailwind CSS v3.4 (do not upgrade to v4)
• Always local build before deploy: Prevents wasted build resources and faster debugging
• Deprecated packages: @insforge/react, @insforge/nextjs, and @insforge/react-router are deprecated. Do NOT install or use them. Use @insforge/sdk directly for all features including authentication.
• Deployment: Include a vercel.json in the project root for SPA routing (React, React Router apps). The download-template tool includes this automatically.