Migration from v9 to v10
Dinou v10 is a landmark major release introducing End-to-End Type-Safe Routing with zero-boilerplate "./dinou" contextual modules, full .env* & DINOU_PUBLIC_* isolation, unified tsconfig.json path aliases, AOT dinou.config.ts & Netlify Functions v2 bundles, single-execution inline RSC streaming, and transactional dinou uneject — alongside targeted breaking changes to tighten security, routing determinism, and deployment isolation.
1. Overview & Quick Upgrade
Most application code (Server Components, Client Components, Server Functions, page_functions.ts, and layout_functions.ts) works out of the box in Dinou v10. However, v10 introduces 7 targeted breaking changes affecting underscore-prefixed helper folders, PPR inheritance, cloud deployment directories, legacy favicons/, build-time plugin hooks, client environment variables, and strict route typing.
| Area | Dinou v9 (Previous) | Dinou v10 (Current) |
|---|---|---|
_folder Directories | Skipped URL routing but still scanned by bundlers, manifests, and Server Functions | Completely excluded (“parked/archived”); active imports fail at compile time (move helpers to clean folders like src/components) |
ppr Resolution | Inherited from parent layout_functions.ts down to child layouts and pages | Strictly per-segment (no parent-to-child inheritance), falling back to global dinou.config.ts |
| Cloudflare & Netlify Paths | Cloudflare used .dinou/dist3; manifests lived in root .dinou/* folders | Cloudflare: .dinou/cloudflare/assets; Netlify: .dinou/netlify/functions (AOT v2); manifests consolidated into .dinou/dist1 |
Static Files (favicons/) | Supported legacy root favicons/ alongside public/; root /manifest.json reserved | Unified public/ only (favicons/ removed); public/manifest.json freed for PWAs |
plugin.onRequest in SSG | Executed during build-time SSG pre-rendering | Skipped during build-time SSG (isSSG === true); runs on every runtime HTTP request |
Client process.env.* | Unprefixed variables could leak during SSR or throw in browser | Unprefixed vars strictly evaluate to undefined in "use client"; explicit DINOU_PUBLIC_* prefix inlined across all 3 bundlers |
| Routing Types & Legacy Deps | Untyped string URLs; dotenv & cross-env bundled transitively | Strict typed <Link> & useRouter() via dinou typegen; 7 obsolete deps removed (31 compiled vendors) |
1.1 Upgrading Dependencies & Running Typegen
Upgrade dinou to v10 (requires react and react-dom at 19.3.1 or higher), then generate route types:
npm install dinou@latest
npx dinou typegenpnpm add dinou@latest
pnpm exec dinou typegenbun add dinou@latest
bunx dinou typegenyarn add dinou@latest
yarn dinou typegenUpdate tsconfig.json to include generated route declarations and enable zero-boilerplate contextual "./dinou" imports:
{
"compilerOptions": {
"rootDirs": ["src", ".dinou/routes"],
"paths": {
"@/*": ["./src/*"]
}
},
"include": ["dinou-env.d.ts", ".dinou/types/**/*.d.ts", "src/**/*"]
}Make sure dinou-env.d.ts exists at your project root with /// <reference types="dinou/env" /> so static asset imports (including fonts and custom assetExtensions) are typed automatically.
2. Breaking Changes (v9 to v10)
Action Required Before Deploying v10
_folder imports, strict route types) surface immediately via npm run dev and npx tsc --noEmit, while runtime/deployment changes (PPR inheritance, wrangler.toml, netlify.toml, favicons/, and SSG onRequest) require manual verification.2.1 Underscore (_folder) Directories Are Now Fully Excluded
In v9, directories prefixed with an underscore inside src/ (such as src/_components/ or src/_plugins/) only opted out of URL routing while remaining visible to bundlers, manifests, and Server Functions.
In Dinou v10, any _-prefixed directory subtree inside src/ is treated as completely parked / archived: excluded from routing, bundlers, CSS extraction, VFS snapshots, dev watchers, route types, and Server Functions (returning 403 Forbidden access if invoked). Any active file in src/ importing from a _-prefixed folder now fails immediately at compile time with an actionable error.
In Dinou, any folder without a page.tsx is already ignored by the router — you never need a leading underscore for active components, utilities, or plugins. Note that _-prefixed files inside active directories (e.g., src/blog/_helper.ts) remain valid.
// Folders like src/_components, src/_lib, src/_plugins
import { Header } from "@/_components/header"; // ❌ Compile-time error in v10
import { clerkPlugin } from "@/_plugins/clerk"; // ❌ Compile-time error in v10
import { formatDate } from "./_utils/dates"; // ❌ Compile-time error in v10// Rename folders by removing the leading underscore:
// src/components/, src/lib/, src/plugins/, src/blog/utils/
import { Header } from "@/components/header"; // ✅ Clean & ignored by router (no page.tsx)
import { clerkPlugin } from "@/plugins/clerk"; // ✅ Works across dev, build & AOT config
import { formatDate } from "./utils/dates"; // ✅ Valid active helper folder
// Reserve _folders strictly for parked/disabled route trees or WIP drafts:
// src/_old-checkout/page.tsx // Completely ignored by router & bundlers2.2 Per-Segment ppr Resolution (No Parent-to-Child Inheritance)
In v9, exporting export const ppr = true; in a parent layout_functions.ts cascaded automatically to nested layouts and child pages.
In Dinou v10, parent-to-child ppr inheritance has been removed so mixed-PPR hierarchies behave predictably without false-positive holes or hidden bailouts. Every layout_functions.ts and page_functions.ts resolves its own ppr flag independently, falling back directly to the global default in dinou.config.ts (ppr: false by default).
// dinou.config.ts — enables PPR across all layouts & pages by default
import { defineConfig } from "dinou";
export default defineConfig({
ppr: true,
});
// Opt out individual segments when needed:
// src/marketing/page_functions.ts
export const ppr = false;// src/dashboard/layout_functions.ts
export const ppr = true; // Applies ONLY to src/dashboard/layout.tsx
// src/dashboard/page_functions.ts
export const ppr = true; // Required explicitly if the child page also uses PPR2.3 Deployment & Build Output Directory Changes
Dinou v10 enforces strict physical isolation between public static assets, internal server manifests, and platform-specific build outputs:
- Cloudflare Workers (
wrangler.toml): Static assets and isolated internal cache files (__dinou_dist2, blocked with404externally) now emit to.dinou/cloudflare/assetsinstead of.dinou/dist3. - Netlify Functions v2 (
netlify.toml): Dedicated single-file AOT bundles now emit to.dinou/netlify/functions/ssr.mjs(build:netlify). Only.dinou/dist2/**needs to be listed inincluded_files— no more bundlingnode_modules/**orsrc/**. (Legacy.dinou/dist1/serverentries are also available.) - Internal Manifests & Docker:
.dinou/react_client_manifestand.dinou/server_functions_manifesthave been removed, andmanifest.jsonmoved out of.dinou/dist3into.dinou/dist1. Ensure non-root Node Dockerfiles copy.dinou/dist2with--chown=node:nodeso runtime ISR writes succeed.
name = "my-dinou-app"
main = ".dinou/cloudflare/worker.js"
compatibility_date = "2026-01-01"
compatibility_flags = ["nodejs_compat"]
[assets]
# Updated in v10 (was ".dinou/dist3" in v9)
directory = ".dinou/cloudflare/assets"
binding = "ASSETS"
run_worker_first = true
html_handling = "none"[build]
command = "npm run build:netlify"
publish = ".dinou/dist3"
[functions]
# Dedicated single-file AOT bundle in v10
directory = ".dinou/netlify/functions"
included_files = [".dinou/dist2/**"]# Copy only runtime artifacts (no .dinou/react_client_manifest in v10)
COPY /app/.dinou/dist1 ./.dinou/dist1
COPY /app/.dinou/dist3 ./.dinou/dist3
COPY /app/.dinou/node ./.dinou/node
# Ensure non-root USER node can write ISR/ISG updates into .dinou/dist2
COPY /app/.dinou/dist2 ./.dinou/dist22.4 Removed Legacy favicons/ Directory (Unified public/)
Dinou v10 removes legacy copying and watching of the root favicons/ directory, standardizing exclusively on public/ for all unhashed static assets (icons, robots.txt, sitemap.xml, manifest.json, and .well-known/*).
# Move any remaining files from favicons/ into public/
mkdir -p public
mv favicons/* public/
rmdir faviconsMoving Dinou's internal bundler chunk manifest to .dinou/dist1/manifest.json also frees /manifest.json at your domain root for standard Progressive Web Apps (public/manifest.json). See Public Directory.
2.5 plugin.onRequest No Longer Runs During Build-Time SSG
In v9, plugin.onRequest and plugin.onRequestContext executed during build-time static site generation (npm run build), which could accidentally trigger authentication redirects, rate limiters, or request logging while pre-rendering static pages.
In Dinou v10, onRequest is skipped during SSG (platformContext.isSSG === true) and runs exclusively on live runtime HTTP requests (ahead of both dynamic routes and cached SSG/ISR/PPR responses). If a statically pre-rendered Server Component reads custom data normally injected by a plugin (such as an i18n translator), add a safe fallback derived from getContext().req?.path (which is populated during SSG without triggering dynamic bailout):
// Example: SSG-safe fallback when onRequest is skipped at build time
import { getContext } from "dinou";
export function getServerLocale(): "en" | "es" {
const ctx = getContext();
if (ctx.locale) return ctx.locale; // Set by plugin.onRequest at runtime
// Fallback for build-time SSG using ctx.req.path (does NOT cause dynamic bailout)
return ctx.req?.path?.startsWith("/es") ? "es" : "en";
}2.6 Strict Client Env Isolation (DINOU_PUBLIC_*)
Inside "use client" components, any unprefixed process.env.* reference now strictly evaluates to undefined during both SSR/SSG and browser execution across Esbuild, Rollup, and Webpack — preventing accidental secret leaks into HTML and browser ReferenceError: process is not defined crashes.
If a Client Component needs a build-time public value (such as an analytics ID or public API origin), prefix it with DINOU_PUBLIC_. For runtime-configured values across Edge/Serverless runtimes, read getContext().env in a Server Component and pass it down as props. See Environment Variables.
"use client";
export function Analytics() {
// ❌ Always undefined in Client Components in v10
const apiUrl = process.env.API_URL;
return <div data-api={apiUrl} />;
}"use client";
export function Analytics() {
// ✅ Safely inlined at build time across Esbuild, Rollup, and Webpack
const apiUrl = process.env.DINOU_PUBLIC_API_URL;
return <div data-api={apiUrl} />;
}2.7 Strict Route Types & Removed Legacy Dependencies
- Compile-time validated
<Link>&useRouter(): Passing an arbitrarystringvariable to<Link href={url}>,router.push(url), orrouter.replace(url)now produces a TypeScript error unless it matches a route in.dinou/types/routes.d.ts. Prefer typed route patterns withparams, or type dynamic external/callback targets asDinouLinkTarget. - Optional catch-all
[[...slug]]params: Received segmentparamsinPageProps,LayoutProps,PageFunctions, etc. are now strictly typed asstring[](matching Dinou's runtime[]array normalization on the base route), while staying optional in<Link params>andgetStaticPaths. - Removed transitive packages:
dotenv,cross-env,@esbuild-plugins/tsconfig-paths,rollup-plugin-tsconfig-paths,tsconfig-paths-webpack-plugin,esbuild-copy-static-files, androllup-plugin-copywere removed from Dinou's dependencies. Dinou now loads.env*files andtsconfig.jsonpath aliases natively; if your own custom scripts callcross-envdirectly, install it in your project'sdevDependencies.
import { useRouter, type DinouLinkTarget } from "dinou";
const router = useRouter();
// ✅ Preferred: compile-time checked pattern + params
router.push("/blog/[slug]", { params: { slug } });
// ✅ When bridging untyped strings from external libraries (e.g., auth SDKs):
router.push(callbackUrl as DinouLinkTarget);3. Major New Features in v10
Beyond the breaking changes above, Dinou v10 ships a comprehensive suite of developer experience, security, and runtime upgrades across all 3 bundlers and all 5 production runtimes:
"./dinou"npx dinou typegen generates .dinou/types/routes.d.ts and route-contextual .dinou/routes/<dir>/dinou.{js,d.ts} modules. Import Link, useRouter, ROUTE, PageProps, LayoutProps (with sibling @slot inference), and PageFunctions directly from "./dinou" with zero manual route strings.
.env* Hierarchy & tsconfig AliasesNative .env.{NODE_ENV}.local → .env.local → .env.{NODE_ENV} → .env loading with live hot-reload in dinou dev, unified getContext().env across all runtimes, auto-typed NodeJS.ProcessEnv, and full multi-alias tsconfig.json / jsconfig.json resolution (including extends, ${configDir}, CSS, and dinou.config.ts).
allowISG & assetExtensionsdinou.config.ts is now compiled ahead-of-time into every production bundle (zero runtime esbuild dependency) and live-reloads in dinou dev. Adds global allowISG, reactCompiler, assetExtensions (auto-generating ambient *.ext types), and normalized SPA-safe context.req.path (plus rawPath & isRscRequest).
Adds dinou build:netlify[:esbuild|:rollup|:webpack] emitting a self-contained Netlify Functions v2 bundle, standalone static export client-side <Link> SPA navigation (dinou export-static), universal RSC/SSR CSS Modules, CSS url(...) fingerprinting, font asset imports, and RFC 9110 206 Partial Content byte-range media streaming.
#418 StabilityEliminates double server execution on initial loads by streaming segmented Flight RSC payloads inline in the HTML response. Unlocks un-awaited Promise props for React 19 use(promise), progressive production <Suspense> streaming on dynamic SSR routes, PPR holes for useSearchParams(), multi-branch router backtracking, and hardened Redis / Cloudflare KV / Deno KV adapters.
dinou unejectEjecting is now reversible. npm run uneject (or node dinou/cli.js uneject [version]) restores package.json scripts, reinstalls dinou via your detected package manager with automatic rollback on failure, and removes ./dinou. dinou eject also selectively rewrites only existing scripts.
4. Upgrading Ejected Applications
If your v9 application was previously ejected (contains a local ./dinou directory):
- Back up any custom patches you made inside
./dinou(for example withgit diffagainst the original v9 snapshot). - Remove the local
./dinoudirectory, restore"dinou": "^10.0.0"inpackage.json(pointing scripts back fromnode dinou/cli.js ...todinou ...), and runnpm install. - Check whether you still need to eject — many v9 reasons to eject (custom
assetExtensions, globalreactCompiler/allowISG, Netlify Functions v2,tsconfig.jsonaliases, andDINOU_PUBLIC_*) are now built in. - If you still need local framework ownership, run
npx dinou ejectagain on v10 and re-apply your patches. Going forward in v10,npm run unejectmakes future upgrades transactional, andnpm run build:vendorscompiles the consolidated 31-package vendor catalog across multi-root package managers (including strictpnpm).
5. Verification Checklist
- Updated
"dinou": "^10.0.0"(andreact/react-dom>=19.3.1) inpackage.jsonand reinstalled dependencies. - Added
"rootDirs": ["src", ".dinou/routes"]and".dinou/types/**/*.d.ts"totsconfig.json, then rannpx dinou typegen. - Renamed any active
src/_*helper/component/plugin folders to clean names without a leading underscore (e.g.,src/components,src/plugins). - Verified
pprroutes: either enabledppr: trueindinou.config.tsor declaredexport const ppr = trueon each childpage_functions.ts/layout_functions.tsthat previously relied on parent inheritance. - Updated deployment manifests if applicable:
wrangler.toml(.dinou/cloudflare/assets),netlify.toml(.dinou/netlify/functions+build:netlify), and Dockerfiles (removed legacy manifest dirs; added--chown=node:nodeon.dinou/dist2). - Moved any files from legacy
favicons/intopublic/. - Audited
plugin.onRequesthooks to ensure static SSG pages do not depend on runtime-only context fields without a fallback. - Prefixed intentional browser-visible environment variables with
DINOU_PUBLIC_and installedcross-envexplicitly if referenced by custom scripts. - Confirmed
npx tsc --noEmit,npm run dev, andnpm run buildall succeed cleanly.