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
The admitted versions are Next.js15.5.26 and newer patches in 15.5.x, or 16.3.6–16.3.7. The verified fixtures use 15.5.26 and 16.3.7; other admitted versions are experimental. A ^ or ~ declaration is experimental, and its base and frozen installed version must be inside the admitted window. 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.7 and adds --webpack for Next.js 16; Next.js 15 uses its normal build without that flag. Next.js 16 also accepts next build --webpack. Use one default-exported next.config.js, .mjs or .ts; do not set output: standalone, output: export, cacheComponents: true or a non-root basePath or assetPrefix.
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, on-demand revalidation and Cache Components are unsupported; keep existing static pages when addressing a packaging error. The private cache defaults to 32 MiB. With CLI/MCP 0.1.28 or later, addbuild.ssg_cache_max_mib to ohmyhost.yaml to select an integer from 1 to 64. Keep your existing build settings, for example:
- 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.
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, notNEXT_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 inlinestyle 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:
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:
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 witheval 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.