Ontwikkelaarsgids

Hoe je een lokale ontwikkelomgeving opzet en code bijdraagt aan SnapOtter.

Vereisten

• Node.js 22.22+
• pnpm 9+ (corepack enable && corepack prepare pnpm@latest --activate)
• Docker (vereist voor lokale Postgres + Redis, containerbuilds en AI-functies)
• Git

Python 3.11+ is alleen nodig als je aan de AI/ML-sidecar werkt (achtergrond verwijderen, opschalen, OCR).

Installatie

git clone https://github.com/snapotter-hq/snapotter.git
cd snapotter
docker compose -f docker-compose.dev.yml up -d   # start Postgres + Redis
pnpm install
pnpm dev

Dit start twee dev-servers:

Service	URL	Opmerkingen
Frontend	http://localhost:1351	Vite-dev-server, proxyt /api
Backend	http://localhost:13490	Fastify-API (bereikbaar via proxy)

Open http://localhost:1351 in je browser. Meld je aan met admin / admin. Je wordt gevraagd het wachtwoord te wijzigen bij de eerste aanmelding.

Projectstructuur

apps/
  api/              Fastify backend
  web/              Vite + React frontend
  docs/             VitePress documentation (this site)
packages/
  shared/           Constants, types, i18n strings
  image-engine/     Sharp-based image operations
  media-engine/     FFmpeg spawn + progress parsing
  doc-engine/       qpdf, LibreOffice, ghostscript wrappers
  ai/               Python sidecar bridge for ML models
tests/
  unit/             Vitest unit tests
  integration/      Vitest integration tests (full API)
  e2e/              Playwright end-to-end specs
  fixtures/         Small test images

Commando's

pnpm dev                # start frontend + backend
pnpm build              # build all workspaces
pnpm typecheck          # TypeScript check across monorepo
pnpm lint               # Biome lint + format check
pnpm lint:fix           # auto-fix lint + format
pnpm test               # unit + integration tests
pnpm test:unit          # unit tests only
pnpm test:integration   # integration tests only
pnpm test:e2e           # Playwright e2e tests
pnpm test:coverage      # tests with coverage report

Codeconventies

• Dubbele aanhalingstekens, puntkomma's, inspringen met 2 spaties (afgedwongen door Biome)
• ES-modules in alle workspaces
• Conventional commits voor semantic-release
• Zod voor alle API-invoervalidatie
• Geen wijzigingen aan Biome-, TypeScript- of editor-configuratiebestanden. Fix de code, niet de linter.

Database

PostgreSQL 17 via Drizzle ORM (pg-core). Lokale ontwikkeling vereist dat Postgres en Redis draaien - start ze met:

docker compose -f docker-compose.dev.yml up -d

Dit geeft je Postgres op poort 5432 en Redis op poort 6379. Genereer en pas vervolgens migraties toe:

cd apps/api
npx drizzle-kit generate   # generate a migration from schema changes
npx drizzle-kit migrate    # apply pending migrations

Het schema is gedefinieerd in apps/api/src/db/schema.ts. Tabellen: users, sessions, settings, jobs, apiKeys, pipelines, teams, userFiles, roles, auditLog.

Een nieuwe tool toevoegen

Elke tool volgt hetzelfde patroon. Hier is een minimaal voorbeeld.

1. Backend-route

Maak apps/api/src/routes/tools/my-tool.ts:

import { z } from "zod";
import type { FastifyInstance } from "fastify";
import { createToolRoute } from "../tool-factory.js";

const settingsSchema = z.object({
  intensity: z.number().min(0).max(100).default(50),
});

export function registerMyTool(app: FastifyInstance) {
  createToolRoute(app, {
    toolId: "my-tool",
    settingsSchema,
    async process(inputBuffer, settings, filename) {
      // Use sharp or other libraries to process the image
      const sharp = (await import("sharp")).default;
      const result = await sharp(inputBuffer)
        // ... your processing logic
        .toBuffer();

      return {
        buffer: result,
        filename: filename.replace(/\.[^.]+$/, ".png"),
        contentType: "image/png",
      };
    },
  });
}

Registreer het vervolgens in apps/api/src/routes/tools/index.ts.

2. Frontend-instellingencomponent

Maak apps/web/src/components/tools/my-tool-settings.tsx:

import { useState } from "react";
import { useToolProcessor } from "@/hooks/use-tool-processor";
import { useFileStore } from "@/stores/file-store";

export function MyToolSettings() {
  const { files } = useFileStore();
  const { processFiles, processing, error, downloadUrl } =
    useToolProcessor("my-tool");

  const [intensity, setIntensity] = useState(50);

  const handleProcess = () => {
    processFiles(files, { intensity });
  };

  return (
    <div className="space-y-4">
      {/* your controls here */}
      <button
        type="button"
        onClick={handleProcess}
        disabled={files.length === 0 || processing}
        data-testid="my-tool-submit"
        className="w-full py-2.5 rounded-lg bg-primary text-primary-foreground font-medium disabled:opacity-50"
      >
        Process
      </button>
    </div>
  );
}

Registreer het vervolgens in het frontend-toolregister op apps/web/src/lib/tool-registry.tsx:

