Vercel Framework Migration: Static to Next.js
Summary
This process documents the reconfiguration of a Vercel project that was initially deployed as a static site but required a transition to the Next.js framework. The migration involved updating the framework preset in the Vercel dashboard and clearing deployment overrides to ensure consistent builds via GitHub integration.
Details
During the development of the Sokrates web components, a project was initially provisioned on Vercel using the “Other” framework preset, which treats the repository as a collection of static assets. As the project evolved into a full Next.js application, this configuration caused deployment failures; specifically, the Vercel edge network would report a “Ready” status for the deployment, but the application would return 404 errors because the build output was not being correctly routed or generated for a React-based SSR/ISR environment.
Configuration Correction
The primary fix required navigating to the Vercel Project Settings and changing the Framework Preset from “Other” to Next.js. This change is critical because it instructs Vercel’s build pipeline to automatically detect the next.config.js file, install the appropriate dependencies, and use the next build command rather than simply serving the root directory.
Deployment and Overrides
To apply these changes, a manual deployment was triggered using the --force flag via the Vercel CLI. This served to verify that the project-level settings were correctly interpreted by the build engine.
A key step in this process was the removal of “production deployment overrides.” In Vercel, manual CLI deployments can sometimes create overrides that bypass the standard project settings or GitHub integration logic. To ensure long-term maintainability, the environment was cleaned so that the project-level framework setting (Next.js) would be the authoritative source of truth.
Final State
The migration concluded with a clean deployment triggered by a Git push through the GitHub integration. This confirmed that:
- The framework is correctly identified as Next.js at the project level.
- No manual overrides are interfering with the automated CI/CD pipeline.
- The build output correctly maps to the Next.js routing structure, resolving the previous 404 issues.