Skip to main content
Run ohmyhost init --dry-run --json in the Next.js project. Keep an exact package-manager version and one matching lockfile; resolve the concrete inspection output before planning a deployment.

​
Supported versions and build

Next.js requires stable 16.4.1 or later. Every Next.js 15 release, Next.js 16.4.0 and older, and prereleases are refused. The security floor is enforced on new plans and builds in Dev and Prod; existing deployments need a rebuild to adopt an updated application dependency. The version resolved by the committed package-lock.json or pnpm-lock.yaml decides; otherwise the exact version or ^/~ range in package.json does, and a range spanning the floor stays pending until the build checks the installed version. There is no upper version bound in that security check, but a newer release must still build: OpenNext refuses a Next.js major it does not support yet. Pin exact react and react-dom versions and commit the matching package-manager lockfile. Keep scripts.build as next build. The service supplies OpenNext 1.20.9 and adds --webpack; next build --webpack is also accepted. A committed open-next.config.ts is ignored because the service writes its own OpenNext configuration. Use one default-exported next.config.js, .mjs or .ts; do not set output: standalone, output: export or a non-root basePath or assetPrefix. The Webpack build ignores Turbopack rules. create-next-app 16.4 with Tailwind CSS, its --yes default, loads Tailwind only through the Turbopack rule @tailwindcss/turbopack, so planning refuses it as next_tailwind_turbopack_only until the application root has a PostCSS configuration that Webpack reads. Add postcss.config.mjs with export default { plugins: { "@tailwindcss/postcss": {} } }, remove the Turbopack rule, and use the package manager to add @tailwindcss/postcss at the same version as tailwindcss and remove @tailwindcss/turbopack, so the lockfile records both. An app created with --no-tailwind needs no change. The service-owned Next.js bundle uses keep_names: false to prevent injected name helpers from breaking browser scripts serialized by libraries. This setting is supplied by the platform; no customer Wrangler override is needed.

​
Build-time static pages and cache limits

Pages and route responses prerendered during the build use an immutable cache carried with that deployment. Ordinary request-time rendering and route handlers remain available. A new deployment refreshes the cache. Time-based ISR and on-demand revalidation are unsupported; keep existing static pages when addressing a packaging error.

​
Cache Components

Next.js 16 Cache Components (cacheComponents: true, also with partialPrefetching: true, the create-next-app 16.4 default) build and run. A page’s prerendered static shell comes from the deployment’s cache and its Suspense holes render for each request. "use cache" and the next/cache functions cacheLife, cacheTag, io, navigation, prefetch, refresh and unstable_noStore (imported or re-exported by name) are admitted.
  • The cache is read-only: request-time "use cache" values are never stored, so a later request computes them again. A cached function must depend on request data only through its arguments.
  • A "use cache" value in a static shell would stay frozen until the next deployment, and every built-in cacheLife profile revalidates. The build refuses it unless it uses cacheLife({ revalidate: Infinity, expire: Infinity }); otherwise call the cached function inside a Suspense boundary after reading request data, for example await connection().
  • revalidateTag, revalidatePath, updateTag, unstable_expireTag, unstable_expirePath, unstable_cache and other next/cache uses stay refused.
  • Each dynamic page needs a static shell: read params inside a Suspense boundary, without ensureStatic and without a root layout inside a dynamic segment. With partialPrefetching: true, dynamic pages must not use generateStaticParams.
A refused build ends with one ohmyho.st packaging: line that names the fix; apply it, then deploy the new commit. The private cache defaults to 32 MiB. With CLI/MCP 0.1.28 or later, add build.ssg_cache_max_mib to ohmyhost.yaml to select an integer from 1 to 64. Keep your existing build settings, for example:
Use your repository’s package manager and commands. Save the change as a managed version, or commit and push it for a GitHub source, then plan and deploy that exact saved commit. Sources and versions.
  • Ordinary public assets retain their separate 25 MiB allowance.
  • Each public asset or cache file is at most 10 MiB; the combined asset inventory has at most 1,000 files.
  • The complete deployment archive is at most 30 MiB compressed and 64 MiB expanded, including cache, public files, Worker modules, migrations and archive metadata.