// Add the lazy import
const MyToolSettings = lazy(() =>
  import("@/components/tools/my-tool-settings").then((m) => ({
    default: m.MyToolSettings,
  })),
);

// Add to the toolRegistry Map
["my-tool", { displayMode: "before-after", Settings: MyToolSettings }],

Weergavemodi: "side-by-side", "before-after", "live-preview", "no-comparison", "interactive-crop", "interactive-eraser", "no-dropzone".

3. i18n-vermelding

Voeg toe aan packages/shared/src/i18n/en.ts:

"my-tool": {
  name: "My Tool",
  description: "Short description of what this tool does",
},

4. Tests

Voeg een data-testid-attribuut toe aan je actieknop (zoals hierboven getoond) zodat e2e-tests het betrouwbaar kunnen aanspreken.

5. Visuele baselines

De screenshottests staan nul gewijzigde pixels toe, en een nieuwe tool verandert wat ze renderen: het aantal tools op de startpagina en in de catalogus, een nieuwe kaart in het raster en een eigen pagina waarop tests/e2e/gui-visual-tools.spec.ts faalt met "snapshot doesn't exist" totdat die een baseline heeft. Werk de baselines bij in dezelfde PR als de tool, zodat de nachtelijke visuele vergelijking groen blijft.

CI genereert zowel de linux- (ubuntu-latest) als de darwin-baselines (macos-latest). Push je branch en start daarop de update:

gh workflow run update-visual-baselines.yml --ref <your-branch> -f update_snapshots=changed

Elke OS-stap uploadt een visual-baselines-linux-<run-id>-<attempt>- of visual-baselines-darwin-<run-id>-<attempt>-artefact en opent een concept-PR (chore/visual-baselines-linux-... en chore/visual-baselines-darwin-...) tegen main met de opnieuw gegenereerde PNG's. In de beschrijving van elke concept-PR staat een gh run download-opdracht; voer ze allebei uit vanuit de root van je checkout om de PNG's in je branch te zetten, commit ze en sluit de concept-PR's. Gebruik update_snapshots=all als changed een screenshot mist waarvan je verwachtte dat die zou veranderen. Starten vereist schrijfrechten op de repository, dus als je branch op een fork staat, zet dan in de PR dat er een baseline-update nodig is en een maintainer start die.

Op een Mac kun je de darwin-baselines voor snellere iteratie ook lokaal bijwerken:

pnpm playwright test --project=chromium-visual --project=mobile-chromium --project=tablet-chromium --update-snapshots=changed

Open in elk geval elke nieuwe of gewijzigde PNG voordat je hem commit: een baseline legt vast wat er gerenderd werd, kapot of niet.

Een release heeft hier niets van nodig. De appversie is gemaskeerd in elke screenshot die hem toont, dus een nieuwe versie verandert geen enkele baseline.

Docker-builds

Bouw de volledige productie-image lokaal:

docker build -f docker/Dockerfile -t snapotter:latest .

Gebruik BuildKit-cachemounts voor snellere rebuilds:

DOCKER_BUILDKIT=1 docker build -f docker/Dockerfile -t snapotter:latest .

Versiedomeinen vrijgeven

SnapOtter heeft opzettelijk drie versiedomeinen. Kopieer tijdens een release niet het ene domein naar het andere:

• De releaseversie van de applicatie omvat het rootmanifest, alle privéwerkruimtepakketten en APP_VERSION. Semantic-release levert deze waarde, en pnpm version:sync <version> werkt elke werkruimte bij voordat een applicatie wordt uitgebracht.
• OpenAPI info.version is het stabiele publieke API-groot contract. Alle gelokaliseerde specificaties blijven op <major>.0.0 voor compatibele applicatiereleases en veranderen alleen wanneer het API-contract overgaat naar een nieuwe hoofdversie.
• docker/feature-manifest.json behoudt imageVersion: 2.0.0 als het onveranderlijke historische opslagtijdperk met featurebundels. Deze v2-archiefpaden zijn geen applicatiepakketversies. Nauwkeurige OCR maakt gebruik van runtime-indeling v3 en registreert de herkomst van de applicatierelease afzonderlijk.

tests/unit/infra/release-version-policy.test.ts handhaaft deze grenzen. Een nieuw versiedomein of een nieuwe migratie moet dat contract en het relevante artefactmigratieontwerp samen bijwerken. De onafhankelijke API- en legacy-bundelwaarden bevinden zich in config/release-version-policy.json; Synchronisatie van de applicatieversie mag dat beleidsbestand nooit impliciet herschrijven.

Omgevingsvariabelen

Zie de Configuratiegids voor de volledige lijst. De belangrijkste voor ontwikkeling:

Variabele	Standaard	Beschrijving
AUTH_ENABLED	true	Authenticatie in-/uitschakelen
DEFAULT_USERNAME	admin	Standaard beheerdersgebruikersnaam
DEFAULT_PASSWORD	admin	Standaard beheerderswachtwoord
SKIP_MUST_CHANGE_PASSWORD	false	Geforceerde wachtwoordwijziging overslaan (alleen CI/dev)
RATE_LIMIT_PER_MIN	1000	API-ratelimiet per minuut (0 = uitgeschakeld)
MAX_UPLOAD_SIZE_MB	100	Maximale uploadgrootte in MB (0 = onbeperkt)