Spring to TypeScript Generator

Generate TypeScript types automatically from your Spring Boot/Kotlin entities to ensure synchronization between backend and frontend.

Features

• ✨ Parse Kotlin/Java classes annotated with JPA
• 🔄 Generate TypeScript interfaces with proper types
• 🔗 Support entity relations (@OneToMany, @ManyToOne, etc.)
• 📦 Handle enums, nullable types, and Optional
• ✅ Include validation annotations
• 👀 Watch mode for automatic regeneration
• ⚙️ Highly configurable via JSON/YAML

Installation

npm install -g @geekles007/spring-to-ts

Or use with npx:

npx @geekles007/spring-to-ts generate --source ./src/main/kotlin --output ./frontend/types

Quick Start

1. Initialize a configuration file:

spring-to-ts init

2. Edit the generated spring-to-ts.config.json:

{
  "sourceDir": "./backend/src/main/kotlin/entities",
  "outputDir": "./frontend/src/types",
  "includeValidation": true,
  "dateFormat": "ISO"
}

3. Generate TypeScript types:

spring-to-ts generate

CLI Usage

Generate Types

spring-to-ts generate [options]

Options:

• -s, --source <path>: Source directory containing Kotlin/Java entities
• -o, --output <path>: Output directory for TypeScript types
• -c, --config <path>: Path to configuration file
• -w, --watch: Watch mode - regenerate on file changes
• --no-validation: Exclude validation annotations
• --no-relations: Exclude entity relations
• --date-format <format>: Date format (ISO, Date, or number)

Initialize Configuration

spring-to-ts init [options]

Options:

• -f, --format <format>: Configuration format (json or yaml)

Configuration

Configuration File

Create a spring-to-ts.config.json or spring-to-ts.config.yaml:

{
  "sourceDir": "./backend/src/main/kotlin/entities",
  "outputDir": "./frontend/src/types",
  "includeValidation": true,
  "dateFormat": "ISO",
  "includeEnums": true,
  "includeRelations": true,
  "excludePatterns": ["**/*Test.kt", "**/*Spec.kt"],
  "watch": false,
  "customTypeMapping": {
    "UUID": "string",
    "BigDecimal": "number",
    "LocalDateTime": "string",
    "LocalDate": "string"
  }
}

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | sourceDir | string | - | Required. Source directory with entities | | outputDir | string | - | Required. Output directory for types | | includeValidation | boolean | true | Include validation annotations as comments | | dateFormat | string | "ISO" | Date format: "ISO", "Date", or "number" | | includeEnums | boolean | true | Generate enums | | includeRelations | boolean | true | Include entity relations | | excludePatterns | string[] | [] | Glob patterns to exclude files | | watch | boolean | false | Enable watch mode | | customTypeMapping | object | {} | Custom type mappings |

Examples

Example Kotlin Entity

package com.example.entities

import jakarta.persistence.*
import java.time.LocalDateTime
import java.util.UUID

@Entity
@Table(name = "users")
data class User(
    @Id
    @GeneratedValue(strategy = GenerationType.UUID)
    val id: UUID? = null,

    @Column(nullable = false)
    val username: String,

    @Column(nullable = false)
    val email: String,

    val createdAt: LocalDateTime = LocalDateTime.now(),

    @OneToMany(mappedBy = "user")
    val posts: List<Post> = emptyList()
)

enum class UserRole {
    ADMIN,
    USER,
    GUEST
}

Generated TypeScript

// User.ts
import { Post } from './Post';

export interface User {
  id?: string;
  username: string;
  email: string;
  createdAt: string;
  posts: Post[];
}

// UserRole.ts
export enum UserRole {
  ADMIN = 'ADMIN',
  USER = 'USER',
  GUEST = 'GUEST',
}

Type Mappings

Default Kotlin/Java to TypeScript mappings:

| Kotlin/Java | TypeScript | |-------------|------------| | String | string | | Int, Long, Double, Float | number | | Boolean | boolean | | UUID | string | | LocalDate, LocalDateTime | string (configurable) | | List, Set | T[] | | Map<K, V> | Record<K, V> | | Optional, T? | T | undefined |

Watch Mode

Enable automatic regeneration when files change:

spring-to-ts generate --watch

Or in configuration:

{
  "watch": true
}

Supported Annotations

• @Entity, @Table, @Document - Entity detection
• @OneToMany, @ManyToOne, @OneToOne, @ManyToMany - Relations
• @Column(nullable = false) - Nullable detection
• Validation annotations (included as comments when includeValidation: true)

Development

# Install dependencies
npm install

# Build
npm run build

# Development mode
npm run dev

# Run tests
npm test

# Lint
npm run lint

# Format
npm run format

📚 Documentation

• Publishing Guide - How to publish to npm
• Contributing Guide - How to contribute
• Changelog - Version history

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details on:

• How to set up your development environment
• Coding standards and guidelines
• How to submit pull requests
• Reporting bugs and requesting features

📝 License

MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with Commander.js
• Styled with Chalk
• Powered by TypeScript

📞 Support

• 🐛 Report a bug
• ✨ Request a feature
• 💬 Discussions

Made with ❤️ by Geekles007 (https://github.com/geekles007)