DEV Community: Robert Pitt

I Turned an S3 Bucket Into a Git Remote—No Server Required

Robert Pitt — Mon, 31 Aug 2026 09:36:17 +0000

Most Git remotes eventually involve running or depending on a server.

That means another service to deploy, secure, monitor, upgrade, and keep available—even when all you really need is somewhere to push and fetch a repository.

I wanted something simpler:

Normal Git commands
Storage I already control
Authentication through AWS credentials and IAM
No server, database, mounted filesystem, or custom account system

So I built git3: a Git remote helper that stores complete Git repositories in Amazon S3 or S3-compatible object storage.

Install it in one line

git3 supports Linux and macOS on amd64 and arm64, and requires Git 2.38 or newer.

curl -fsSL https://github.com/robertpitt/git3/releases/latest/download/install.sh | sh

Once installed, an S3 URL behaves like a Git remote:

git clone s3://my-bucket/repos/example

That is the basic idea: your S3 bucket becomes the remote.

Authentication uses the standard AWS credential chain

There is no separate git3 account system.

If your AWS credentials are already configured, clone normally:

git clone s3://my-bucket/repos/example

To use a named AWS profile:

AWS_PROFILE=development git clone s3://my-bucket/repos/example

You can also provide credentials through environment variables:

AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... AWS_DEFAULT_REGION=us-east-1 git clone s3://my-bucket/repos/example

This also means existing AWS authentication methods—including shared profiles, IAM Identity Center, web identity, and compute roles—remain responsible for resolving credentials.

Credentials, profiles, regions, endpoints, and encryption settings never need to appear in the Git remote URL.

Creating a repository

The S3 bucket must already exist, but you do not need to initialize anything inside it.

Add the remote and push a branch:

git remote add origin s3://my-bucket/repos/example
git push -u origin HEAD:refs/heads/main

The first valid branch push creates the repository under that bucket prefix.

A single bucket can contain multiple repositories:

s3://my-bucket/repos/api
s3://my-bucket/repos/frontend
s3://my-bucket/repos/infrastructure

Which Git operations work?

git3 supports the everyday full-repository workflows I wanted it to feel boringly normal to use with.

Command	Support
`git clone`	Full repository clones
`git fetch`	Incremental synchronization
`git pull`	Fetch and integrate normally
`git push`	Create or update branches and tags
`git push --delete`	Delete branches and tags
`git push --force`	Forced ref updates
`git push --force-with-lease`	Lease-checked forced updates
`git push --atomic`	Atomic multi-ref pushes
`git submodule`	Supported with `s3://` protocol permission

Signed commits and signed tags are preserved as ordinary Git objects.

Both SHA-1 and SHA-256 repositories are supported without translating between object formats.

How can Git use an S3 URL?

Git supports external remote helpers.

When Git encounters this:

git clone s3://my-bucket/repos/example

it invokes a helper named git-remote-s3.

git3 implements that helper protocol and translates Git’s fetch and push operations into S3 reads and conditional writes.

The flow looks roughly like this:

Git invokes git-remote-s3.
Native Git creates and verifies packfiles.
git3 uploads immutable packs and transaction records.
A small HEAD document publishes the new ref state.
Fetch installs native packs directly into .git/objects/pack.

There is no Git server between the developer and the bucket. Git computation happens on the workstation or CI runner.

Native Git repositories, not a mounted filesystem

git3 does not pretend that an S3 bucket is a POSIX filesystem.

It also does not replace Git’s local object database with a custom implementation.

After a successful clone or fetch, the repository contains normal Git packfiles. Standard local commands continue working:

git log
git checkout
git fsck
git repack

You could even remove git3 after fetching and the local repository would remain an ordinary Git repository.

That property was important to me: S3 is the remote storage layer, but Git still owns the local repository.

Publishing ref updates safely

S3 objects are not updated using filesystem locks, so git3 uses conditional requests as a compare-and-swap operation.

Most repository data is immutable. One small mutable HEAD object identifies the current repository state.

A push:

Reads and validates the current state.
Creates and uploads immutable object data.
Builds a transaction describing the ref updates.
Replaces HEAD only if it has not changed since it was read.

If another writer publishes first, the conditional write fails instead of silently overwriting their update.

Accepted multi-ref changes are published through one HEAD replacement, which makes the visible ref update atomic.

Fetching without downloading everything again

Each client keeps a verified logical cursor.

An active client fetches only the transactions and Git data published after that cursor. Physical pack identities are not treated as repository history, so remote or local repacking does not force clients to start again.

