typedef

Convert JSON to type definitions in multiple programming languages.

typedef is a code generator that analyzes JSON input and produces strongly-typed definitions for your target language. Whether you're working with API responses, configuration files, or any JSON data, typedef helps you quickly generate type-safe code.

Table of Contents

• Features
• Quick Start
• Installation
• Usage
• Clipboard Support Setup
• Examples
• Troubleshooting
• Web Interface
• License

Features

• Multiple Output Formats: Generate Go structs, TypeScript interfaces, Zod schemas, or JSDoc typedefs
• Flexible Input: Provide JSON via command flag, stdin pipe, or clipboard
• Smart Output: Send generated types to clipboard, stdout, or file
• Intelligent Type Deduplication: Automatically identifies and reuses structurally identical types
• Clipboard Integration: Seamless clipboard support with automatic fallback on macOS and Linux
• Web Interface: Also available as a browser-based tool at https://exanubes.github.io/typedef

Quick Start

# Build the tool
go build -o typedef main.go

# Generate Go types from JSON
./typedef --format go --input '{"name": "John", "age": 30, "active": true}'

# Output (copied to clipboard by default):
# type Root struct {
#     Active bool   
#     Age    int    
#     Name   string 
# }

Installation

Option 1: Install via Homebrew (macOS/Linux)

The easiest way to install typedef on macOS or Linux:

brew install exanubes/typedef/typedef

Verify installation:

typedef version 
# {
#   "build_time": "2026-01-10T14:29:40Z",
#   "commit_sha": "b33e9f0",
#   "version": "0.0.21"
# }

Option 2: Download Pre-built Binary

Download the latest release for your platform from GitHub Releases:

• macOS (Intel): typedef-darwin-amd64.tar.gz
• macOS (Apple Silicon): typedef-darwin-arm64.tar.gz
• Linux (Intel/AMD): typedef-linux-amd64.tar.gz
• Linux (ARM): typedef-linux-arm64.tar.gz

Extract and install:

# Download and extract (example for Linux amd64)
wget https://github.com/exanubes/typedef/releases/latest/download/typedef-linux-amd64.tar.gz
tar -xzf typedef-linux-amd64.tar.gz

# The archive contains: typedef (binary), README.md, LICENSE
# Verify it works
./typedef --format go --input '{"test": 1}'

# Add to PATH (optional)
sudo mv typedef /usr/local/bin/

Verify Download Integrity:

# Download checksums
wget https://github.com/exanubes/typedef/releases/latest/download/checksums.txt

# Verify checksum
sha256sum -c checksums.txt --ignore-missing

Option 3: Build from Source

Prerequisites: Go 1.24.4 or higher

# Clone the repository
git clone https://github.com/exanubes/typedef.git
cd typedef

# Build the CLI tool
go build -o typedef ./cmd/cli/main.go

Verify the build:

./typedef --format go --input '{"test": 1}' --target cli

Usage

Input Methods

typedef accepts JSON input in three ways (checked in this order):

1. --input flag: Explicit JSON string

   ./typedef --format go --input '{"name": "Alice", "age": 25}'

2. stdin (piped input):

   echo '{"name": "Bob", "score": 95}' | ./typedef --format typescript

3. Clipboard (automatic): If no input is provided, typedef reads from your clipboard

   # Copy JSON to clipboard, then run:
   ./typedef --format zod

Output Targets

Control where generated types are sent using the --target flag:

• clipboard (default): Copies output to clipboard for easy pasting

  ./typedef --format go --input '{"data": true}'
  # Output copied to clipboard automatically

• cli: Prints to stdout

  ./typedef --format typescript --target cli --input '{"id": 1}'

• file: Saves to a file (use --output-path to specify location, or it will fallback to default location)

  ./typedef --format go --input '{"user": "john"}' --target file --output-path ./types.go

Supported Formats

Format	Flag Values	Output
Go	go, golang	Go structs
TypeScript	typescript, ts	TypeScript interfaces
Zod	zod, ts-zod	Zod schema definitions
JSDoc	jsdoc	JSDoc typedef comments

Command Flags Reference

