Vercel App Deployment
Relevant source files
The following files were used as context for generating this wiki page:
Nordcom Commerce is designed for multi-tenant deployment on the Vercel platform. A single Next.js deployment serves an arbitrary number of shops, resolving tenants at the edge by hostname before routing requests to tenant-scoped segments. This architecture leverages Vercel's infrastructure for edge-friendly caching, preview deployments, and automated domain management via the Vercel REST API.
Sources: README.md:14-22, apps/storefront/README.md:1-5, CONTEXT.md:1-4
Multi-Tenant Routing Architecture
The platform uses Next.js middleware to handle multi-tenancy. Requests arriving at Vercel are normalized to strip ports and preview suffixes. The middleware calls the data layer (Convex) to resolve the tenant based on the host header. Upon a successful match, the URL is rewritten to a /[domain]/[locale]/... path, which the App Router uses to provide the correct shop context.
The middleware distinguishes between administrative routes and public storefront routes. Paths prefixed with /admin are delegated to admin-specific middleware, while all others are treated as storefront requests.
Sources: README.md:118-126, apps/storefront/README.md:31-41, CONTEXT.md:280-285
Domain Management via Vercel API
The Admin application integrates directly with the Vercel REST API to manage custom domains for storefronts. This allows operators to add project domains and verify their status programmatically.
Domain Operations
The system performs idempotent domain additions. If a domain addition fails because it already exists on the project, the system verifies this with a secondary GET request to treat the operation as successful.
| Function | Vercel API Endpoint | Description |
|---|---|---|
addProjectDomain | POST /v10/projects/:id/domains | Adds a custom domain to the Vercel project. |
getProjectDomainStatus | GET /v9/projects/:id/domains/:domain | Checks if Vercel has verified ownership. |
getProjectDomainStatus | GET /v6/domains/:domain/config | Checks for DNS misconfigurations. |
Sources: apps/admin/src/lib/domains/vercel.ts:25-50, apps/admin/src/lib/domains/vercel.ts:60-84
Domain Verification Flow
Domain verification proves platform connectivity rather than per-shop ownership. The admin dashboard renders a domain as "connected" only when it is both verified by Vercel and has no DNS misconfigurations.
Deployment Environment Configuration
Vercel deployments distinguish between production and preview environments using VERCEL_ENV. This is critical for gating behavior, such as suppressing live-chat launchers or certain observability tools on non-production hosts.
Build and Asset Optimization
The next.config.js for the applications includes specific Vercel optimizations:
- Asset Prefix: Uses
VERCEL_PROJECT_PRODUCTION_URLto set the base URL for assets in Vercel environments. - Image Optimization: Configures remote patterns for Unsplash, Shopify, and Gravatar, alongside the
SERVICE_DOMAINandADMIN_DOMAIN. - Trailing Slashes: Enabled (
trailingSlash: true) withskipTrailingSlashRedirectto allow the edge to handle redirects.
Sources: apps/landing/next.config.js:31-44, apps/landing/next.config.js:52-61, CLAUDE.md:131-137
Environment Variables
Key variables required for Vercel deployment include:
| Variable | Source/Usage |
|---|---|
VERCEL_ENV | Used by @nordcom/commerce-utils to determine environment tier. |
VERCEL_URL | The unique URL for the deployment. |
LANDING_DOMAIN | Canonical hostname for marketing and documentation. |
ADMIN_DOMAIN | Hostname for the operator dashboard. |
SERVICE_DOMAIN | Fallback hostname for unknown-shop rewrites. |
Sources: apps/landing/README.md:38-40, apps/admin/README.md:35-43, CLAUDE.md:131-137
Observability and Tooling
Vercel-specific observability tools are integrated into the applications to monitor performance and provide developer utilities.
- Vercel Toolbar: Enabled for storefront, admin, and landing apps to provide in-browser deployment controls.
- Vercel Analytics & Speed Insights: Integrated into the storefront for real-time performance monitoring.
- OpenTelemetry: Bootstrapped via
instrumentation.tsin each application for distributed tracing.
Sources: apps/landing/README.md:15, apps/admin/README.md:17, apps/storefront/README.md:14
Conclusion
Vercel App Deployment in Nordcom Commerce is a deeply integrated system that goes beyond simple hosting. It automates the complex relationship between multi-tenant hostnames, Vercel project domains, and edge-based routing, ensuring that adding a new tenant is a data-level operation that does not require a redeploy.