Dinouv7
npmGitHub
Dinou v7 Setup
Installation & Project Guide

Getting Started with Dinou

Start building modern, full-stack React 19 applications in seconds. Choose between the automated CLI generator or manual configuration for full architectural control.

1. Prerequisites

Before getting started, ensure your local environment meets the minimum requirements. Dinou is engineered to leverage modern JavaScript standards with zero transpile overhead.

1.1. Runtime Requirements

  • Node.js 20.6.0+ (Required): Dinou utilizes Node's modern native ES module customization hooks (module.register) for zero-fork server execution and Web Standard APIs (Request, Response, ReadableStream, Headers) natively supported in modern Node.js versions.
  • Bun 1.1+ (Optional): If you plan to run on Bun or compile self-contained standalone native executables using npm run build:bun:compile.
  • Deno 2.0+ (Optional): If you target Deno or cross-compile single-file binaries for Linux, macOS, or Windows using npm run build:deno:compile.
  • Cloudflare Wrangler (Optional): Required if you deploy to Cloudflare Workers withnpm run build:cloudflare and preview locally with wrangler dev.

2. Quick Start (CLI)

The fastest way to scaffold a ready-to-code Dinou application is using the official CLI starter. It sets up TypeScript, Tailwind CSS, sample Server Components, and the recommended directory layout:

2.1. CLI Scaffolding

# 1. Initialize a new Dinou application
npx create-dinou@latest my-app
# or
npm create dinou@latest my-app

# 2. Enter project directory
cd my-app

# 3. Launch development server (default: esbuild)
npm run dev

3. Manual Project Setup

Prefer to wire up everything manually? Follow these step-by-step instructions to configure Dinou from scratch with complete transparency:

13.1. Install Dependencies

Initialize your project folder and install React 19, React DOM, and the dinou framework package:

# Create and enter directory
mkdir my-dinou-app
cd my-dinou-app

# Initialize package.json
npm init -y

# Install React 19 and Dinou
npm install react react-dom dinou

# Install TypeScript definitions for IDE intellisense
npm install -D @types/react @types/react-dom

23.2. Project Structure & Files

Create the src/ directory with a root page (src/page.tsx) and the recommended root document layout (src/layout.tsx):

src/page.tsx (React Server Component)
// src/page.tsx - React Server Component (RSC)
export default function Page() {
  return (
    <main className="p-8 max-w-4xl mx-auto space-y-4">
      <h1 className="text-3xl font-bold tracking-tight">
        Hello from Dinou!
      </h1>
      <p className="text-muted-foreground">
        Rendered natively on the server with React 19 and zero client JavaScript overhead.
      </p>
    </main>
  );
}
src/layout.tsx (Recommended - Root Layout)
// src/layout.tsx - Root document layout
import type { ReactNode } from "react";

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <title>My Dinou App</title>
      </head>
      <body>{children}</body>
    </html>
  );
}

The root layout.tsx defines the shared <html> and <body> document shell, metadata, and global providers so you don't have to repeat them on each page.

Recommended Directory Layout
my-dinou-app/
├── public/                    # Static root assets (served directly at /)
│   ├── favicon.ico
│   ├── robots.txt
│   └── site.webmanifest
├── src/
│   ├── page.tsx               # Root page component (RSC)
│   ├── layout.tsx             # Root document layout (<html/head/body>)
│   └── globals.css            # Styles / Tailwind CSS
├── dinou.config.ts            # Framework configuration (optional: ppr, plugins)
├── dinou-env.d.ts             # Ambient framework typings
├── tsconfig.json              # TypeScript configuration
├── package.json
└── .gitignore

33.3. TypeScript Configuration

Dinou does not force you to use TypeScript—you are completely free to write your application in standard JavaScript (.js / .jsx). However, even for pure JavaScript projects, defining a tsconfig.json in your project root is strongly recommended:

💡 Why define tsconfig.json even when using JavaScript?
  • Import Aliases: Dinou's build engines (esbuild, Rollup, Webpack) automatically read compilerOptions.paths from tsconfig.json to resolve clean path aliases like @/* into src/*.
  • IDE Autocomplete: With "allowJs": true, code editors (VS Code, Cursor) use tsconfig.json to provide full autocomplete, auto-imports, and path resolution across all .js and .jsx files.
tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "@/*": ["src/*"]
    },
    "allowJs": true,
    "noEmit": true,
    "jsx": "react-jsx",
    "strict": true,
    "module": "ESNext",
    "moduleResolution": "bundler"
  },
  "include": [
    "src",
    "dinou-env.d.ts"
  ]
}
dinou-env.d.ts
/// <reference types="dinou/env" />

The dinou/env reference automatically declares ambient typings for static assets (SVGs, images, web fonts) and CSS modules without manual type boilerplate.

43.4. Package Scripts

Add the complete set of Dinou scripts to your package.json to control development, multi-runtime production builds (Node, Cloudflare, Deno, Bun), binary compilation, static exports, and ejecting (scroll through the block below to view all target combinations):

