Insolitum Developers

Szybki start β€” Zbuduj swoj pierwszy modul

Utworz, skonfiguruj i uruchom modul Insolitum Universe w mniej niz 5 minut. Przewodnik krok po kroku od zera do dzialajacego modulu.

Szybki start

Zbuduj swoj pierwszy modul Insolitum Universe w 5 minut.

Wymagania wstepne

Zanim zaczniesz, upewnij sie, ze masz:

  • Node.js >= 18.0
  • pnpm >= 8.0 (zalecany) lub npm
  • Dostep do instancji Supabase (wspoldzielonej z Universe Shell)
  • Dzialajaca instancja Universe Shell (do testowania integracji iframe)

Utworz nowy modul

Wygeneruj szablon za pomoca CLI

Najszybszy sposob na utworzenie nowego modulu:

npx create-insolitum-module my-analytics

CLI zapyta o:

  • Nazwa modulu β€” format slug (male litery, laczniki)
  • Nazwa wyswietlana β€” czytelna nazwa dla uzytkownika
  • Opis β€” krotki opis do marketplace
  • Kategoria β€” hr, iot, production, finance, analytics, ai lub other
  • Supabase URL β€” adres URL wspoldzielonego projektu Supabase
  • Supabase anon key β€” publiczny klucz anonimowy

Jesli wolisz reczna konfiguracje, skopiuj szablon z templates/module-starter/ w monorepo.

Zainstaluj zaleznosci

cd my-analytics
pnpm install

Skonfiguruj srodowisko

Edytuj .env.local z danymi dostepu do Supabase:

.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

Uruchom serwer deweloperski

pnpm dev

Twoj modul dziala pod adresem http://localhost:3010.

Przetestuj endpoint health

Sprawdz, czy modul jest poprawnie skonfigurowany:

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

Oczekiwana odpowiedz:

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

Endpoint health pod sciezka /api/health jest obowiazkowy. Universe Shell uzywa go do monitorowania stanu modulu, a walidacja marketplace sprawdzi go podczas procesu recenzji.

Przetestuj w Universe Shell

  1. Uruchom Universe Shell na domyslnym porcie
  2. Zaloguj sie jako administrator
  3. Przejdz do Panel administracyjny β†’ Moduly
  4. Dodaj nowy modul z adresem URL: http://localhost:3010
  5. Modul zaladuje sie w ramce iframe Shell z automatycznym uwierzytelnianiem

Shell wysyla do modulu sesje uwierzytelniania za pomoca postMessage. Komponent ShellAuthProvider w module obsluguje to automatycznie β€” nie wymaga dodatkowej konfiguracji.

Struktura projektu

Po wygenerowaniu szablonu modul ma nastepujaca strukture:

my-analytics/
β”œβ”€β”€ src/
β”‚   β”œβ”€β”€ app/
β”‚   β”‚   β”œβ”€β”€ layout.tsx              # Glowny layout z ShellAuthProvider
β”‚   β”‚   β”œβ”€β”€ page.tsx                # Strona glowna dashboardu
β”‚   β”‚   β”œβ”€β”€ globals.css             # Style Tailwind
β”‚   β”‚   β”œβ”€β”€ settings/
β”‚   β”‚   β”‚   └── page.tsx            # Strona ustawien
β”‚   β”‚   └── api/
β”‚   β”‚       └── health/
β”‚   β”‚           └── route.ts        # Endpoint health (wymagany)
β”‚   β”œβ”€β”€ hooks/
β”‚   β”‚   β”œβ”€β”€ useNats.ts              # Hook zdarzen w czasie rzeczywistym
β”‚   β”‚   └── useModuleApi.ts         # Zapytania DB z zakresem tenanta
β”‚   └── lib/
β”‚       β”œβ”€β”€ shell-auth.tsx          # Provider uwierzytelniania (postMessage)
β”‚       β”œβ”€β”€ shell-navigation.ts     # Pomocnicze funkcje nawigacji Shell
β”‚       └── nats-events.ts          # Typy zdarzen i tematy NATS
β”œβ”€β”€ package.json
β”œβ”€β”€ next.config.ts                  # Naglowki CSP dla iframe
β”œβ”€β”€ tailwind.config.ts              # Tailwind z ciemnym motywem
β”œβ”€β”€ tsconfig.json
β”œβ”€β”€ .env.example
└── .env.local                      # Twoje dane dostepowe (w gitignore)

Dodawanie nowej strony

Tworzenie stron zgodnie z konwencja Next.js App Router:

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">Ladowanie...</p>;
  }
 
  return (
    <div className="p-6">
      <h1 className="text-2xl font-bold text-white">Raporty</h1>
      <p className="text-gray-400 mt-2">
        Analityka dla organizacji: {organizationId}
      </p>
    </div>
  );
}

Dostepna pod adresem http://localhost:3010/reports.

Wdrozenie na Vercel

Wypchnij modul do repozytorium Git.

Utworz nowy projekt na Vercel i polacz repozytorium.

Dodaj zmienne srodowiskowe w ustawieniach projektu Vercel:

  • NEXT_PUBLIC_SUPABASE_URL
  • NEXT_PUBLIC_SUPABASE_ANON_KEY
  • NEXT_PUBLIC_MODULE_ID
  • NEXT_PUBLIC_MODULE_VERSION

Wdroz. Twoj modul jest teraz dostepny pod adresem https://my-analytics.vercel.app.

Co dalej?

On this page