Deploy Next.js to Vercel with a Custom Domain

Who this is for

This guide is for developers who have a working Next.js application in GitHub and want a repeatable Vercel deployment on a domain registered elsewhere. It assumes you can edit the domain's DNS records.

What you will solve

You will connect GitHub to Vercel, validate the deployment before touching DNS, configure the apex and www hostnames, and verify that HTTPS, redirects, and application routes work as one production system.

Understand the delivery path

The production path has four owners: GitHub stores the source, Vercel builds and serves the application, your registrar hosts DNS, and browsers verify the TLS certificate. Debugging is faster when you identify which owner is failing.

Prerequisites

• A Next.js project that passes its local production build.
• A GitHub repository with the deployable branch pushed.
• A Vercel account authorized to read that repository.
• Access to the DNS control panel for the domain.

Use the package manager represented by the repository lockfile. This project uses pnpm, so its baseline is:

pnpm install --frozen-lockfile
pnpm lint
pnpm build

Import the repository into Vercel

1. In the Vercel dashboard, choose Add New → Project.
2. Import the GitHub repository.
3. Confirm that Vercel detects Next.js and the correct root directory.
4. Add only environment variables the application actually reads.
5. Deploy and inspect the build log.

Do not configure a manual output directory for a standard Next.js deployment unless the repository explicitly uses a static export or custom build layout.

Validate the Vercel URL first

Open the generated vercel.app URL before changing DNS. Test the homepage, the technical writing index, individual articles, and server routes such as the CV PDF. This isolates application failures from domain failures.

Add the custom domain

In Project Settings → Domains, add both the apex domain and its www variant. Choose one canonical hostname and redirect the other. This site uses antonioibarra.dev as canonical.

Vercel will display the exact DNS values required for each hostname. Copy those values rather than relying on screenshots or old tutorials, because platform recommendations can change.

Configure DNS without breaking email

At the registrar, change only the web records required for the apex and www hosts. Preserve MX, SPF, DKIM, and DMARC records; they belong to email delivery and are unrelated to the website deployment.

• Remove conflicting parking, forwarding, A, AAAA, ALIAS, or CNAME records for the same host.
• Create the records Vercel shows.
• Keep the TTL at the provider default unless you have an operational reason to change it.
• Return to Vercel and wait for domain verification.

Verify HTTPS and canonical redirects

Once DNS resolves, test all four entry points: HTTP and HTTPS for both the apex and www host. Every request should end on one HTTPS canonical URL without a redirect loop.

curl -I http://example.com
curl -I https://example.com
curl -I https://www.example.com

Make deployments repeatable

After the Git integration is active, a push to the production branch should trigger a production deployment. Pull requests should produce preview deployments. Treat preview URLs as release candidates: verify routes and content there before merging.

Common mistakes

• Changing DNS before validating the preview: this combines application and DNS failures into one incident.
• Deleting mail records: cleaning up web records must not remove MX or email-authentication records.
• Assuming a push guarantees production: confirm that the repository and production branch are connected in Vercel.
• Maintaining two canonical hosts: redirect one hostname and use the other consistently in metadata and sitemaps.
• Ignoring server routes: a homepage can work while PDF generation or route handlers fail.

Production checklist

• The install, lint, and production build pass locally.
• The Vercel preview works before DNS changes.
• Every important route returns the expected content.
• The apex and www hosts converge on one HTTPS URL.
• The canonical metadata uses that same hostname.
• Email DNS records remain intact.
• A new production-branch commit triggers a deployment.

Primary documentation

• Vercel: add a custom domain
• Next.js deployment documentation
• GitHub repository documentation