Fullstack Nhost Starter Template

A production-ready fullstack template with Nhost Auth + Spring Boot JWT validation. React 19, Spring Boot 3.4, PostgreSQL—all pre-configured.

✨ Why This Template?

• Hybrid architecture - Nhost handles auth, Spring Boot validates JWTs
• Ship in days, not weeks - Auth, database, security all working
• Modern tech stack - Spring Boot 3.4 + Java 24, React 19 + Vite 7
• No vendor lock-in - Your data in your PostgreSQL
• JWKS validation - Secure JWT validation against Nhost public keys

🏗️ Architecture

┌─────────┐     ┌──────────┐     ┌──────────────┐     ┌─────────────┐
│ Browser │────▶│  React   │────▶│   Nhost     │────▶│  Spring     │
│         │     │  (Front) │     │   Auth      │ JWT │   Boot      │
└─────────┘     └──────────┘     └──────────────┘     │  (Backend)  │
                                                   │              │
                                                   │  Validates   │
                                                   │  JWT via JWKS│
                                                   │              │
                                                   └──────┬───────┘
                                                          │
                                                          ▼
                                                   ┌─────────────┐
                                                   │  PostgreSQL │
                                                   │ (your data) │
                                                   └─────────────┘

1. Sign in via Nhost → Get JWT
2. Frontend calls backend → Authorization: Bearer <JWT>
3. Backend validates JWT → Against Nhost JWKS
4. Backend extracts userId → Stores data in PostgreSQL

🚀 Quick Start

1. Create Nhost Project

Go to nhost.io, create a project, and get:

• Subdomain & Region
• JWKS URL (auto-generated)

2. Clone and Configure

git clone https://github.com/your-username/your-repo.git
cd your-repo
cp frontend/.env.example frontend/.env.development

Frontend (frontend/.env.development):

VITE_NHOST_SUBDOMAIN=your-subdomain
VITE_NHOST_REGION=us-east-1
VITE_API_BASE_URL=http://localhost:8080/api

Backend (backend/.env):

# Nhost (for JWT validation)
nhost.subdomain=your-subdomain
nhost.region=us-east-1

# PostgreSQL (for business data)
DB_URL=jdbc:postgresql://localhost:5432/your_db
DB_USERNAME=postgres
DB_PASSWORD=your_password

3. Start Development

# Backend
cd backend && mvn spring-boot:run

# Frontend
cd frontend && npm install && npm run dev

📦 What's Included

Component	Technology	Purpose
Auth	Nhost	User management, JWT issuance
Backend	Spring Boot 3.4, Java 24	Business API, JWT validation
Database	PostgreSQL	Your business data
Frontend	React 19, Vite 7, TailwindCSS	UI, Nhost SDK
Security	Spring Security, JWKS	JWT validation, headers

🏗️ Project Structure

├── backend/                 # Spring Boot application
│   ├── src/main/java/com/template/
│   │   ├── config/          # Security config
│   │   ├── controller/      # REST endpoints
│   │   ├── entity/          # Database entities
│   │   ├── repository/      # Spring Data JDBC
│   │   └── security/        # JWT validation, filters
│   └── src/main/resources/db/migration/
├── frontend/                # React application
│   └── src/
│       ├── api/            # Backend API client (with JWT)
│       ├── context/        # Nhost auth context
│       ├── lib/            # Nhost client config
│       └── pages/          # Route pages
└── docs/                   # Documentation

🔧 Authentication Flow

Backend (Spring Boot)

@GetMapping("/api/user/me")
public ResponseEntity<Map<String, Object>> getCurrentUser(Authentication auth) {
    // Get userId from JWT (validated by JwtAuthenticationFilter)
    Map<String, Object> details = (Map<String, Object>) auth.getDetails();
    String userId = (String) details.get("userId");

    // Use userId to fetch/store data in your PostgreSQL
    User user = userRepository.findById(UUID.fromString(userId)).orElse(...);
    return ResponseEntity.ok(user);
}

Frontend (React)

import { nhost } from '@/lib/nhost';

// Sign in
const { session, error } = await nhost.auth.signIn({
  email: 'user@example.com',
  password: 'password',
});

// Call backend (JWT automatically added)
const response = await fetch('/api/user/me', {
  headers: {
    Authorization: `Bearer ${nhost.auth.getAccessToken()}`
  }
});

🧪 Running Tests

# Backend
cd backend && mvn test

# Frontend
cd frontend && npm test

📚 Documentation

• Nhost Config Guide - JWKS setup, JWT validation

🛠️ Customization

After cloning:

1. Rename package: Find/replace com.template with your package
2. Update pom.xml: Change groupId and artifactId
3. Add your tables: Create Flyway migrations in db/migration/
4. Add endpoints: Extend controllers with your business logic

📝 License

MIT License - use this template for anything!

---

Built for developers who ship. ⚡