When nothing has changed, a fetch requires:

One conditional S3 read
Zero Git-object bytes
No material local writes

Cold clones download the current compacted packset and the bounded transaction tail.

No S3 listing during normal Git operations

Normal clone, fetch, push, and maintenance operations do not need s3:ListBucket or s3:DeleteObject.

A reader can be limited to:

{
  "Effect": "Allow",
  "Action": ["s3:GetObject"],
  "Resource": "arn:aws:s3:::BUCKET/PREFIX/.git/git3/*"
}

A writer adds s3:PutObject and multipart-upload permissions.

Listing and deletion are reserved for explicit garbage collection. GC is dry-run by default and uses a published, resumable barrier before deleting anything.

git s3 gc origin
git s3 gc origin --execute --older-than 30d

Maintenance and diagnostics

git3 includes several administrative commands:

git s3 doctor origin
git s3 fsck origin --full
git s3 maintenance origin
git s3 gc origin
git s3 set-head origin refs/heads/main

Maintenance compacts immutable packs for efficient cold clones without changing the logical repository history.

S3-compatible services

Alternative S3-compatible endpoints can be configured without changing the remote URL:

export GIT3_ENDPOINT=https://objects.example.com
export GIT3_PATH_STYLE=true

An endpoint needs the S3 behavior git3 relies on, including conditional writes, range requests, multipart uploads, and compatible error semantics.

What git3 intentionally does not provide

git3 is a storage and synchronization tool, not a GitHub or GitLab replacement.

It does not currently provide:

Shallow or partial clones
Integrated Git LFS storage
Server-side hooks
Protected branches
Pull requests or code review
Merge queues
A web interface
git archive --remote
Git wire-protocol server endpoints
Windows release binaries

If you need an independent LFS service, it can still be configured separately.

There is also an important security boundary: any AWS principal that can overwrite the reserved S3 prefix is effectively a repository administrator. git3 cannot enforce branch protection against someone who already has direct write access to the underlying repository metadata.

Where might this be useful?

git3 may be a good fit when:

Your organization already uses S3 and IAM extensively
You want a private Git remote without operating a service
CI workers already receive temporary AWS credentials
You want repository storage inside your own cloud boundary
You need Git synchronization but not forge features
You want a remote that can work with compatible object-storage platforms

It is probably not the right choice for a high-traffic public forge, a workflow centered on pull requests, or a very large monorepo that depends on partial cloning.

Try it

git3 is open source under the Apache-2.0 license:

github.com/robertpitt/git3

I would especially appreciate feedback on:

The S3 storage and concurrency model
Which missing Git operation matters most to you
S3-compatible services you would like to see tested
Workflows where a serverless Git remote would be useful

Would you use an S3 bucket as a Git remote? Let me know in the comments.

I Turned an S3 Bucket Into a Git Remote—No Server Required

Robert Pitt — Sun, 30 Aug 2026 01:26:07 +0000

Most Git remotes eventually involve running or depending on a server.

That means another service to deploy, secure, monitor, upgrade, and keep available—even when all you really need is somewhere to push and fetch a repository.

I wanted something simpler:

Normal Git commands
Storage I already control
Authentication through AWS credentials and IAM
No server, database, mounted filesystem, or custom account system

So I built git3: a Git remote helper that stores complete Git repositories in Amazon S3 or S3-compatible object storage.

Install it in one line

git3 supports Linux and macOS on amd64 and arm64, and requires Git 2.38 or newer.

curl -fsSL https://github.com/robertpitt/git3/releases/latest/download/install.sh | sh

Once installed, an S3 URL behaves like a Git remote:

git clone s3://my-bucket/repos/example

That is the basic idea: your S3 bucket becomes the remote.

Authentication uses the standard AWS credential chain

There is no separate git3 account system.

If your AWS credentials are already configured, clone normally:

git clone s3://my-bucket/repos/example

To use a named AWS profile:

AWS_PROFILE=development git clone s3://my-bucket/repos/example

You can also provide credentials through environment variables:

AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... AWS_DEFAULT_REGION=us-east-1 git clone s3://my-bucket/repos/example

This also means existing AWS authentication methods—including shared profiles, IAM Identity Center, web identity, and compute roles—remain responsible for resolving credentials.

Credentials, profiles, regions, endpoints, and encryption settings never need to appear in the Git remote URL.

Creating a repository

The S3 bucket must already exist, but you do not need to initialize anything inside it.

