subdomain.to for Next.js

@subdomainto/nextjs provides server-only helpers for adding customer custom domains to Next.js SaaS applications. It creates the typed subdomain.to API client from environment variables and verifies signed webhooks in Route Handlers.

Installation

npm install @subdomainto/nextjs

Next.js 14 through 16 are supported. Never import this package into a Client Component or expose its environment variables through browser code.

Create the API client

import { createSubdomainToClient } from '@subdomainto/nextjs';

const client = createSubdomainToClient();
const domain = await client.domains.create(
  'portal.customer.com',
  'customer-42-domain',
);

The helper reads SUBDOMAINTO_API_KEY and optional SUBDOMAINTO_BASE_URL. The returned client exposes destinations, domains, DNS and TLS lifecycle status, webhooks, widget sessions, and usage.

Verify a Route Handler webhook

import { verifyWebhookRequest } from '@subdomainto/nextjs';

export async function POST(request: Request) {
  const event = await verifyWebhookRequest(request);
  console.log(event.event, event.data);

  return new Response(null, { status: 204 });
}

verifyWebhookRequest() reads the untouched body, SubdomainTo-Signature, and SUBDOMAINTO_WEBHOOK_SECRET. It rejects invalid signatures, stale timestamps, and malformed payloads before returning a typed event.

Documentation

Read the Next.js SDK guide, browse the custom domains API documentation, or report an issue in the JavaScript SDK repository.

License

MIT