Panduan developer

Cara menyiapkan lingkungan pengembangan lokal dan berkontribusi kode ke SnapOtter.

Prasyarat

• Node.js 22.22+
• pnpm 9+ (corepack enable && corepack prepare pnpm@latest --activate)
• Docker (diperlukan untuk Postgres + Redis lokal, build kontainer, dan fitur AI)
• Git

Python 3.11+ hanya diperlukan jika Anda mengerjakan sidecar AI/ML (penghapusan latar belakang, upscaling, OCR).

Penyiapan

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

Ini memulai dua server dev:

Layanan	URL	Catatan
Frontend	http://localhost:1351	Server dev Vite, mem-proxy /api
Backend	http://localhost:13490	Fastify API (diakses melalui proxy)

Buka http://localhost:1351 di browser Anda. Login dengan admin / admin. Anda akan diminta untuk mengubah kata sandi saat login pertama.

Struktur proyek

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

Perintah

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

Konvensi kode

• Tanda kutip ganda, titik koma, indentasi 2 spasi (ditegakkan oleh Biome)
• ES module di semua workspace
• Conventional commits untuk semantic-release
• Zod untuk semua validasi input API
• Tidak ada modifikasi pada file konfigurasi Biome, TypeScript, atau editor. Perbaiki kodenya, bukan linter-nya.

Database

PostgreSQL 17 melalui Drizzle ORM (pg-core). Dev lokal memerlukan Postgres dan Redis yang berjalan - mulai keduanya dengan:

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

Ini memberi Anda Postgres pada port 5432 dan Redis pada port 6379. Kemudian buat dan terapkan migrasi:

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

Skema didefinisikan di apps/api/src/db/schema.ts. Tabel: users, sessions, settings, jobs, apiKeys, pipelines, teams, userFiles, roles, auditLog.

Menambahkan tool baru

Setiap tool mengikuti pola yang sama. Berikut contoh minimal.

1. Route backend

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

Kemudian daftarkan di apps/api/src/routes/tools/index.ts.

2. Komponen pengaturan frontend

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

Kemudian daftarkan di registry tool frontend di 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 }],

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

3. Entri i18n

Tambahkan ke packages/shared/src/i18n/en.ts:

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

4. Tes

Tambahkan atribut data-testid ke tombol aksi Anda (seperti ditunjukkan di atas) agar tes e2e dapat menargetkannya secara andal.

Build Docker

Bangun image produksi lengkap secara lokal:

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

Gunakan cache mount BuildKit untuk build ulang yang lebih cepat:

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

Rilis domain versi

SnapOtter sengaja memiliki tiga versi domain. Jangan menyalin satu domain ke domain lain selama rilis:

• Versi rilis aplikasi mencakup manifes root, semua paket ruang kerja pribadi, dan APP_VERSION. Semantic-release menyediakan nilai ini, dan pnpm version:sync <version> memperbarui setiap ruang kerja sebelum aplikasi dirilis.
• OpenAPI info.version adalah kontrak utama publik API yang stabil. Semua spesifikasi yang dilokalkan tetap pada <major>.0.0 untuk rilis aplikasi yang kompatibel dan hanya berubah ketika kontrak API berpindah ke versi utama baru.
• docker/feature-manifest.json menjadikan imageVersion: 2.0.0 sebagai masa penyimpanan paket fitur lama yang tidak dapat diubah. Jalur arsip v2 tersebut bukan versi paket aplikasi. OCR yang akurat menggunakan format runtime v3 dan mencatat asal rilis aplikasinya secara terpisah.

tests/unit/infra/release-version-policy.test.ts menerapkan batasan ini. Domain atau migrasi versi baru harus memperbarui kontrak tersebut dan desain migrasi artefak yang relevan secara bersamaan. Nilai API independen dan paket warisan ada di config/release-version-policy.json; sinkronisasi versi aplikasi tidak boleh menulis ulang file kebijakan tersebut secara implisit.

Variabel lingkungan

Lihat Panduan Konfigurasi untuk daftar lengkap. Yang penting untuk pengembangan:

Variabel	Default	Deskripsi
AUTH_ENABLED	true	Aktifkan/nonaktifkan autentikasi
DEFAULT_USERNAME	admin	Nama pengguna admin default
DEFAULT_PASSWORD	admin	Kata sandi admin default
SKIP_MUST_CHANGE_PASSWORD	false	Lewati perubahan kata sandi paksa (hanya CI/dev)
RATE_LIMIT_PER_MIN	1000	Batas laju API per menit (0 = dinonaktifkan)
MAX_UPLOAD_SIZE_MB	100	Ukuran unggah maksimum dalam MB (0 = tak terbatas)