Create, configure, and run an Insolitum Universe module in under 5 minutes. Step-by-step guide from zero to working module.

Quick Start

Build your first Insolitum Universe module in 5 minutes.

Prerequisites

Before you begin, make sure you have:

Node.js >= 18.0
pnpm >= 8.0 (recommended) or npm
Access to a Supabase instance (shared with Universe Shell)
A running Universe Shell instance (for testing iframe integration)

Create a New Module

Scaffold with CLI

The fastest way to create a new module:

npx create-insolitum-module my-analytics

The CLI will ask for:

Module name — slug format (lowercase, hyphens)
Display name — human-readable name
Description — short description for the marketplace
Category — hr, iot, production, finance, analytics, ai, or other
Supabase URL — your shared Supabase project URL
Supabase anon key — public anonymous key

If you prefer manual setup, copy the template from templates/module-starter/ in the monorepo.

Install Dependencies

cd my-analytics
pnpm install

Configure Environment

Edit .env.local with your Supabase credentials:

.env.local

# Supabase (shared with Universe Shell)
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIs...
 
# Module identity
NEXT_PUBLIC_MODULE_ID=my-analytics
NEXT_PUBLIC_MODULE_VERSION=1.0.0

Start Development Server

pnpm dev

Your module is running at http://localhost:3010.

Test Health Endpoint

Verify your module is properly configured:

curl http://localhost:3010/api/health

Expected response:

{
  "status": "ok",
  "module": "my-analytics",
  "version": "1.0.0",
  "timestamp": "2026-02-13T12:00:00.000Z",
  "uptime_since": "2026-02-13T11:55:00.000Z",
  "checks": {
    "supabase": true
  }
}

The health endpoint at /api/health is mandatory. Universe Shell uses it to monitor module status, and the marketplace validation will check it during review.

Test in Universe Shell

Start Universe Shell on its default port
Log in as an admin
Go to Admin Panel → Modules
Add a new module with URL: http://localhost:3010
Your module loads in the Shell's iframe with automatic authentication

The Shell sends your module an auth session via postMessage. The ShellAuthProvider in your module handles this automatically — no configuration needed.

Project Structure

After scaffolding, your module has this structure:

my-analytics/
├── src/
│   ├── app/
│   │   ├── layout.tsx              # Root layout with ShellAuthProvider
│   │   ├── page.tsx                # Main dashboard page
│   │   ├── globals.css             # Tailwind styles
│   │   ├── settings/
│   │   │   └── page.tsx            # Settings page
│   │   └── api/
│   │       └── health/
│   │           └── route.ts        # Health endpoint (required)
│   ├── hooks/
│   │   ├── useNats.ts              # Real-time events hook
│   │   └── useModuleApi.ts         # Tenant-scoped DB queries
│   └── lib/
│       ├── shell-auth.tsx          # Auth provider (postMessage)
│       ├── shell-navigation.ts     # Shell navigation helpers
│       └── nats-events.ts          # NATS event types & subjects
├── package.json
├── next.config.ts                  # CSP headers for iframe
├── tailwind.config.ts              # Tailwind with dark theme
├── tsconfig.json
├── .env.example
└── .env.local                      # Your credentials (gitignored)

Adding a New Page

Create pages using Next.js App Router conventions:

src/app/reports/page.tsx

'use client';
 
import { useShellAuth } from '@/lib/shell-auth';
 
export default function ReportsPage() {
  const { user, organizationId, isAuthenticated } = useShellAuth();
 
  if (!isAuthenticated) {
    return <p className="p-6 text-gray-400">Loading...</p>;
  }
 
  return (
    <div className="p-6">
      <h1 className="text-2xl font-bold text-white">Reports</h1>
      <p className="text-gray-400 mt-2">
        Analytics for org: {organizationId}
      </p>
    </div>
  );
}

Access it at http://localhost:3010/reports.

Deploy to Vercel

Push your module to a Git repository.

Create a new project on Vercel and connect the repository.

Add environment variables in Vercel project settings:

NEXT_PUBLIC_SUPABASE_URL
NEXT_PUBLIC_SUPABASE_ANON_KEY
NEXT_PUBLIC_MODULE_ID
NEXT_PUBLIC_MODULE_VERSION

Deploy. Your module is now available at https://my-analytics.vercel.app.

What's Next?

Architecture — Understand how modules work in Universe
Authentication — Deep dive into Shell auth integration
Database — Supabase queries with multi-tenant isolation
Real-time Events — Subscribe to NATS events
Marketplace — Publish your module and earn revenue
Module Validator — Test your module before submission

Quick Start — Build Your First Module