with one click
nextjs-vercel-public-trace-size-debugging
// Diagnose and fix Vercel Preview/Deploy failures caused by Next.js output file tracing pulling oversized public assets into API/server function bundles.
// Diagnose and fix Vercel Preview/Deploy failures caused by Next.js output file tracing pulling oversized public assets into API/server function bundles.
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | nextjs-vercel-public-trace-size-debugging |
| description | Diagnose and fix Vercel Preview/Deploy failures caused by Next.js output file tracing pulling oversized public assets into API/server function bundles. |
Use this when a Next.js app deploys locally but Vercel Preview/Deploy fails with function size / bundle size / traced files issues after adding or moving large files under public/.
Typical signs:
npm run build passes.public/ (images, docs, generated assets, route-aligned asset trees, etc.).process.cwd()/public or similar generic public-root paths.In Next.js on Vercel, server/API output tracing can conservatively include files reachable from filesystem access patterns. If a route touches process.cwd()/public generically, Vercel may bundle large unrelated assets from public/, causing function size failures.
The fix is usually not to remove the assets. Instead:
public filesystem access in that function,Confirm the failing check.
gh pr checks <PR_NUMBER>gh pr view <PR_NUMBER> --json statusCheckRollupInspect Vercel deploy logs.
npx vercel inspect <DEPLOYMENT_ID> --logsFind routes that access public too broadly.
process.cwd()path.join(..., "public")publicDirsearch_files(pattern='publicDir|process\\.cwd\\(|/public|join\\([^\\n]*public|path\\.join\\([^\\n]*public', target='content', path='src', file_glob='*.{ts,tsx}')Narrow filesystem access to explicit roots.
const publicDir = path.join(process.cwd(), "public")path.join(publicDir, relativeSrc)path.join(process.cwd(), "public", "documentation")path.join(process.cwd(), "public", "demo")const ALLOWED_ROOTS = { documentation: ..., demo: ... } as constpublic/.For upload/delete routes, use an explicit directory map.
const UPLOAD_DIR_PATHS = { uploads: ..., news: ..., documentation: ..., demo: ... } as consttype UploadDirName = keyof typeof UPLOAD_DIR_PATHSresolveUploadDirName(...).UPLOAD_DIR_PATHS[dirName] instead of recomputing path.join(process.cwd(), "public", dirName).Add or update tests.
Re-run local verification.
npm run test:run ...npm run typechecknpm run buildInspect local trace artifacts after build.
.next/server/app/**/route.js.nft.json for the affected routes.Commit, push, and re-check CI.
gh pr checks <PR_NUMBER>public/path/solutions/** can break Vercel Preview deploys even when local build passes.process.cwd()/public access, not from the assets themselves.src/app/api/downloads/file/route.tssrc/app/api/admin/uploads/route.tsA similar Vercel function-size failure can happen even when the traced files are not under public/.
Observed pattern:
fs.readFile(...)process.cwd()npm run build may passt/eula with logs pointing at the server component import traceIn the legal preview case, all of these steps happened:
src/content/legal-preview/*.mdxfs.readFile(...)src/lib/legal-preview-mdx.tsxReusable fix pattern:
fs.readFile if the content can be bundled staticallysrc/content/legal-preview/sources.tsExample shape:
await fs.readFile(path.join(process.cwd(), 'src', 'content', 'legal-preview', 'eula.mdx'), 'utf8')import { legalPreviewSources } from '@/content/legal-preview/sources'const source = legalPreviewSources.eulaWhy this helps:
Checklist when using this fix:
src/content/** if humans still need themsources.ts module that exports the exact content strings used at runtimefs/pathbuildnext build may pass while Vercel Preview still fails; do not assume local build is sufficient.vercel build may be unavailable in a worktree if project settings are not pulled locally; in that case rely on CI + vercel inspect.Use this when the user wants deployment/infra scope isolated from content or feature work.
Recommended sequence:
origin/main for the tracing fix only.This prevents reviewer confusion and matches the user's expectation that CMS/API infrastructure changes be reviewed independently from public-content migration work.
typecheck passes.build passes.