Unified Management of Custom Domains via the TypeScript Domain SDK
Domain SDK provides a normalized TypeScript API for managing customer domains across Vercel, Cloudflare, and other cloud providers.
The Domain SDK abstracts provider-specific APIs into a single typed contract for managing custom hostnames.
- Domain SDK offers a single TypeScript interface to add, verify, and monitor customer domains across multiple hosting providers.
- The library supports adapters for Vercel, Cloudflare for SaaS, Railway, Render, and Netlify.
- Features include idempotent operations, automated polling with provider backoff, and an isolated testing adapter.
A Unified Interface for Domain Infrastructure
Managing custom domains for multi-tenant applications often requires integrating with various third-party hosting platforms. Each platform typically exposes a unique API with varying data structures for DNS verification, certificate issuance, and routing. The Domain SDK is an open-source TypeScript library designed to abstract these differences, providing developers with a normalized lifecycle for domain management.
By using a provider-agnostic client, developers can implement custom domain workflows without hardcoding logic specific to a single infrastructure provider. This approach allows applications to transition between services like Vercel and Cloudflare or support multiple platforms simultaneously while maintaining a consistent codebase for domain provisioning and monitoring.
Core Architecture and Provider Adapters
The SDK operates on an adapter-based architecture. Currently, it supports several major cloud platforms, including Vercel, Cloudflare for SaaS, Railway, Render, and Netlify. Each provider is implemented as a dedicated entry point within the library, ensuring that platform-specific requirements—such as API tokens or project identifiers—are isolated from the core logic.
The library is designed for server-side environments and requires Node.js version 20 or newer, or the Bun runtime. This restriction ensures that sensitive provider credentials, such as API tokens, remain securely within the server environment and are never exposed to the client-side browser code. For local development and CI/CD pipelines, the SDK includes an in-memory testing adapter that simulates provider behavior without making real network requests, facilitating faster and more reliable automated testing.
The Domain Lifecycle: From Addition to Verification
The SDK manages the entire lifecycle of a customer domain through a sequence of predictable operations. When a domain is added via the add() method, the library interacts with the configured provider to register the hostname. A key feature of this process is idempotency; if an application calls the add or remove methods multiple times for the same hostname, the SDK handles these as safe operations, treating an already-present or already-absent domain as a successful outcome.
Once a domain is added, the SDK returns a normalized object containing the exact DNS records required for the customer to configure their DNS provider. These records are categorized by their purpose: routing (CNAME or A records), ownership verification (TXT records), and TLS certificate issuance (ACME challenges). This structured data allows developers to build user interfaces that clearly instruct customers on how to update their DNS settings.
Honest Readiness and Polling
One of the primary challenges in domain management is determining when a domain is truly ready to serve traffic. The Domain SDK implements what it describes as "honest readiness." Rather than relying on optimistic assumptions, the SDK tracks routing, ownership, and certificate states separately. It only considers a domain active once the provider confirms that all three components are verified.
The SDK provides a waitUntilActive() utility that performs sequential polling. This mechanism includes built-in logic for timeouts, cancellation, and callbacks. To prevent rate-limiting issues, the polling logic is aware of provider-specific backoff requirements, ensuring that the application remains a good citizen of the provider's API ecosystem.
Handling Subdomains and Tenant Scoping
For applications that provide subdomains under a parent domain (e.g., tenant.myapp.com), the library includes a createSubdomainClient. This specialized client allows developers to scope domain operations to a specific base domain. It also supports reserved labels—such as "www", "api", or "admin"—to prevent tenants from claiming critical infrastructure hostnames.
While the SDK handles the communication with the hosting provider, it does not manage the application's internal database or tenant authorization. The application remains the authority on which tenant owns which domain, while the SDK acts as the bridge to the infrastructure provider, which remains the source of truth for the domain's external status.
Development and Release Tooling
The Domain SDK is developed using modern TypeScript tooling. It utilizes Bun for package management and testing. The release process is managed via Tegami, a tool that handles changelogs and versioning. The release workflow includes automated linting, type-checking, and cross-provider testing to maintain stability across the various adapters. The project is licensed under the MIT license, encouraging open-source contribution and integration into commercial products.
Enjoyed this?
Get more posts like this delivered to your inbox.
