Guida per sviluppatori

Come configurare un ambiente di sviluppo locale e contribuire con codice a SnapOtter.

Prerequisiti

• Node.js 22.22+
• pnpm 9+ (corepack enable && corepack prepare pnpm@latest --activate)
• Docker (richiesto per Postgres + Redis locali, build dei container e funzionalità AI)
• Git

Python 3.11+ è necessario solo se stai lavorando sul sidecar AI/ML (rimozione dello sfondo, upscaling, OCR).

Configurazione

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

Questo avvia due dev server:

Servizio	URL	Note
Frontend	http://localhost:1351	Dev server Vite, fa da proxy a /api
Backend	http://localhost:13490	API Fastify (accessibile via proxy)

Apri http://localhost:1351 nel tuo browser. Accedi con admin / admin. Ti verrà chiesto di cambiare la password al primo login.

Struttura del progetto

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

Comandi

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

Convenzioni di codice

• Virgolette doppie, punto e virgola, indentazione di 2 spazi (imposte da Biome)
• Moduli ES in tutti i workspace
• Conventional commit per semantic-release
• Zod per tutta la validazione degli input API
• Nessuna modifica ai file di configurazione di Biome, TypeScript o dell'editor. Correggi il codice, non il linter.

Database

PostgreSQL 17 via Drizzle ORM (pg-core). Lo sviluppo locale richiede Postgres e Redis in esecuzione: avviali con:

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

Questo ti fornisce Postgres sulla porta 5432 e Redis sulla porta 6379. Poi genera e applica le migrazioni:

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

Lo schema è definito in apps/api/src/db/schema.ts. Tabelle: users, sessions, settings, jobs, apiKeys, pipelines, teams, userFiles, roles, auditLog.

Aggiungere un nuovo strumento

Ogni strumento segue lo stesso pattern. Ecco un esempio minimo.

1. Route del backend

Crea 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",
      };
    },
  });
}

Poi registralo in apps/api/src/routes/tools/index.ts.

2. Componente delle impostazioni del frontend

Crea 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>
  );
}

Poi registralo nel registro degli strumenti del frontend in 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 }],

Modalità di visualizzazione: "side-by-side", "before-after", "live-preview", "no-comparison", "interactive-crop", "interactive-eraser", "no-dropzone".

3. Voce i18n

Aggiungi a packages/shared/src/i18n/en.ts:

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

4. Test

Aggiungi un attributo data-testid al tuo pulsante di azione (come mostrato sopra) così i test e2e possono individuarlo in modo affidabile.

5. Baseline visive

I test con screenshot non ammettono alcun pixel modificato, e un nuovo strumento cambia ciò che mostrano: i conteggi degli strumenti nella home e nel catalogo, una nuova scheda nella griglia e una pagina tutta sua su cui tests/e2e/gui-visual-tools.spec.ts fallisce con "snapshot doesn't exist" finché non ha una baseline. Aggiorna le baseline nella stessa PR dello strumento, così il confronto visivo notturno resta verde.

La CI genera sia le baseline linux (ubuntu-latest) sia quelle darwin (macos-latest). Fai push del tuo branch, poi avvia l'aggiornamento su di esso:

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

Ogni job per sistema operativo carica un artefatto visual-baselines-linux-<run-id>-<attempt> o visual-baselines-darwin-<run-id>-<attempt> e apre una PR in bozza (chore/visual-baselines-linux-... e chore/visual-baselines-darwin-...) verso main con i PNG rigenerati. La descrizione di ciascuna PR in bozza contiene un comando gh run download; eseguili entrambi dalla radice del tuo checkout per portare i PNG nel tuo branch, fai commit e chiudi le PR in bozza. Usa invece update_snapshots=all se changed salta uno screenshot che ti aspettavi cambiasse. L'avvio richiede accesso in scrittura al repository, quindi se il tuo branch è su un fork, scrivi nella PR che serve un aggiornamento delle baseline e un maintainer lo avvierà.

Su un Mac puoi anche aggiornare localmente le baseline darwin per iterare più rapidamente:

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

In ogni caso, apri ogni PNG nuovo o modificato prima di fare commit: una baseline registra ciò che è stato renderizzato, rotto o no.

Una release non richiede nulla di tutto questo. La versione dell'app è mascherata in ogni screenshot che la mostra, quindi cambiarla non modifica nessuna baseline.

Build Docker

Compila l'immagine di produzione completa localmente:

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

Usa le cache mount di BuildKit per rebuild più veloci:

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

Rilascia i domini della versione

SnapOtter ha intenzionalmente tre domini di versione. Non copiare un dominio in un altro durante un rilascio:

• La versione di rilascio dell'applicazione copre il manifest root, tutti i pacchetti dell'area di lavoro privata e APP_VERSION. Semantic-release fornisce questo valore e pnpm version:sync <version> aggiorna ogni area di lavoro prima del rilascio dell'applicazione.
• OpenAPI info.version è il contratto pubblico stabile API-major. Tutte le specifiche localizzate rimangono su <major>.0.0 per i rilasci di applicazioni compatibili e cambiano solo quando il contratto API passa a una nuova versione principale.
• docker/feature-manifest.json mantiene imageVersion: 2.0.0 come epoca di archiviazione del pacchetto di funzionalità legacy immutabile. Tali percorsi di archivio v2 non sono versioni del pacchetto dell'applicazione. L'OCR accurato utilizza il formato runtime v3 e registra separatamente la provenienza del rilascio dell'applicazione.

tests/unit/infra/release-version-policy.test.ts rafforza questi limiti. Un nuovo dominio di versione o una migrazione deve aggiornare insieme il contratto e la progettazione di migrazione dell'artefatto pertinente. I valori API indipendenti e quelli del bundle legacy risiedono in config/release-version-policy.json; la sincronizzazione della versione dell'applicazione non deve mai riscrivere implicitamente il file della politica.

Variabili d'ambiente

Vedi la Guida alla configurazione per l'elenco completo. Quelle principali per lo sviluppo:

Variabile	Predefinito	Descrizione
AUTH_ENABLED	true	Abilita/disabilita l'autenticazione
DEFAULT_USERNAME	admin	Nome utente amministratore predefinito
DEFAULT_PASSWORD	admin	Password amministratore predefinita
SKIP_MUST_CHANGE_PASSWORD	false	Salta il cambio forzato della password (solo CI/dev)
RATE_LIMIT_PER_MIN	1000	Limite di rate delle API al minuto (0 = disabilitato)
MAX_UPLOAD_SIZE_MB	100	Dimensione massima di caricamento in MB (0 = illimitata)