Add the remote and push a branch:

git remote add origin s3://my-bucket/repos/example
git push -u origin HEAD:refs/heads/main

The first valid branch push creates the repository under that bucket prefix.

A single bucket can contain multiple repositories:

s3://my-bucket/repos/api
s3://my-bucket/repos/frontend
s3://my-bucket/repos/infrastructure

Which Git operations work?

git3 supports the everyday full-repository workflows I wanted it to feel boringly normal to use with.

Command	Support
`git clone`	Full repository clones
`git fetch`	Incremental synchronization
`git pull`	Fetch and integrate normally
`git push`	Create or update branches and tags
`git push --delete`	Delete branches and tags
`git push --force`	Forced ref updates
`git push --force-with-lease`	Lease-checked forced updates
`git push --atomic`	Atomic multi-ref pushes
`git submodule`	Supported with `s3://` protocol permission

Signed commits and signed tags are preserved as ordinary Git objects.

Both SHA-1 and SHA-256 repositories are supported without translating between object formats.

How can Git use an S3 URL?

Git supports external remote helpers.

When Git encounters this:

git clone s3://my-bucket/repos/example

it invokes a helper named git-remote-s3.

git3 implements that helper protocol and translates Git’s fetch and push operations into S3 reads and conditional writes.

The flow looks roughly like this:

Git invokes git-remote-s3.
Native Git creates and verifies packfiles.
git3 uploads immutable packs and transaction records.
A small HEAD document publishes the new ref state.
Fetch installs native packs directly into .git/objects/pack.

There is no Git server between the developer and the bucket. Git computation happens on the workstation or CI runner.

Native Git repositories, not a mounted filesystem

git3 does not pretend that an S3 bucket is a POSIX filesystem.

It also does not replace Git’s local object database with a custom implementation.

After a successful clone or fetch, the repository contains normal Git packfiles. Standard local commands continue working:

git log
git checkout
git fsck
git repack

You could even remove git3 after fetching and the local repository would remain an ordinary Git repository.

That property was important to me: S3 is the remote storage layer, but Git still owns the local repository.

Publishing ref updates safely

S3 objects are not updated using filesystem locks, so git3 uses conditional requests as a compare-and-swap operation.

Most repository data is immutable. One small mutable HEAD object identifies the current repository state.

A push:

Reads and validates the current state.
Creates and uploads immutable object data.
Builds a transaction describing the ref updates.
Replaces HEAD only if it has not changed since it was read.

If another writer publishes first, the conditional write fails instead of silently overwriting their update.

Accepted multi-ref changes are published through one HEAD replacement, which makes the visible ref update atomic.

Fetching without downloading everything again

Each client keeps a verified logical cursor.

When nothing has changed, a fetch requires:

One conditional S3 read
Zero Git-object bytes
No material local writes

Cold clones download the current compacted packset and the bounded transaction tail.

No S3 listing during normal Git operations

Normal clone, fetch, push, and maintenance operations do not need s3:ListBucket or s3:DeleteObject.

A reader can be limited to:

{
  "Effect": "Allow",
  "Action": ["s3:GetObject"],
  "Resource": "arn:aws:s3:::BUCKET/PREFIX/.git/git3/*"
}

A writer adds s3:PutObject and multipart-upload permissions.

Listing and deletion are reserved for explicit garbage collection. GC is dry-run by default and uses a published, resumable barrier before deleting anything.

git s3 gc origin
git s3 gc origin --execute --older-than 30d

Maintenance and diagnostics

git3 includes several administrative commands:

git s3 doctor origin
git s3 fsck origin --full
git s3 maintenance origin
git s3 gc origin
git s3 set-head origin refs/heads/main

Maintenance compacts immutable packs for efficient cold clones without changing the logical repository history.

S3-compatible services

Alternative S3-compatible endpoints can be configured without changing the remote URL:

export GIT3_ENDPOINT=https://objects.example.com
export GIT3_PATH_STYLE=true

An endpoint needs the S3 behavior git3 relies on, including conditional writes, range requests, multipart uploads, and compatible error semantics.

What git3 intentionally does not provide

git3 is a storage and synchronization tool, not a GitHub or GitLab replacement.

It does not currently provide:

Shallow or partial clones
Integrated Git LFS storage
Server-side hooks
Protected branches
Pull requests or code review
Merge queues
A web interface
git archive --remote
Git wire-protocol server endpoints
Windows release binaries

If you need an independent LFS service, it can still be configured separately.