Flag	Description	Default
--format	Output format (go/typescript/zod/jsdoc)	Required
--input	JSON input string	Uses stdin or clipboard
--target	Output target (clipboard/cli/file)	clipboard
--output-path	File path when using --target file	./typedef.txt

Clipboard Support Setup

typedef can read JSON from your clipboard and copy generated types back to it automatically. Support varies by platform:

Platform	Requirements	Setup Needed
macOS	pbcopy, pbpaste (built-in)	None
Linux	wl-clipboard, xclip	Yes

macOS

No setup required! typedef uses the built-in pbcopy and pbpaste utilities that come with macOS.

Linux

wl-clipboard

Install the wl-clipboard package:

# Debian/Ubuntu
sudo apt-get install wl-clipboard

# Fedora
sudo dnf install wl-clipboard

# Arch Linux
sudo pacman -S wl-clipboard

Verify installation:

which wl-copy wl-paste

xclip

Install the xclip package:

# Debian/Ubuntu
sudo apt-get install xclip

# Fedora
sudo dnf install xclip

# Arch Linux
sudo pacman -S xclip

Verify installation:

which xclip

Automatic Fallback

If supported clipboard tools aren't detected, typedef will automatically fall back to stdout output without errors:

INFO: required dependencies for clipboard not detected. Falling back to cli target

The tool continues to work normally, printing output to your terminal instead. You can also explicitly use --target cli or --target file to bypass clipboard functionality.

Examples

Basic Usage

# Generate Go struct
typedef --format go --input '{"username": "alice", "email": "[email protected]"}'

# Generate TypeScript interface
typedef --format typescript --input '{"id": 1, "title": "Hello", "published": true}'

# Generate Zod schema
typedef --format zod --input '{"age": 30, "name": "Bob"}'

# Generate JSDoc typedef
typedef --format jsdoc --input '{"count": 5, "items": ["a", "b"]}'

Piped Input

# From echo
echo '{"status": "success", "data": {"id": 123}}' | typedef --format go

# From file
cat config.json | typedef --format typescript

# From API response with curl
curl -s https://api.example.com/user/1 | typedef --format go

Clipboard Workflow

# 1. Copy JSON from anywhere (browser, editor, etc.)
# 2. Run typedef
typedef --format typescript

# 3. Generated TypeScript interface is now in your clipboard
# 4. Paste directly into your code editor

File Output

# Save Go types to file
./typedef --format go --input '{"name": "test"}' --target file --output-path ./models/user.go

# Process API response and save
curl -s https://api.example.com/data | ./typedef --format typescript --target file --output-path ./types/api.ts

Real-World Scenarios

Converting API Response to TypeScript:

curl -s https://jsonplaceholder.typicode.com/users/1 | ./typedef --format typescript

Generating Go Structs from Config:

cat settings.json | ./typedef --format go --target file --output-path ./config/types.go

Creating Zod Schemas for Form Validation:

./typedef --format zod --input '{"email": "[email protected]", "age": 25, "subscribe": true}'

Using with jq for Complex JSON:

# Extract specific data with jq, then generate types
curl -s https://api.github.com/repos/golang/go | jq '.owner' | ./typedef --format typescript

Troubleshooting

Clipboard Issues

Problem: "Clipboard support disabled" message on Linux

Solution: Install the required clipboard tool for your display server:

• Wayland: sudo apt-get install wl-clipboard
• X11: sudo apt-get install xclip

Problem: Clipboard not working after installation

Solution: Verify the tools are in your PATH:

which wl-copy wl-paste  # Wayland
which xclip              # X11

Invalid JSON Errors

Problem: "Failed to parse JSON" or similar errors

Solution: Validate your JSON before passing to typedef:

# Using jq to validate
echo '{"test": 1}' | jq .

# Using online validators
# https://jsonlint.com/

Platform-Specific Issues

Linux: Permission denied

# Make the binary executable
chmod +x typedef

macOS: "cannot be opened because the developer cannot be verified"

# Allow the binary in System Preferences > Security & Privacy
# Or build from source as shown in Installation section

Web Interface

Prefer a browser-based tool? typedef is also available as a web application at:

https://exanubes.github.io/typedef

The web version offers the same type generation capabilities with a graphical interface, perfect for quick conversions without installing the CLI tool.

License

MIT License - see LICENSE file for details