Migration from v8 to v9

1. Upgrade Implications: Zero Code Changes Required

100% Backwards Compatible: Zero Code Changes

As an application developer, you do not need to rewrite, refactor, or adjust a single line of code. All route contracts, Server Components (RSC), Flight RPC Server Functions, CSS modules, Tailwind styling, and multi-bundler builds operate identically to v8.

Routes & Layouts (page.tsx, layout.tsx)

Data Contracts (page_functions, layout_functions)

Server Functions ("use server", forms, closures)

Client Components ("use client" hooks)

1.1 Upgrading Your Dependencies

To upgrade any standard Dinou project, simply update the dinou package to ^9.0.0:

npm install dinou@latest

bun add dinou@latest

pnpm add dinou@latest

yarn add dinou@latest

Your package.json will reflect the new major version (note that Dinou v9 requires react and react-dom at version 19.3.1 or higher):

{
  "name": "my-dinou-app",
  "type": "module",
  "dependencies": {
    "dinou": "^9.0.0",
    "react": "^19.3.1",
    "react-dom": "^19.3.1"
  }
}

1.2 100% Backwards Compatibility

Every feature from Dinou v8 is fully preserved in v9 with zero deprecations:

Framework Feature	Dinou v8 Status	Dinou v9 Status	Action Required
Route Signatures (page.tsx / layout.tsx)	Supported	Identical	None
Data Contracts (page_functions.ts)	Supported	Identical	None
Server Functions (Module & Function Level)	Supported (v8.1)	Identical	None
Multi-Engine Bundlers (esbuild, Rollup, Webpack)	Supported	Accelerated	None
Universal Deployment (Node, Bun, Deno, Cloudflare)	Supported	Identical	None

2. What's New: Dual-Mode Additive Vendoring

Although application code remains 100% unchanged, Dinou v9 completely overhauls how internal build dependencies and compiler plugins are loaded and executed.

2.1 Solved: Cold Starts, FS Overhead & Dependency Drift

Instant Cold Starts

Eliminates scanning and parsing thousands of small files across deep node_modules directories during framework startup.

Zero Upstream Drift

Guarantees identical, deterministic behavior across machines and CI runners without subtle bugs caused by transitive dependency updates.

Seamless ESM Interop

Pre-compiled, standalone ESM modules eliminate costly runtime CommonJS bridges and dynamic require shims.

2.2 Native Node.js Subpath Imports (`#...`)

Rather than using ad-hoc file aliases or complex module linkers, Dinou v9 implements the native Node.js Subpath Imports standard. In Dinou's internal configuration, dependencies are mapped with conditional resolution:

{
  "imports": {
    "#babel/core": {
      "unvendorized": "@babel/core",
      "default": "./compiled/babel-core/index.js"
    },
    "#postcss": {
      "unvendorized": "postcss",
      "default": "./compiled/postcss/index.js"
    },
    "#chokidar": {
      "unvendorized": "chokidar",
      "default": "./compiled/chokidar/index.js"
    }
  }
}

The Additive Principle

Vendoring in Dinou v9 is strictly additive and non-destructive: all 36 vendorized dependencies remain declared in package.json and installed in node_modules. If you ever need to inspect or patch an upstream library, you can switch off vendoring on-demand with a single flag.

3. How to Use Dinou v9: The Two Modes

Dinou provides two execution modes that require no complex configuration:

3.1 Default Mode: Pre-Compiled Fast Vendors

When you develop or build your application normally:

# Starts the development server in default vendorized mode
npm run dev

# Compiles for production using pre-bundled vendors
npm run build

Dinou runs in Vendorized Mode by default. All 36 internal compiler and bundler utilities resolve directly to optimized bundles in dinou/compiled/, providing instant startup times with zero configuration.

3.2 Unvendorized Mode (`-u` / `--unvendorized`)

If you need to debug an upstream library in node_modules, test a patch, or inspect raw dependencies, Dinou provides a single, uniform opt-out mechanism: the -u flag.