Where might this be useful?

git3 may be a good fit when:

Your organization already uses S3 and IAM extensively
You want a private Git remote without operating a service
CI workers already receive temporary AWS credentials
You want repository storage inside your own cloud boundary
You need Git synchronization but not forge features
You want a remote that can work with compatible object-storage platforms

It is probably not the right choice for a high-traffic public forge, a workflow centered on pull requests, or a very large monorepo that depends on partial cloning.

Try it

git3 is open source under the Apache-2.0 license:

github.com/robertpitt/git3

I would especially appreciate feedback on:

The S3 storage and concurrency model
Which missing Git operation matters most to you
S3-compatible services you would like to see tested
Workflows where a serverless Git remote would be useful

Would you use an S3 bucket as a Git remote? Let me know in the comments.

Building Type-Safe APIs with itty-spec: A Contract-First Approach

Robert Pitt — Sun, 14 Dec 2025 21:43:46 +0000

Building Type-Safe APIs with itty-spec: A Contract-First Approach

itty-spec is a powerful library that brings type-safe, contract-first API development to itty-router. By defining your API contracts using standard schema libraries, you get automatic validation, full TypeScript type inference, and seamless OpenAPI documentation generation—all while maintaining compatibility with edge computing environments.

The Problem: Building APIs Without Contracts

Traditional API development often involves:

Manual validation scattered across route handlers
Type definitions that drift from actual runtime behavior
Inconsistent error handling for invalid requests
Outdated documentation that requires manual maintenance
No runtime guarantee that handlers match their documented contracts

These issues lead to bugs, security vulnerabilities, and poor developer experience. itty-spec solves these problems by making your schema definitions the single source of truth for routes, validation, types, and documentation.

Core Philosophy: Contract-First Development

itty-spec follows a contract-first approach where you define your API's structure and validation rules upfront using standard schema libraries. The contract becomes the foundation that drives:

Route registration - Automatically creates routes from contract definitions
Request validation - Validates all incoming data against schemas
Type inference - Provides full TypeScript types for handlers
Response validation - Ensures handlers return valid responses
Documentation generation - Automatically creates OpenAPI specifications

Key Features and Capabilities

1. Type-Safe Handlers

One of the most powerful features of itty-spec is how it provides fully typed request objects to your handlers. When you define a contract, TypeScript automatically infers the types for:

Path parameters - Extracted from route patterns like /users/:id
Query parameters - Typed and validated query strings
Request headers - Validated header objects
Request body - Typed request payloads

import { createContract } from 'itty-spec';
import { z } from 'zod';

const contract = createContract({
  getUser: {
    path: '/users/:id',
    query: z.object({
      include: z.enum(['posts', 'comments']).optional(),
    }),
    headers: z.object({
      'x-api-key': z.string(),
    }),
    responses: {
      200: { body: z.object({ id: z.string(), name: z.string() }) },
    },
  },
});

// In your handler, everything is fully typed!
const router = createRouter({
  contract,
  handlers: {
    getUser: async (request) => {
      // request.params.id is typed as string
      // request.query.include is typed as 'posts' | 'comments' | undefined
      // request.validatedHeaders['x-api-key'] is typed as string

      const userId = request.params.id; // TypeScript knows this is a string
      const include = request.query.include; // Type-safe enum access

      return request.json({ id: userId, name: 'John' });
    },
  },
});

The type system ensures you can't accidentally access properties that don't exist and provides autocomplete for all available fields.

2. Validation-Driven Contracts

itty-spec uses a middleware pipeline that automatically validates all incoming requests before they reach your handlers. The validation happens in a specific order:

Path parameters - Extracted from the URL and validated against optional pathParams schema
Query parameters - Parsed from the query string and validated
Headers - Normalized and validated
Request body - Parsed from JSON and validated (for POST/PUT/PATCH requests)

If validation fails at any step, the request is rejected with a 400 status code and detailed error information, without ever reaching your handler code.

const contract = createContract({
  createUser: {
    path: '/users',
    method: 'POST',
    request: z.object({
      name: z.string().min(1).max(100),
      email: z.string().email(),
      age: z.number().int().min(18).max(120),
    }),
    responses: {
      200: { body: z.object({ id: z.string(), name: z.string() }) },
      400: { body: z.object({ error: z.string(), details: z.any() }) },
    },
  },
});

// If the request body doesn't match the schema, validation fails automatically
// Your handler only receives validated, typed data

This means your handlers can focus on business logic, knowing that all input data already conforms to your contract's requirements.

