synclangs 0.2.1

Write types once, use everywhere

SyncLangs

One centralized types file -> Multiple languages across all your codebases.

SyncLangs is a developer tool that enables you to maintain a single source of truth for your type definitions. Define your structures once in a universal schema language (.syln) and automatically synchronize them as native, idiomatic types across Python, TypeScript, and multiple projects or packages simultaneously.

Why SyncLangs?

Modern full-stack applications often use different languages for frontend (TypeScript) and backend (Python). This creates type duplication, drift risk, and maintenance burden.

SyncLangs solves this by:

• No more type drift - Define types once, generate native code for each language
• Zero config start - Works immediately with sensible defaults
• Fast watch mode - Regenerates in under 200ms on file save
• Readable syntax - Human-readable .syln files, no verbose boilerplate

Quick Start

Installation

pip install synclangs
# or
pipx install synclangs

Initialize a Project

syln init

This creates:

• syln.config.json - Configuration file
• shared/example.syln - Example schema

Define Your Types

Create shared/user.syln:

## Represents a user in the system
type User {
  ## Unique identifier
  id: string

  ## User's email address
  email: string

  ## Display name (optional)
  name: string?

  ## Account active status
  isActive: bool

  ## User tags
  tags: list<string>

  ## Arbitrary metadata
  metadata: map<string, any>
}

Generate Code

syln generate

TypeScript Output (user.types.ts):

// Auto-generated by SyncLangs - DO NOT EDIT

export interface User {
  /** Unique identifier */
  id: string;
  /** User's email address */
  email: string;
  /** Display name (optional) */
  name?: string;
  /** Account active status */
  isActive: boolean;
  /** User tags */
  tags: string[];
  /** Arbitrary metadata */
  metadata: Record<string, any>;
}

Python Output (user_types.py):

# Auto-generated by SyncLangs - DO NOT EDIT

from dataclasses import dataclass
from typing import Any, Optional

@dataclass
class User:
    """Represents a user in the system"""
    id: str
    """Unique identifier"""
    email: str
    """User's email address"""
    is_active: bool
    """Account active status"""
    tags: list[str]
    """User tags"""
    metadata: dict[str, Any]
    """Arbitrary metadata"""
    name: Optional[str] = None
    """Display name (optional)"""

Watch Mode

syln watch

Changes to .syln files automatically regenerate output in under 200ms.

CLI Reference

Command	Description
syln init	Initialize a new project with config and example
syln generate	Generate code from .syln files
syln check	Validate schemas without generating
syln watch	Watch mode with auto-regeneration
syln version	Show version

Common Flags

Flag	Short	Description
--config	-c	Config file path (default: ./syln.config.json)
--input	-i	Input directory (default: ./shared)
--out-ts		TypeScript output directory
--out-py		Python output directory
--verbose	-v	Verbose logging
--dry-run		Show what would be generated

Syntax Reference

Primitives

SyncLangs	Python	TypeScript
string	str	string
int	int	number
float	float	number
bool	bool	boolean
any	Any	any

Generics

SyncLangs	Python	TypeScript
list<T>	list[T]	T[]
map<K, V>	dict[K, V]	Record<K, V>

Nullable Types

type Example {
  required: string      # Required field
  optional: string?     # Optional field (nullable)
}

Imports

import { User, Address } from "./user.syln"

type Order {
  user: User
  shippingAddress: Address
}

Comments

# Regular comment (ignored in output)

## Doc comment (generates docstrings/JSDoc)
type User {
  ## The user's unique identifier
  id: string
}

Configuration

Create syln.config.json in your project root:

{
  "$schema": "https://synclangs.com/schema/v1.json",
  "version": "1.0",
  "input": "./shared",
  "outputs": {
    "typescript": {
      "enabled": true,
      "outDir": "./generated/ts",
      "fileExtension": ".types.ts"
    },
    "python": {
      "enabled": true,
      "outDir": "./generated/py",
      "fileExtension": "_types.py",
      "useDataclasses": true
    }
  },
  "options": {
    "watchDebounceMs": 100,
    "caseConversion": {
      "fields": {
        "python": "snake_case",
        "typescript": "camelCase"
      }
    },
    "generateIndex": true
  }
}

Error Messages

SyncLangs provides helpful error messages with file locations and suggestions:

Error: SY002 - Invalid type reference
  --> shared/user.syln:15:12
   |
15 |   role: Roles
   |         ^^^^^ Type 'Roles' not found. Did you mean 'Role'?
   |
Help: Import 'Roles' or define it in this file.

Documentation

• Getting Started
• Syntax Reference
• Configuration
• CLI Reference

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a PR.

License

MIT - see LICENSE

---

Made with care by SyncLangs