x
Skip to main content
Version: 2.0 (Beta)

Contribution guidelines

Thanks for taking a look at how to contribute to Stirling PDFs open-source codebase!

Development Setup​

Prerequisites​

  • Java 21 or later
  • Node.js 18+
  • Docker (for testing)
  • Gradle (included in repository)

Getting Started​

  1. Clone the repository

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

  2. Backend Development

    # Build and run the Spring Boot backend
    ./gradlew bootRun
    # Backend runs on localhost:8080

  3. Frontend Development (V2.0+)

    # Navigate to frontend directory
    cd frontend

    # Install dependencies
    npm install

    # Run development server
    npm run dev
    # Frontend runs on localhost:5173, proxies API calls to backend (localhost:8080)

Contributing to Code​

Backend Contributions​

  • See our CONTRIBUTING guidelines
  • Backend uses Spring Boot + Java
  • Code formatting: Run ./gradlew spotlessApply before committing

Frontend Contributions (V2.0+)​

  • Frontend is a React + TypeScript application
  • Uses Vite for build tooling
  • UI components: Mantine UI + TailwindCSS
  • Adding new tools: See ADDING_TOOLS.md
  • Tool architecture: Uses useToolOperation hook pattern

Translation Contributions​

V2.0 Translations (JSON)​

Translation files are located in frontend/public/locales/

  • CRITICAL: Always update translations in en-GB only, never en-US
  • Files are organized by feature (e.g., common.json, tools.json)
  • Use standard JSON format

Legacy Translations (Properties)​

For V1.5 and backend translations:

Development Resources​

  • API Documentation: Access at /swagger-ui/index.html on your local instance
  • Developer Guide: See DeveloperGuide.md in the repository
  • Claude Code Guide: See CLAUDE.md for detailed architecture and patterns