Selecting 64 MiB of cache capacity leaves those combined limits in place. Leave space for the rest of the deployment. Increase this setting only when the error names the private cache limit; an expanded-archive or public-asset error requires reducing that output. Cache storage costs 0 credits per 100 MB-month: its provider storage cost is zero, so cost plus 50% remains zero. Unused capacity is not charged. Normal build and Worker request/CPU charges still apply, including when a cached page executes Worker code. Pricing The cache payloads are private. Direct requests to their reserved paths must return 404; the application serves the rendered pages through their normal URLs.

​
Keep the app portable

Use ordinary Next.js routes and configuration. The hosting service supplies its build adapter; do not create a customer Wrangler project merely to make deployment work. Private auth credentials and database access belong in the server runtime, not NEXT_PUBLIC_ values. Keep existing authentication unless you choose to replace it. Configure exact callback and logout URLs for the environment you are testing. Application authentication · Runtime secrets. Hosted server code reads private bindings through getCloudflareContext({ async: true }).env. A localhost-only runtime factory is a test adapter, not a production backend. Preserve ordinary route handlers and use the application database client and private file client from that context. For a library that uses WebAssembly, prefer a runtime-specific package export: a workerd entry can statically import the pinned .wasm modules, while a separate Node entry loads the same bytes locally. Preserve the library’s license and real validation. The shared build pipeline carries validated Workers-compatible JavaScript, MJS and WASM modules for Next.js, TanStack Start edge, Vite edge companions and plain functions Workers. Auxiliary modules are at most 5 MiB each; the Worker and artifact budgets still apply. The immutable artifact keeps those modules together; a successful Node build alone does not prove the Worker module can start. Scheduled work is declared as functions.crons and runs scheduled from the default export of src/ohmyhost/worker.ts, a module the platform bundles outside the Next.js build; see Functions and cron. Next.js SSR receives a fresh nonce on every rendered script/style tag; style attributes, event handlers and later client-created unnonced tags remain blocked. External connections/resources/frames/workers need explicit browser declarations; media/microphone needs the server HTML opt-in.

​
Images and themes under CSP

A nonce permits a script or style tag; it does not permit an inline style attribute. If an already unoptimized next/image component emits blocked inline styles, use a native image with the same URL, dimensions, classes and alternative text. Keep its loading behavior and put styling in the stylesheet:
For an image that previously had priority loading, preserve that with loading="eager" and fetchPriority="high" instead of lazy loading. Libraries that insert styles after hydration must use the trusted response nonce from meta[property="csp-nonce"]. For next-themes 0.4.6, read it before the provider’s first client effect:
Keep the app’s system-theme, transition and native color-scheme settings. Waiting until an effect to supply the nonce can miss the library’s first inserted style. Verify the initial theme, Light/Dark/System changes, client navigation and reloads without CSP or hydration errors. Keep the CSP strict; these adaptations require no unsafe-inline allowance.

​
Files read by server code

The platform includes non-executable files recorded in Next.js output-file traces (.nft.json) as read-only data modules in the Worker. Use ordinary Node filesystem reads for those deployed files and keep them inside the application root. When Next cannot infer a dynamic filename, declare the required files with its normal outputFileTracingIncludes configuration. Missing or invalid traced files fail packaging, and data modules count toward the Worker size limits. These runtime files receive no public URL from this mechanism. Files intentionally placed in public/ still follow Next.js public-asset behavior. Do not bundle secrets as content; use runtime secrets. Runtime filesystem writes do not persist application data: use files or the database.

​
Compile MDX during the build

Workers does not support runtime code generation with eval or new Function. An MDX library that evaluates compiled strings at request time therefore needs a build-time integration, even if the same code works under local Node.js. Compile MDX with @mdx-js/mdx using outputFormat: "program", write ordinary ES modules and import them through a static component registry. Invoke the deterministic generator from the Next configuration so the build script stays next build. Keep the source JSON or MDX as the canonical content and preserve the application’s component mapping, GFM plugins, links and embedded markup. Routes render the generated components without a runtime evaluator. The generator must also work in a fresh checkout.

​
Verify after deployment

Check the landing page and every content route, including direct reloads, unknown URLs, images, feeds and sitemap where present. Check server behavior, application login and a real data operation where used, then inspect the browser for hydration or content-security errors and missing content. An admitted or successful build does not prove every Next.js feature. The inspection response distinguishes verified, experimental and unsupported capabilities. Use the portable-app Skill for required source changes, then follow your first deployment.