Developer Setup

This page is for contributors to the Plugwerk codebase in plugwerk/plugwerk. If you are looking to develop a plugin for a Plugwerk-managed catalog, see Getting Started instead.

The canonical setup reference is AGENTS.md in the main repository — this page is a quick on-ramp.

Prerequisites

JDK 21 (any distribution — Temurin, Zulu, Corretto)
Node.js (current LTS) and npm
Docker with Docker Compose (used for the local PostgreSQL instance)
Git

Clone the repository

git clone https://github.com/plugwerk/plugwerk.git
cd plugwerk

Backend

The backend is a Spring Boot 4.x service in Kotlin, built with Gradle.

Start the development database:

docker compose up -d postgres

Run the server:

./gradlew :plugwerk-server:plugwerk-server-backend:bootRun

Run the full build (compiles all modules and runs every test):

./gradlew build

To skip tests during iteration:

./gradlew build -x test

Frontend

The frontend is React + TypeScript, served by Vite, embedded into the server JAR at build time.

cd plugwerk-server/plugwerk-server-frontend
npm install
npm run dev

The Vite dev server runs on port 5173 and proxies /api to http://localhost:8080, so run it alongside the backend.

Running tests

Backend tests run as part of ./gradlew build from the repository root.

Frontend tests must be run from plugwerk-server/plugwerk-server-frontend/:

npm run test:run        # single run (CI mode)
npm run test:coverage   # with V8 coverage report

Running npx vitest from the repository root picks up the wrong configuration and reports unrelated test files — always run tests from the frontend directory.