# Domain SDK

> Add, verify, monitor, and remove customer domains across Vercel, Cloudflare for SaaS, Railway, Render, and Netlify with one server-side TypeScript API.

## Agent resources

- [Complete documentation](https://domain-sdk.dev/llms-full.txt): All documentation in one file.
- [Human-readable sitemap](https://domain-sdk.dev/sitemap): Every canonical documentation page grouped by topic.
- [Install the Domain SDK skill](https://github.com/opencoredev/domain-sdk/tree/main/skills/domain-sdk): `npx skills add opencoredev/domain-sdk --skill domain-sdk`
- [Source code](https://github.com/opencoredev/domain-sdk): Package source, providers, tests, and examples.

## Product facts

- Package: `@opencoredev/domain-sdk`
- License: MIT
- Runtime: Server-side Node.js 20+ or Bun
- Language: TypeScript
- Providers: Vercel, Cloudflare for SaaS, Railway, Render, and Netlify
- Cost: The open-source SDK is free; infrastructure provider charges are separate.
- Scope: Domain SDK manages domain lifecycle calls and normalized DNS instructions. It does not register domains, host DNS, proxy traffic, or store tenant data.

## Documentation

- [TypeScript custom domains SDK](/docs): Add, verify, monitor, and remove SaaS customer domains with one provider-independent TypeScript API.
- [Install Domain SDK for TypeScript](/docs/installation): Install the server-side TypeScript SDK and start managing SaaS customer domains with Vercel, Cloudflare, Railway, Render, or Netlify.
- Guides
  - [Custom domain implementation guides](/docs/guides): Build secure SaaS custom-domain workflows with practical TypeScript guides for setup, DNS, polling, persistence, testing, and troubleshooting.
  - [Build a custom-domain settings page](/docs/guides/custom-domain-settings-page): Connect an authenticated tenant endpoint to Domain SDK without exposing credentials.
  - [Add and remove customer domains](/docs/guides/add-remove-domains): Use safe idempotency without silently claiming domains from another resource.
  - [Display DNS records correctly](/docs/guides/display-dns-records): Give customers complete instructions without registrar-specific assumptions.
  - [Store domain state in your database](/docs/guides/store-domain-state): Persist tenant ownership and cached UI state while keeping the provider authoritative.
  - [Poll until a domain is active](/docs/guides/poll-until-active): Wait sequentially with cancellation, timeout, and provider backoff.
  - [Troubleshoot pending DNS](/docs/guides/troubleshoot-dns): Diagnose routing and ownership records that remain pending or invalid.
  - [Troubleshoot certificate issuance](/docs/guides/troubleshoot-certificates): Separate certificate validation from routing and hostname ownership.
  - [Handle apex domains and subdomains](/docs/guides/apex-and-subdomains): Respect adapter capabilities without guessing public-suffix boundaries.
  - [Give tenants managed subdomains](/docs/guides/managed-subdomains): Safely map tenant labels to subdomains under a parent domain you own.
  - [Tenant authorization and domain security](/docs/guides/tenant-security): Prevent cross-tenant access and abandoned-domain takeover.
  - [Production credential setup](/docs/guides/production-credentials): Scope and store platform credentials for server-side domain management.
  - [Switch providers safely](/docs/guides/switch-providers): Build a deliberate migration without pretending Domain SDK moves live traffic.
  - [Test without external API calls](/docs/guides/test-without-network): Simulate latency, failures, transitions, and calls with isolated memory providers.
- Components
  - [Custom domain UI components](/docs/components): Add accessible, copy-ready DNS instructions and optional one-click DNS setup to a React custom-domain settings page.
  - [DNS records UI component](/docs/components/dns-records-table): Add a copy-ready React DNS records table to your SaaS domain settings page so customers can configure routing, ownership, and certificates.
  - [One-click DNS setup component](/docs/components/one-click-dns-setup): Send customers from your SaaS domain settings page to a supported DNS provider for reviewed, automatic record configuration.
- Providers
  - [Custom domain provider comparison](/docs/providers): Compare custom domain support across Vercel, Cloudflare for SaaS, Railway, Render, and Netlify before choosing a TypeScript adapter.
  - [Vercel custom domains](/docs/providers/vercel): Add, verify, monitor, and remove Vercel project domains with a typed, server-side TypeScript adapter that preserves exact DNS instructions.
  - [Cloudflare for SaaS custom domains](/docs/providers/cloudflare): Manage Cloudflare for SaaS Custom Hostnames with a server-side TypeScript adapter for normalized status, DNS records, and certificates.
  - [Railway custom domains](/docs/providers/railway): Add, monitor, and remove Railway custom domains for one project, environment, and service with a typed server-side TypeScript adapter.
  - [Render custom domains](/docs/providers/render): Add, verify, monitor, and remove custom domains for a Render web service or static site with a server-side TypeScript adapter.
  - [Netlify custom domains](/docs/providers/netlify): Add, monitor, and remove customer domains as aliases on an existing Netlify site with a typed server-side TypeScript adapter.
  - [Testing provider](/docs/providers/testing): Exercise domain flows without credentials, network calls, or shared state.
- Concepts
  - [Custom domain architecture concepts](/docs/concepts): Understand the domain lifecycle, DNS records, ownership verification, managed TLS, provider capabilities, status, errors, and tenant security.
  - [Domain lifecycle](/docs/concepts/domain-lifecycle): Move a hostname from user input to provider-authoritative activation.
  - [Platform providers](/docs/concepts/platform-providers): Understand what adapters normalize and what remains provider-specific.
  - [DNS records](/docs/concepts/dns-records): Render exact normalized routing, ownership, and certificate instructions.
  - [Ownership verification](/docs/concepts/ownership-verification): Prove a customer controls a hostname without collecting registrar credentials.
  - [Managed certificates](/docs/concepts/managed-certificates): Track provider-managed TLS issuance separately from DNS and ownership.
  - [Status model](/docs/concepts/status-model): Use overall, verification, certificate, and DNS-record states without false precision.
  - [Error handling](/docs/concepts/error-handling): Handle normalized provider failures without leaking secrets.
  - [Provider capabilities](/docs/concepts/provider-capabilities): Detect optional list, verification, certificate, apex, and wildcard behavior.
  - [Security model](/docs/concepts/security-model): Keep provider credentials server-side and tenant ownership in your application.
- API Reference
  - [Domain SDK TypeScript API reference](/docs/api-reference): Reference the typed clients, provider contract, domain model, DNS records, lifecycle status, errors, polling, and isolated testing utilities.
  - [createDomainClient](/docs/api-reference/create-domain-client): Create a stateless client from a provider and optional silent-by-default logger.
  - [createSubdomainClient](/docs/api-reference/create-subdomain-client): Scope tenant hostname operations to direct children of one owned parent domain.
  - [DomainClient](/docs/api-reference/domain-client): Reference for normalized custom-domain lifecycle methods.
  - [DomainProvider](/docs/api-reference/domain-provider): Implement the adapter contract for a platform provider.
  - [Domain](/docs/api-reference/domain): Provider-independent state returned by every lifecycle read.
  - [DnsRecord](/docs/api-reference/dns-record): Exact DNS instruction normalized for a SaaS settings UI.
  - [DomainStatus](/docs/api-reference/domain-status): Exhaustive overall lifecycle status union.
  - [DomainSdkError](/docs/api-reference/domain-sdk-error): Structured, sanitized failures shared by the core and provider adapters.
  - [waitUntilActive](/docs/api-reference/wait-until-active): Sequential polling with timeout, cancellation, callback, and retry backoff.
  - [Testing utilities](/docs/api-reference/testing-utilities): Reference for the isolated testing-only subpath.
- Project
  - [Domain SDK project](/docs/project): Follow Domain SDK releases, inspect the open-source project, and learn how to contribute provider adapters, fixes, documentation, or tests.
  - [Contributing](/docs/project/contributing): Set up the workspace, make a focused change, and run the repository checks.
  - [Changelog](/docs/project/changelog): User-visible Domain SDK releases and compatibility changes.