# Skir

**Like Protocol Buffers, but better.**

Skir is a declarative language for defining data types, constants, and RPC interfaces. Write your schema once in a `.skir` file and generate idiomatic, type-safe code in TypeScript, Python, Java, C++, Kotlin, and Dart.

- Website: https://skir.build/
- GitHub: https://github.com/gepheum/skir

## Key Features

- **Single source of truth** — Define data types and APIs once, share across backend, frontend, and microservices.
- **Multi-language** — First-class support for TypeScript, Python, C++, Java, Kotlin, and Dart.
- **Idiomatic code gen** — Generated code feels native to each language.
- **Effortless serialization** — JSON and binary serialization generated automatically.
- **Schema evolution** — Built-in rules and checks for backward-compatible schema changes.
- **End-to-end type-safe RPCs** — Like tRPC, but for every language.
- **Built-in package manager** — Import types from other GitHub repos.
- **Easy setup** — `npx skir init`, single YAML config file, watch mode, formatter, VSCode extension.

## Quick Example

```skir
// shapes.skir

struct Point {
  x: int32;
  y: int32;
  label: string;
}

struct Shape {
  points: [Point];
  /// A short string describing this shape.
  label: string;
}

const TOP_RIGHT_CORNER: Point = {
  x: 600,
  y: 400,
  label: "top-right corner",
};

/// Returns true if no part of the shape's boundary curves inward.
method IsConvex(Shape): bool = 12345;
```

Skir compiles these definitions into native, type-safe code:

```python
from skirout.shapes_skir import Point

point = Point(x=3, y=4, label="P")

point_json = Point.serializer.to_json(point)
restored = Point.serializer.from_json(point_json)

assert(restored == point)
```

## Detailed Documentation

### Getting Started
- Setup & Workflow: https://skir.build/llms/setup.txt
  - Learn how to initialize a Skir project, configure code generators for multiple languages, and integrate Skir into your build workflow with watch mode and continuous integration.
- Language Reference: https://skir.build/llms/language-reference.txt
  - Complete syntax guide covering structs, enums, fields, variants, types, constants, methods, and all language features with examples.
- Examples & Projects: https://skir.build/llms/examples.txt
  - Browse a collection of starter projects for every language and full-stack end-to-end applications demonstrating real-world usage.

### Core Concepts
- Best Practices: https://skir.build/llms/best-practices.txt
  - Practical rules for writing future-proof schemas and robust APIs.
- Serialization: https://skir.build/llms/serialization.txt
  - Understand Skir's JSON (dense and readable) and binary serialization formats, including encoding rules for each data type and when to use each format.
- Schema Evolution: https://skir.build/llms/schema-evolution.txt
  - Learn safe schema changes (adding fields, renaming types), automated compatibility checking with snapshots, and how to maintain backward/forward compatibility.
- Typesafe RPCs: https://skir.build/llms/services.txt
  - Build type-safe RPC services by defining methods in schemas, implementing handlers with custom context, and integrating with existing HTTP frameworks.
- External Dependencies: https://skir.build/llms/dependencies.txt
  - Import and reuse types from other GitHub repositories by configuring dependencies in skir.yml, with support for transitive dependencies and private repositories.

### Language Guides
- TypeScript: https://skir.build/llms/typescript.txt
- Python: https://skir.build/llms/python.txt
- Java: https://skir.build/llms/java.txt
- Kotlin: https://skir.build/llms/kotlin.txt
- C++: https://skir.build/llms/cpp.txt
- Dart: https://skir.build/llms/dart.txt