Spring Boot Kotlin React Template

A full-stack template for building web applications with Spring Boot, Kotlin, and React.

Technology Stack and Features

• ⚡ Spring Boot 4.0.2 with Kotlin 2.2.21
  • 💾 PostgreSQL as the SQL database
  • 🔐 Spring Security with JWT authentication
  • 📧 Email templates with FreeMarker
  • 🔄 Flyway for database migrations
  • 📖 SpringDoc OpenAPI (Swagger UI)
• 🚀 React 19 with TypeScript for the frontend
  • ⚡ Vite for fast builds
  • 🛣️ TanStack Router for file-based routing
  • 📊 TanStack Query for server state
  • 🎨 Tailwind CSS v4 and shadcn/ui
  • 🤖 Automatically generated API client from OpenAPI spec
  • 🦇 Dark mode support
• 🐋 Docker Compose for local development
• 🔒 Secure password hashing with BCrypt
• 🔑 JWT (JSON Web Token) authentication
• 📫 Email-based password recovery
• 📬 MailCatcher for local email testing

Quick Start

Prerequisites

• Docker - for running all services locally

Start the Application

docker compose up -d

Services will be available at:

Service	URL
Frontend	http://localhost:5173
Backend API	http://localhost:8000
API Docs (Swagger)	http://localhost:8000/swagger-ui.html
MailCatcher	http://localhost:1080
PostgreSQL	localhost:5432

Generate Secret Keys

For production, generate secure random keys:

# Generate a random secret key
openssl rand -base64 32

Development

Local Development (Outside Docker)

You can run services locally instead of Docker:

Backend

cd backend
mvn spring-boot:run

The Spring Boot spring-boot-docker-compose module will automatically start PostgreSQL and MailCatcher.

Frontend

cd frontend
bun run dev

Generate Frontend API Client

After modifying backend API endpoints, regenerate the TypeScript client:

# Make sure backend is running first
docker compose up backend

# Then regenerate the client
cd frontend
bun run generate-client

This command:

1. Fetches the OpenAPI spec from http://localhost:8000/v3/api-docs
2. Generates TypeScript types and client code in src/client/

Documentation

• Backend: backend/README.md
• Frontend: frontend/README.md
• Development: development.md

Default Credentials

The application is initialized with a default superuser:

• Email: admin@template.com
• Password: 12345678

Important: Change these credentials before deploying to production.

License

This project is licensed under the terms of the MIT license.