Porkbun DNS records: the TypeScript adapter
Write Porkbun DNS records (A, AAAA, CNAME, ALIAS, TXT, CAA) from TypeScript: API keys, per-domain API Access, nameserver checks, TTLs from 600 seconds, and errors.
The Porkbun API can write DNS records for a domain in your account once you create an API key pair and turn on API Access for that domain. The records only take effect while the domain uses Porkbun's nameservers: Porkbun keeps a zone even when a domain is delegated elsewhere, so a write there succeeds and public DNS doesn't change. The porkbun adapter checks delegation with getZone(), reads records with /dns/retrieve, creates them with /dns/create, and deletes only the record IDs it selected.
Credentials and scope
Create an API key and secret API key in Porkbun's account API settings. Enable API Access for each domain you want to manage. Store both keys in server-only configuration as PORKBUN_API_KEY and PORKBUN_SECRET_API_KEY. For a walkthrough of the Porkbun API itself, with raw fetch calls next to the adapter, see Porkbun API: create DNS records from TypeScript. To compare Porkbun's API access and DNS automation with Namecheap's, see Namecheap vs Porkbun for developers. For domains whose DNS is on Spaceship's basic nameservers, use the Spaceship adapter.
The adapter writes DNS records, not hosting-provider domains or certificates. A Porkbun DNS zone must already exist for the domain.
Apply a hosting provider's records
Use a hosting provider to add the domain, then pass its result to applyDomainRecords(). This example uses Vercel:
import { createDnsClient, createDomainClient } from "@opencoredev/domain-sdk";
import { porkbun } from "@opencoredev/domain-sdk/porkbun";
import { vercel } from "@opencoredev/domain-sdk/vercel";
const domains = createDomainClient({
provider: vercel({
token: process.env.VERCEL_TOKEN!,
projectId: process.env.VERCEL_PROJECT_ID!,
}),
});
const dns = createDnsClient({
provider: porkbun({
apiKey: process.env.PORKBUN_API_KEY!,
secretApiKey: process.env.PORKBUN_SECRET_API_KEY!,
}),
});
const zone = await dns.getZone("customer.com");
if (!zone.authoritative) {
throw new Error("Delegate customer.com to Porkbun before applying records.");
}
const domain = await domains.add("app.customer.com");
await dns.applyDomainRecords(domain, { zone: "customer.com" });applyDomainRecords() writes required records by default and leaves unrelated records alone. Repeating the call does not create records already present. Conflicting routing records produce DOMAIN_CONFLICT; pass onConflict: "replace" only when you intend to delete those conflicting records. Use includeOptional: true to include optional records returned by the hosting provider.
Inspect await dns.listRecords("customer.com") to check the saved records. DNS propagation takes time; use the hosting provider's verification flow afterward to check routing and certificate readiness.
Supported records and limits
The adapter creates A, AAAA, CNAME, ALIAS, TXT, and CAA records. It does not create ANAME records. Apex names and wildcards are supported. CAA values use presentation format, such as 0 issue "letsencrypt.org".
The default TTL is 600 seconds. Set ttl on the adapter to change the default, or set it on an individual input record. The adapter accepts TTLs from 600 to 86400 seconds. Porkbun's usual minimum is 600 seconds, but account settings can impose a different minimum.
Record retrieval uses one request, not pagination. The adapter returns every record the API includes, even types it does not create, and deletes only selected record IDs. Porkbun's retrieve endpoint excludes SOA and default Porkbun NS records. If an apex NS record pointing at a Porkbun nameserver is returned, the adapter marks it non-editable.
The nameserver check uses /domain/getNs/{domain} and considers the zone authoritative only when every returned nameserver ends in .porkbun.com. It reports delegation, not an independent public DNS lookup.
Errors and testing
Invalid keys produce AUTHENTICATION_FAILED. Missing domain API access or insufficient permissions produce PERMISSION_DENIED with guidance to enable API Access. A missing domain produces DOMAIN_NOT_FOUND. Rate limits and service outages are retryable; retryAfter is exposed when Porkbun supplies a Retry-After header.
Each create request carries a fresh Idempotency-Key. A DUPLICATE_RECORD response with HTTP 400 is accepted as a successful create. The adapter does not automatically retry requests.
Sandbox API keys beginning with pk1_sb_ use the same endpoint. For tests, pass a custom fetch implementation or override baseUrl. Do not send production credentials to an untrusted endpoint.
bunny.net custom domains
Add, verify, monitor, and remove customer hostnames on a bunny.net CDN pull zone with a typed server-side TypeScript adapter.
Namecheap DNS records: BasicDNS API adapter
Set Namecheap DNS records (A, AAAA, CNAME, ALIAS, TXT, CAA) from TypeScript: why the API needs BasicDNS, IP whitelisting, whole-list setHosts writes, and limits.
