Vercel
Vercel is supported for the Next.js UI app only. Deploy apps/ui to Vercel and run Strapi somewhere else, such as Heroku or Strapi Cloud.
Do not deploy apps/strapi to Vercel. Strapi needs a long-running Node.js server, persistent database access, writable/runtime storage decisions, and admin/API behavior that does not fit Vercel's serverless frontend deployment model for this starter.
App Layout
| App | Vercel support | Notes |
|---|---|---|
apps/ui | Yes | Next.js App Router frontend. |
apps/strapi | No | Host Strapi separately and point the UI to it with STRAPI_URL. |
apps/docs | Optional | Usually deployed through GitHub Pages in this starter. |
Create The Vercel Project
Create a new Vercel project from the repository and configure it for the UI workspace:
| Setting | Value |
|---|---|
| Framework preset | Next.js |
| Root directory | apps/ui |
| Install command | pnpm install --frozen-lockfile |
| Build command | pnpm build |
| Output directory | Leave default for Next.js |
Even though the Vercel project root directory is apps/ui, Vercel still detects the repository and lockfile. Keep pnpm-lock.yaml committed at the monorepo root.
Environment Variables
Configure required UI environment variables in Vercel Project Settings. Start from apps/ui/.env.local.example and the UI Environment Variables reference.
Minimum production-like setup:
| Variable | Purpose |
|---|---|
APP_PUBLIC_URL | Public URL of the Vercel UI app. |
STRAPI_URL | Server-reachable URL of the separately hosted Strapi app. |
STRAPI_REST_READONLY_API_KEY | Read-only Strapi API token for public content reads. |
STRAPI_REST_CUSTOM_API_KEY | Required only when browser-safe proxy writes are used. |
BETTER_AUTH_SECRET | Required when end-user auth is enabled. |
STRAPI_PREVIEW_SECRET | Required when Strapi preview is enabled. Must match Strapi. |
APP_ENV | Deployment label such as testing or production. |
Strapi URL
STRAPI_URL must point to the backend that Vercel can reach from server-side code. For example:
STRAPI_URL=https://your-strapi-app.herokuapp.com
The browser should not need direct access to private Strapi tokens. Client-side requests that need Strapi data should use the UI proxy routes documented in the UI section.
If you use Strapi preview, password reset links, OAuth callbacks, or emails generated by Strapi, configure the matching frontend URL on the Strapi side as well. For Strapi this is usually CLIENT_URL.
Next.js Output Mode
Do not set NEXT_OUTPUT=standalone for Vercel. Vercel handles the Next.js build and runtime packaging.
For most Vercel deployments, leave NEXT_OUTPUT unset. Use NEXT_OUTPUT=export only when the project intentionally deploys a fully static export and accepts the tradeoffs documented in Caching.
Deployment Flow
- Deploy Strapi to a supported backend host.
- Configure Strapi database, upload provider, CORS, preview, auth providers, and
CLIENT_URL. - Create the Vercel project for
apps/ui. - Add UI environment variables in Vercel.
- Deploy the Vercel project.
- Verify that server-side UI requests can reach
STRAPI_URL. - Run the QA workflow against the Vercel deployment URL.