3. Standard Schema Spec Support

itty-spec leverages the Standard Schema V1 specification to provide vendor-agnostic schema support. This means you can use any schema library that implements the Standard Schema spec, including:

Zod (v4) - Currently fully supported with OpenAPI generation
Valibot - Compatible with validation (OpenAPI support planned)
ArkType - Compatible with validation (OpenAPI support planned)
Any other library implementing Standard Schema V1

The Standard Schema spec provides a unified interface (StandardSchemaV1) that includes:

~standard.vendor - Identifies the schema library
~standard.validate() - Standardized validation method
Type inference capabilities through TypeScript

This vendor-agnostic approach means you're not locked into a specific schema library and can migrate between them without changing your contract definitions.

// Works with Zod
import { z } from 'zod';
const zodSchema = z.object({ name: z.string() });

// Works with Valibot (once supported)
import * as v from 'valibot';
const valibotSchema = v.object({ name: v.string() });

// Both can be used in contracts
const contract = createContract({
  endpoint: {
    path: '/test',
    request: zodSchema, // or valibotSchema
    responses: { 200: { body: zodSchema } },
  },
});

4. Automated Documentation Generation

One of the most powerful features of itty-spec is its ability to automatically generate OpenAPI 3.1 specifications from your contracts. This eliminates the need to manually maintain API documentation—your schema definitions become the documentation.

The OpenAPI generator:

Extracts schemas from all contract operations
Converts path formats from :param to {param} (OpenAPI standard)
Maps response schemas to OpenAPI response objects
Includes headers, query params, and request bodies in the specification
Deduplicates schemas using a registry system to avoid duplication

import { createOpenApiSpecification } from 'itty-spec/openapi';
import { contract } from './contract';

const openApiSpec = createOpenApiSpecification(contract, {
  title: 'User Management API',
  version: '1.0.0',
  description: 'A comprehensive API for managing users',
  servers: [
    { url: 'https://api.example.com', description: 'Production' },
    { url: 'https://staging-api.example.com', description: 'Staging' },
  ],
});

// The spec can be used for:
// - Serving interactive documentation (Swagger UI, Stoplight Elements)
// - Generating client SDKs (openapi-generator, swagger-codegen)
// - API testing tools (Postman, Insomnia)
// - CI/CD validation

The generated OpenAPI spec is fully compliant with OpenAPI 3.1 and can be used with any tool that supports the specification.

5. Type-Safe Response Helpers

itty-spec provides typed response helper methods on the request object that ensure your responses match your contract definitions:

request.json(body, status?, headers?) - Creates JSON responses with type validation
request.html(html, status?, headers?) - Creates HTML responses
request.error(status, body, headers?) - Creates error responses
request.noContent(status) - Creates 204 No Content responses

These helpers use TypeScript's type system to ensure:

Only valid status codes from your contract can be used
Response bodies match the schema for the given status code
Headers match the optional header schema for the response

const contract = createContract({
  getUser: {
    path: '/users/:id',
    responses: {
      200: { body: z.object({ id: z.string(), name: z.string() }) },
      404: { body: z.object({ error: z.string() }) },
    },
  },
});

const router = createRouter({
  contract,
  handlers: {
    getUser: async (request) => {
      const user = await findUser(request.params.id);

      if (!user) {
        // TypeScript ensures this matches the 404 response schema
        return request.error(404, { error: 'User not found' });
      }

      // TypeScript ensures this matches the 200 response schema
      return request.json({ id: user.id, name: user.name });
    },
  },
});

If you try to return an invalid status code or a body that doesn't match the schema, TypeScript will catch the error at compile time.

Real-World Example

Let's look at a complete example that demonstrates all these features working together:

import { createContract, createRouter } from 'itty-spec';
import { createOpenApiSpecification } from 'itty-spec/openapi';
import { z } from 'zod';

// Define schemas
const UserSchema = z.object({
  id: z.uuid(),
  name: z.string().min(1),
  email: z.string().email(),
  createdAt: z.string().datetime(),
});

const CreateUserSchema = z.object({
  name: z.string().min(1),
  email: z.string().email(),
});

const ListUsersQuerySchema = z.object({
  page: z.number().int().min(1).default(1),
  limit: z.number().int().min(1).max(100).default(20),
  search: z.string().optional(),
});