"scripts": {
  "dev": "dinou dev",
  "build": "dinou build",
  "start": "dinou start",
  "dev:esbuild": "dinou dev:esbuild",
  "dev:rollup": "dinou dev:rollup",
  "dev:webpack": "dinou dev:webpack",
  "build:node": "dinou build:node",
  "build:node:esbuild": "dinou build:node:esbuild",
  "build:node:rollup": "dinou build:node:rollup",
  "build:node:webpack": "dinou build:node:webpack",
  "start:node": "dinou start:node",
  "start:node:esbuild": "dinou start:node:esbuild",
  "start:node:rollup": "dinou start:node:rollup",
  "start:node:webpack": "dinou start:node:webpack",
  "build:cloudflare": "dinou build:cloudflare",
  "build:cloudflare:esbuild": "dinou build:cloudflare:esbuild",
  "build:cloudflare:rollup": "dinou build:cloudflare:rollup",
  "build:cloudflare:webpack": "dinou build:cloudflare:webpack",
  "build:deno": "dinou build:deno",
  "build:deno:esbuild": "dinou build:deno:esbuild",
  "build:deno:rollup": "dinou build:deno:rollup",
  "build:deno:webpack": "dinou build:deno:webpack",
  "build:deno:compile": "dinou build:deno:compile",
  "build:deno:compile:esbuild": "dinou build:deno:compile:esbuild",
  "build:deno:compile:rollup": "dinou build:deno:compile:rollup",
  "build:deno:compile:webpack": "dinou build:deno:compile:webpack",
  "build:deno:compile:linux": "dinou build:deno:compile:linux",
  "build:deno:compile:linux:esbuild": "dinou build:deno:compile:linux:esbuild",
  "build:deno:compile:linux:rollup": "dinou build:deno:compile:linux:rollup",
  "build:deno:compile:linux:webpack": "dinou build:deno:compile:linux:webpack",
  "build:deno:compile:linux_arm": "dinou build:deno:compile:linux_arm",
  "build:deno:compile:linux_arm:esbuild": "dinou build:deno:compile:linux_arm:esbuild",
  "build:deno:compile:linux_arm:rollup": "dinou build:deno:compile:linux_arm:rollup",
  "build:deno:compile:linux_arm:webpack": "dinou build:deno:compile:linux_arm:webpack",
  "build:deno:compile:mac": "dinou build:deno:compile:mac",
  "build:deno:compile:mac:esbuild": "dinou build:deno:compile:mac:esbuild",
  "build:deno:compile:mac:rollup": "dinou build:deno:compile:mac:rollup",
  "build:deno:compile:mac:webpack": "dinou build:deno:compile:mac:webpack",
  "build:deno:compile:win": "dinou build:deno:compile:win",
  "build:deno:compile:win:esbuild": "dinou build:deno:compile:win:esbuild",
  "build:deno:compile:win:rollup": "dinou build:deno:compile:win:rollup",
  "build:deno:compile:win:webpack": "dinou build:deno:compile:win:webpack",
  "start:deno": "dinou start:deno",
  "build:bun": "dinou build:bun",
  "build:bun:esbuild": "dinou build:bun:esbuild",
  "build:bun:rollup": "dinou build:bun:rollup",
  "build:bun:webpack": "dinou build:bun:webpack",
  "build:bun:compile": "dinou build:bun:compile",
  "build:bun:compile:esbuild": "dinou build:bun:compile:esbuild",
  "build:bun:compile:rollup": "dinou build:bun:compile:rollup",
  "build:bun:compile:webpack": "dinou build:bun:compile:webpack",
  "build:bun:compile:linux": "dinou build:bun:compile:linux",
  "build:bun:compile:linux:esbuild": "dinou build:bun:compile:linux:esbuild",
  "build:bun:compile:linux:rollup": "dinou build:bun:compile:linux:rollup",
  "build:bun:compile:linux:webpack": "dinou build:bun:compile:linux:webpack",
  "build:bun:compile:linux_arm": "dinou build:bun:compile:linux_arm",
  "build:bun:compile:linux_arm:esbuild": "dinou build:bun:compile:linux_arm:esbuild",
  "build:bun:compile:linux_arm:rollup": "dinou build:bun:compile:linux_arm:rollup",
  "build:bun:compile:linux_arm:webpack": "dinou build:bun:compile:linux_arm:webpack",
  "build:bun:compile:mac": "dinou build:bun:compile:mac",
  "build:bun:compile:mac:esbuild": "dinou build:bun:compile:mac:esbuild",
  "build:bun:compile:mac:rollup": "dinou build:bun:compile:mac:rollup",
  "build:bun:compile:mac:webpack": "dinou build:bun:compile:mac:webpack",
  "build:bun:compile:win": "dinou build:bun:compile:win",
  "build:bun:compile:win:esbuild": "dinou build:bun:compile:win:esbuild",
  "build:bun:compile:win:rollup": "dinou build:bun:compile:win:rollup",
  "build:bun:compile:win:webpack": "dinou build:bun:compile:win:webpack",
  "build:bun:pure": "dinou build:bun:pure",
  "build:bun:pure:esbuild": "dinou build:bun:pure:esbuild",
  "build:bun:pure:rollup": "dinou build:bun:pure:rollup",
  "build:bun:pure:webpack": "dinou build:bun:pure:webpack",
  "build:bun:pure:compile": "dinou build:bun:pure:compile",
  "build:bun:pure:compile:esbuild": "dinou build:bun:pure:compile:esbuild",
  "build:bun:pure:compile:rollup": "dinou build:bun:pure:compile:rollup",
  "build:bun:pure:compile:webpack": "dinou build:bun:pure:compile:webpack",
  "build:bun:pure:compile:linux": "dinou build:bun:pure:compile:linux",
  "build:bun:pure:compile:linux:esbuild": "dinou build:bun:pure:compile:linux:esbuild",
  "build:bun:pure:compile:linux:rollup": "dinou build:bun:pure:compile:linux:rollup",
  "build:bun:pure:compile:linux:webpack": "dinou build:bun:pure:compile:linux:webpack",
  "build:bun:pure:compile:linux_arm": "dinou build:bun:pure:compile:linux_arm",
  "build:bun:pure:compile:linux_arm:esbuild": "dinou build:bun:pure:compile:linux_arm:esbuild",
  "build:bun:pure:compile:linux_arm:rollup": "dinou build:bun:pure:compile:linux_arm:rollup",
  "build:bun:pure:compile:linux_arm:webpack": "dinou build:bun:pure:compile:linux_arm:webpack",
  "build:bun:pure:compile:mac": "dinou build:bun:pure:compile:mac",
  "build:bun:pure:compile:mac:esbuild": "dinou build:bun:pure:compile:mac:esbuild",
  "build:bun:pure:compile:mac:rollup": "dinou build:bun:pure:compile:mac:rollup",
  "build:bun:pure:compile:mac:webpack": "dinou build:bun:pure:compile:mac:webpack",
  "build:bun:pure:compile:win": "dinou build:bun:pure:compile:win",
  "build:bun:pure:compile:win:esbuild": "dinou build:bun:pure:compile:win:esbuild",
  "build:bun:pure:compile:win:rollup": "dinou build:bun:pure:compile:win:rollup",
  "build:bun:pure:compile:win:webpack": "dinou build:bun:pure:compile:win:webpack",
  "start:bun": "dinou start:bun",
  "start:bun:esbuild": "dinou start:bun:esbuild",
  "start:bun:rollup": "dinou start:bun:rollup",
  "start:bun:webpack": "dinou start:bun:webpack",
  "export-static": "dinou export-static",
  "export-static:esbuild": "dinou export-static:esbuild",
  "export-static:rollup": "dinou export-static:rollup",
  "export-static:webpack": "dinou export-static:webpack",
  "eject": "dinou eject"
}

