How to Set Up the Stirling-PDF Local Development Environment with Gradle and npm

To set up the Stirling-PDF local development environment with Gradle and npm, clone the repository, execute ./gradlew bootRun to launch the Spring Boot backend on localhost:8080, then run npm ci and npm run dev inside the frontend directory to start the Vite React development server on localhost:5173.

Stirling-PDF combines a Spring Boot Java backend with a Vite/React JavaScript frontend. Setting up the local development environment requires configuring both the Gradle wrapper for backend compilation and npm for frontend dependency management, enabling you to modify and test the full application stack locally.

Prerequisites

Before starting, ensure your system meets the following requirements:

• Java JDK 17+ – Required to compile the Spring Boot backend.
• Node.js ≥ 20 and npm – Required for frontend tooling and package management.
• Git – To clone the repository.
• Docker (optional) – Needed for full-stack integration testing with external binaries like LibreOffice and qpdf.
• Calibre CLI (optional) – Required only if testing e-book to PDF conversion features.

The project includes a Gradle wrapper, so you do not need to install Gradle globally. The wrapper automatically downloads version 9.3.1 as specified in gradle/wrapper/gradle-wrapper.properties.

Clone the Repository

Start by cloning the official repository and entering the project directory:

git clone https://github.com/Stirling-Tools/Stirling-PDF.git
cd Stirling-PDF

Backend Setup with Gradle

The backend build logic is defined in build.gradle and managed through the Gradle wrapper script (gradlew).

Build the Project

Compile the Java source and package the application:

./gradlew clean build

This command downloads the exact Gradle version (9.3.1) defined in gradle/wrapper/gradle-wrapper.properties, installs dependencies, and produces the executable JAR.

Run the Backend Locally

Start the Spring Boot application in development mode:

./gradlew bootRun

The backend service starts on http://localhost:8080. By default, this runs with additional security features disabled to streamline development.

Enable Security Features

To test authentication, audit logs, and other security features locally, set the environment variable before launching:

export DISABLE_ADDITIONAL_FEATURES=false
./gradlew bootRun

This configuration is documented in the devGuide/DeveloperGuide.md under the environment variables section.

Frontend Setup with npm

The frontend source code resides in the frontend directory and uses Vite as the build tool.

Install Dependencies

Navigate to the frontend directory and install exact dependency versions:

cd frontend
npm ci

The npm ci command reads frontend/package.json and package-lock.json to ensure reproducible builds across development machines.

Start the Development Server

Launch the Vite development server:

npm run dev

The server starts on http://localhost:5173 and automatically proxies API requests to the backend at localhost:8080 via the proxy configuration defined in package.json.

Available npm Scripts

The frontend/package.json defines several useful scripts for development:

• npm run dev – Starts the Vite development server with hot module replacement.
• npm run build – Creates an optimized production bundle for deployment.
• npm run lint – Runs ESLint and circular dependency checks.
• npm run test – Executes the Vitest unit test suite.
• npm run e2e – Runs Playwright end-to-end tests against the running application.

Full-Stack Development Workflow

To work on both backend and frontend code simultaneously:

1. Start the backend in a terminal window:

   ./gradlew bootRun

2. Start the frontend in a second terminal:

   cd frontend
   npm run dev

3. Open http://localhost:5173 in your browser. The Vite server handles UI rendering and proxies all /api/* requests to the Gradle backend, providing a seamless development experience.

Docker-Based Testing (Optional)

To verify functionality that depends on external binaries (LibreOffice, qpdf, OCR tools), build and run the full Docker image:

export DISABLE_ADDITIONAL_FEATURES=true
./gradlew clean build
docker build -t stirlingtools/stirling-pdf:dev -f Dockerfile .
docker run -p 8080:8080 stirlingtools/stirling-pdf:dev

Alternatively, run the comprehensive test suite using the provided script:

./test.sh

This script builds all Docker images and executes Cucumber integration tests as defined in the developer guide.

Summary

• Stirling-PDF requires both Gradle (via wrapper) and npm to build the full application locally.
• The Gradle wrapper (./gradlew) handles Java backend compilation and runs on port 8080.
• The npm/Vite frontend toolchain installs via npm ci and serves the UI on port 5173 with automatic API proxying.
• Set DISABLE_ADDITIONAL_FEATURES=false to enable security testing during local development.
• Use ./test.sh for full Docker-based integration testing when validating external tool dependencies.

Frequently Asked Questions

What version of Gradle does Stirling-PDF use?

The project uses Gradle 9.3.1, pinned in gradle/wrapper/gradle-wrapper.properties. You do not need a local Gradle installation; the ./gradlew wrapper script automatically downloads and caches this version on first run.

Should I use npm install or npm ci for the frontend?

Use npm ci when setting up the development environment. This command installs exact versions from package-lock.json, ensuring consistency with the repository's tested dependency tree. Use npm install only when intentionally updating dependencies.

How do I enable user authentication during local development?

Set the environment variable DISABLE_ADDITIONAL_FEATURES=false before starting the backend with ./gradlew bootRun. By default, this variable is true in development mode, which disables login, audit logs, and other security features to simplify testing.

Which ports are used during local development?

The backend runs on port 8080 (configurable via Spring Boot properties), and the frontend development server runs on port 5173. The frontend proxy configuration in frontend/package.json automatically forwards API calls from the browser to the backend, preventing cross-origin issues.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}