Insolitum Developers

Schnellstart β€” Erstelle dein erstes Modul

Erstelle, konfiguriere und starte ein Insolitum-Universe-Modul in unter 5 Minuten. Schritt-fuer-Schritt-Anleitung vom Anfang bis zum fertigen Modul.

Schnellstart

Erstelle dein erstes Insolitum-Universe-Modul in 5 Minuten.

Voraussetzungen

Bevor du beginnst, stelle sicher, dass du Folgendes hast:

  • Node.js >= 18.0
  • pnpm >= 8.0 (empfohlen) oder npm
  • Zugang zu einer Supabase-Instanz (gemeinsam mit Universe Shell genutzt)
  • Eine laufende Universe Shell-Instanz (zum Testen der iframe-Integration)

Neues Modul erstellen

Projekt mit CLI generieren

Der schnellste Weg, ein neues Modul zu erstellen:

npx create-insolitum-module my-analytics

Das CLI fragt nach:

  • Modulname β€” Slug-Format (Kleinbuchstaben, Bindestriche)
  • Anzeigename β€” lesbarer Name fuer Benutzer
  • Beschreibung β€” kurze Beschreibung fuer den Marketplace
  • Kategorie β€” hr, iot, production, finance, analytics, ai oder other
  • Supabase URL β€” URL deines gemeinsamen Supabase-Projekts
  • Supabase anon key β€” oeffentlicher anonymer Schluessel

Wenn du die manuelle Einrichtung bevorzugst, kopiere die Vorlage aus templates/module-starter/ im Monorepo.

Abhaengigkeiten installieren

cd my-analytics
pnpm install

Umgebung konfigurieren

Bearbeite .env.local mit deinen Supabase-Zugangsdaten:

.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

Entwicklungsserver starten

pnpm dev

Dein Modul laeuft unter http://localhost:3010.

Health-Endpoint testen

Ueberpruefen, ob dein Modul korrekt konfiguriert ist:

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

Erwartete Antwort:

{
  "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
  }
}

Der Health-Endpoint unter /api/health ist obligatorisch. Universe Shell verwendet ihn zur Ueberwachung des Modulstatus, und die Marketplace-Validierung prueft ihn waehrend des Review-Prozesses.

In Universe Shell testen

  1. Starte Universe Shell auf dem Standardport
  2. Melde dich als Administrator an
  3. Navigiere zu Admin-Panel β†’ Module
  4. Fuege ein neues Modul mit der URL hinzu: http://localhost:3010
  5. Dein Modul wird im iframe der Shell mit automatischer Authentifizierung geladen

Die Shell sendet deinem Modul eine Authentifizierungssitzung ueber postMessage. Der ShellAuthProvider in deinem Modul verarbeitet dies automatisch β€” keine weitere Konfiguration noetig.

Projektstruktur

Nach der Generierung hat dein Modul folgende Struktur:

my-analytics/
β”œβ”€β”€ src/
β”‚   β”œβ”€β”€ app/
β”‚   β”‚   β”œβ”€β”€ layout.tsx              # Root-Layout mit ShellAuthProvider
β”‚   β”‚   β”œβ”€β”€ page.tsx                # Haupt-Dashboard-Seite
β”‚   β”‚   β”œβ”€β”€ globals.css             # Tailwind-Styles
β”‚   β”‚   β”œβ”€β”€ settings/
β”‚   β”‚   β”‚   └── page.tsx            # Einstellungsseite
β”‚   β”‚   └── api/
β”‚   β”‚       └── health/
β”‚   β”‚           └── route.ts        # Health-Endpoint (erforderlich)
β”‚   β”œβ”€β”€ hooks/
β”‚   β”‚   β”œβ”€β”€ useNats.ts              # Echtzeit-Ereignis-Hook
β”‚   β”‚   └── useModuleApi.ts         # Mandantenbezogene DB-Abfragen
β”‚   └── lib/
β”‚       β”œβ”€β”€ shell-auth.tsx          # Auth-Provider (postMessage)
β”‚       β”œβ”€β”€ shell-navigation.ts     # Shell-Navigations-Hilfsfunktionen
β”‚       └── nats-events.ts          # NATS-Ereignistypen und Subjects
β”œβ”€β”€ package.json
β”œβ”€β”€ next.config.ts                  # CSP-Header fuer iframe
β”œβ”€β”€ tailwind.config.ts              # Tailwind mit dunklem Theme
β”œβ”€β”€ tsconfig.json
β”œβ”€β”€ .env.example
└── .env.local                      # Deine Zugangsdaten (in gitignore)

Neue Seite hinzufuegen

Erstelle Seiten gemaess den Konventionen des Next.js App Routers:

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">Wird geladen...</p>;
  }
 
  return (
    <div className="p-6">
      <h1 className="text-2xl font-bold text-white">Berichte</h1>
      <p className="text-gray-400 mt-2">
        Analysen fuer Organisation: {organizationId}
      </p>
    </div>
  );
}

Erreichbar unter http://localhost:3010/reports.

Bereitstellung auf Vercel

Pushe dein Modul in ein Git-Repository.

Erstelle ein neues Projekt auf Vercel und verbinde das Repository.

Fuege Umgebungsvariablen in den Vercel-Projekteinstellungen hinzu:

  • NEXT_PUBLIC_SUPABASE_URL
  • NEXT_PUBLIC_SUPABASE_ANON_KEY
  • NEXT_PUBLIC_MODULE_ID
  • NEXT_PUBLIC_MODULE_VERSION

Bereitstellen. Dein Modul ist jetzt verfuegbar unter https://my-analytics.vercel.app.

Wie geht es weiter?

On this page