// Define the contract
const contract = createContract({
  listUsers: {
    path: '/users',
    method: 'GET',
    query: ListUsersQuerySchema,
    headers: z.object({
      'x-api-key': z.string(),
    }),
    responses: {
      200: {
        body: z.object({
          users: z.array(UserSchema),
          total: z.number(),
          page: z.number(),
          limit: z.number(),
        }),
      },
    },
  },
  createUser: {
    path: '/users',
    method: 'POST',
    request: CreateUserSchema,
    headers: z.object({
      'content-type': z.literal('application/json'),
    }),
    responses: {
      201: { body: UserSchema },
      400: { body: z.object({ error: z.string(), details: z.any() }) },
    },
  },
  getUser: {
    path: '/users/:id',
    method: 'GET',
    pathParams: z.object({
      id: z.string().uuid(),
    }),
    responses: {
      200: { body: UserSchema },
      404: { body: z.object({ error: z.string() }) },
    },
  },
});

// Create the router with handlers
const router = createRouter({
  contract,
  handlers: {
    listUsers: async (request) => {
      // All types are inferred from the contract
      const { page, limit, search } = request.query;
      const apiKey = request.validatedHeaders['x-api-key'];

      // Business logic here
      const users = await findUsers({ page, limit, search, apiKey });

      return request.json({
        users: users.items,
        total: users.total,
        page,
        limit,
      });
    },

    createUser: async (request) => {
      // request.validatedBody is fully typed as CreateUserSchema
      const { name, email } = request.validatedBody;

      const user = await createUser({ name, email });

      // TypeScript ensures the response matches UserSchema
      return request.json({
        id: user.id,
        name: user.name,
        email: user.email,
        createdAt: user.createdAt.toISOString(),
      }, 201);
    },

    getUser: async (request) => {
      // request.params.id is typed as string (from uuid schema)
      const user = await findUserById(request.params.id);

      if (!user) {
        return request.error(404, { error: 'User not found' });
      }

      return request.json({
        id: user.id,
        name: user.name,
        email: user.email,
        createdAt: user.createdAt.toISOString(),
      });
    },
  },
});

// Generate OpenAPI documentation
const openApiSpec = createOpenApiSpecification(contract, {
  title: 'User Management API',
  version: '1.0.0',
  description: 'API for managing users',
  servers: [{ url: 'https://api.example.com' }],
});

// Export for use in Cloudflare Workers, Node.js, Bun, etc.
export default {
  fetch: router.fetch,
};

Architecture: How It Works

Under the hood, itty-spec uses a sophisticated middleware system that:

Registers routes - Automatically creates routes from contract definitions
Validates requests - Middleware pipeline validates path params, query, headers, and body
Attaches types - Extends request objects with typed properties
Provides helpers - Adds typed response helper methods
Formats responses - Converts contract response objects to HTTP responses
Handles errors - Catches validation errors and formats them appropriately

The middleware execution order ensures that validation happens before your handlers run, and type information flows through the entire request lifecycle.

Benefits Summary

Using itty-spec provides several key benefits:

Type Safety - Catch errors at compile time, not runtime
Reduced Boilerplate - Define routes, validation, and types in one place
Automatic Validation - No need to manually validate requests
Up-to-Date Documentation - OpenAPI specs generated from your contracts
Vendor Flexibility - Use any Standard Schema V1 compatible library
Edge Compatible - Works everywhere itty-router works (Cloudflare Workers, Node.js, Bun, etc.)
Better DX - Full autocomplete and type checking in your IDE

Getting Started

To get started with itty-spec:

npm install itty-spec@latest zod
# or
pnpm add itty-spec@latest zod

Then define your contract and create your router:

import { createContract, createRouter } from 'itty-spec';
import { z } from 'zod';

const contract = createContract({
  hello: {
    path: '/hello',
    query: z.object({ name: z.string().default('World') }),
    responses: {
      200: { body: z.object({ message: z.string() }) },
    },
  },
});

const router = createRouter({
  contract,
  handlers: {
    hello: async (request) => {
      return request.json({
        message: `Hello, ${request.query.name}!`,
      });
    },
  },
});

export default { fetch: router.fetch };

Conclusion

itty-spec brings contract-first development to the itty-router ecosystem, providing a powerful yet simple way to build type-safe APIs. By leveraging standard schemas and automatic validation, it eliminates many common sources of bugs while improving developer experience and maintaining up-to-date documentation.

Whether you're building APIs for Cloudflare Workers, Node.js, or Bun, itty-spec gives you the tools you need to build robust, well-documented, and type-safe APIs with minimal boilerplate.

For more information, visit the GitHub repository.