53.5. Configure .gitignore

Create a .gitignore file to ignore dependencies, environment variables, build outputs, and Dinou caches:

node_modules
.dinou
out
dist
.wrangler
.env

.dinou/ holds internal dev artifacts and runtime builds; out/ contains pages generated by export-static; dist/ stores compiled single-executable binaries (Deno / Bun); and .wrangler/ stores local state when testing Cloudflare Workers.

63.6. Start Development Server

Run the development server with the fast esbuild bundler (default), or choose Rollup or Webpack:

# Start with default ultra-fast esbuild
npm run dev

# Or start with Rollup or Webpack
npm run dev:rollup
npm run dev:webpack

4. Building for Production & Runtimes

Dinou provides both bundler freedom (esbuild, Rollup, Webpack) and universal runtime deployment (Node.js, Cloudflare Workers, Deno, Bun, or Static SSG) from a single codebase in src/ with zero code changes.

4.1. Bundler Selection (esbuild, Rollup, Webpack)

By default, Dinou uses esbuild for sub-second cold starts and in-memory compilation. When enterprise plugins or custom loaders are required, you can switch seamlessly to Rollup or Webpack with 100% feature parity:

# Start development with your preferred bundler
npm run dev           # Default: esbuild
npm run dev:rollup    # Dedicated Rollup in-memory engine
npm run dev:webpack   # Dedicated Webpack engine

For advanced compiler tuning, custom plugins, and SWC options, visit the Bundlers Guide →

4.2. Target Runtimes (Deploy Anywhere)

Compile your application for any execution environment without altering component logic:

Node.js Server

Production server with HTTP/2 and native streaming.

npm run build:node && npm run start:node
Cloudflare Workers Edge

Edge worker with 0ms cold starts and global distribution.

npm run build:cloudflare && npx wrangler dev
Standalone Binaries (Deno / Bun)

Self-contained executable binary output directly to dist/.

npm run build:deno:compile # or build:bun:compile
Static Site Export (SSG)

Pre-rendered HTML and RSC payloads output to out/.

npm run export-static

For complete deployment guides, Docker setups, and cloud hosting instructions, see the Deployment Guide →

Previous
Introduction
Next
About