# Forward the -u flag to the development script
npm run dev -- -u

# Build using unvendorized node_modules packages
npm run build:node:esbuild -- -u

# Run production server in unvendorized mode
npm start -- -u

# Development server with -u
npx dinou dev -u

# Production build with -u
npx dinou build:node:esbuild -u

Transparent Execution via ensureVendorMode

You do not need to memorize verbose Node.js flags like --conditions=unvendorized. Dinou's runtime hook transparently intercepts the -u flag, spawns a child process with Node's native conditional resolution, pipes stdio, and forwards process signals automatically.

3.3 Environment Variable (`DINOU_UNVENDORIZED`)

For CI/CD pipelines, Docker environments, or terminal sessions where passing CLI arguments is inconvenient, set the environment variable:

export DINOU_UNVENDORIZED=true
npm run build

$env:DINOU_UNVENDORIZED="true"
npm run build

npx cross-env DINOU_UNVENDORIZED=true npm run build

4. Ejected Applications: The `build:vendors` Script

In Dinou, developers can eject their application at any time with dinou eject to gain direct, unrestricted access to the framework source code in ./dinou.

In an ejected Dinou v9 application:

Pre-compiled vendor modules are located in ./dinou/compiled/.
Your root package.json automatically includes the maintenance script:

"scripts": {
  "build:vendors": "node dinou/scripts/build-vendors.js"
}

When Should You Run npm run build:vendors?

If you update a framework dependency in your root package.json (for instance, bumping @babel/core or postcss to a new patch release):

Your app will automatically use the updated package from node_modules whenever running with -u.
To also update the default vendorized cache (./dinou/compiled/) to the new version, simply run npm run build:vendors.
In ~5 seconds, all 36 vendor bundles are recompiled with full ESM interop wrappers and vendors-manifest.json is updated.

5. Vendor Catalog: Compiled Tools vs. External Exceptions

Dinou implements a strict architectural separation between packages that benefit from pre-compilation and dependencies that must remain external:

36 Compiled Packages (in dinou/compiled/)

Pre-bundled into standalone ESM:

Babel AST Toolchain: @babel/core, @babel/parser, @babel/traverse, @babel/generator, @babel/types, @babel/template, babel-plugin-react-compiler
Rollup Plugins: @rollup/plugin-babel, commonjs, node-resolve, replace, json
Webpack Loaders: babel-loader, css-loader, mini-css-extract-plugin, copy-webpack-plugin, terser-webpack-plugin
CSS & Styling: postcss, autoprefixer, @tailwindcss/postcss, postcss-modules-*
Utilities: chokidar, commander, dotenv, picocolors, ws

External Exceptions (Never Vendorized)

Kept strictly in standard node_modules:

Native Platform Binaries: esbuild (Go executable) and @swc/core (native Node-API .node binary bindings). Pre-compiling native platform binaries breaks architecture-specific resolution.
React Singletons: react, react-dom, and @roggc/react-server-dom-esm must share an identical instance across client and server.
Core Bundler Engines: webpack and rollup orchestrate dynamic user configurations and plugins at build time.

6. Quick Reference & Verification Checklist

Scenario / Workflow	Command	Active Resolution Mode
Standard development	npm run dev	Vendorized Mode (Default, fast)
Standard production build	npm run build	Vendorized Mode (Default, fast)
Debug upstream packages	npm run dev -- -u	Unvendorized Mode (node_modules)
Build with raw dependencies	npm run build -- -u	Unvendorized Mode (node_modules)
Recompile local vendors (ejected)	npm run build:vendors	Regenerates ./dinou/compiled/

Dinou v9 Verification Checklist

Updated "dinou": "^9.0.0" in package.json and ran npm install.
Confirmed npm run dev boots cleanly in default vendorized mode.
(Optional) Tested npm run dev -- -u to confirm unvendorized fallback operates as expected.
Confirmed production build succeeds: npm run build.

Overview

Migration from v7 to v8