@codenotch/codenotch.cli 1.0.36 → 1.0.37

package/dist/utils/BuildUtils.js

@@ -4,17 +4,16 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const fs_1 = require("fs");
+const path_1 = require("path");
 const StringUtils_1 = __importDefault(require("./StringUtils"));
 const FileUtils_1 = __importDefault(require("./FileUtils"));
 const chalk_1 = __importDefault(require("chalk"));
 const fs_2 = __importDefault(require("fs"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
-const node_fetch_1 = __importDefault(require("node-fetch"));
 const ShellUtils_1 = __importDefault(require("./ShellUtils"));
-const os_1 = require("os");
 const ConsoleUtils_1 = __importDefault(require("./ConsoleUtils"));
 class BuildUtils {
-    static CN_REACT_VERSION = '2.0.0';
+    static CN_REACT_VERSION = '2.0.1';
     static findWorkspaceFromFile(childPath) {
         let parts = childPath.split(FileUtils_1.default.slash());
         parts = parts.slice(0, parts.length - 1); // Remove file name
@@ -30,20 +29,47 @@ class BuildUtils {
         return workspacePath;
     }
     /**
-     * cn react build <target_file>
+     * Builds one React app of a Codenotch project into a ready-to-serve bundle.
+     * Behind the command: cn react build <target_file>
+     *
+     * Everything is staged under the `.codenotch/` folder of the workspace, the sources of the
+     * project are never touched:
+     * - `.codenotch/<appName>-source` — the Vite project: generated package.json, index.html,
+     *   index.jsx (mounts the app component with react 19's createRoot), vite.config.mjs,
+     *   tsconfig.json, the workspace `.npmrc` when there is one, and a copy of every source file of the workspace,
+     *   mirrored flat so that root config files (postcss.config.js, ...) stay where Vite looks.
+     * - `.codenotch/<appName>-dist` — the bundle Vite emits, plus a `.env` holding the Codenotch
+     *   environment (app name, manifests, cluster url) read by the served page.
+     * Both folders are deleted first when a previous build left them behind.
+     *
+     * The build itself runs `npm install` then `npm run build` (vite alone: the copy holds server
+     * files too, typechecking is the job of 'cn validate') inside `-source`, with the Node the CLI
+     * runs under — Node 20 or newer is expected (Vite 8), and npm needs the network.
+     *
+     * On success, prints the `cn react serve '<dist>'` command to try the bundle.
+     *
+     * @param appFilePath Path (absolute, or relative to the current directory) to the app
+     *                    component, e.g. `./apps/index.tsx`. NOT the manifest: the sibling
+     *                    `<name>.manifest.json` is derived from it, and must exist and declare
+     *                    `app.name`, which names the staging folders. The file must live inside
+     *                    a Codenotch workspace (a `manifest.json` in one of its parent folders).
+     * @param clusterUrl  Base URL of the Codenotch cluster the bundle will talk to, written into
+     *                    the `.env` of the dist. Without it the bundle is built all the same,
+     *                    but not bound to a cluster.
+     *
+     * Validation failures (missing file, no workspace, no app name...) print the reason and leave
+     * with `process.exit(1)`: this method is the command, not a library call. See `buildApp2` for
+     * the throwing, CI oriented variant.
      */
-    static async buildApp(appFilePath, clusterUrl) {
+    static async buildReactApp(appFilePath, clusterUrl) {
         //appFilePath = '/home/fabian/Documents/Scenario/test-with-jsx/apps/AppWithFC.tsx';
         //clusterUrl = 'https://fabric.echino.com:19081/lemollqa/scenario';
         if (`${appFilePath ?? ''}`.trim() === '') {
             console.log(chalk_1.default.red(`Error: No target file provided for build command.`));
             process.exit(1);
         }
-        let isRelative = !appFilePath.startsWith('/') && !appFilePath.match(/^[a-zA-Z]:\\/);
-        if (isRelative) {
-            let currentPath = process.cwd();
-            appFilePath = StringUtils_1.default.normalizePath(`${currentPath}/${appFilePath}`);
-        }
+        // resolve() already turns a relative path into an absolute one, based on the current directory
+        appFilePath = StringUtils_1.default.normalizePath((0, path_1.resolve)(appFilePath));
         // Check arguments
         if ((0, fs_1.existsSync)(appFilePath ?? '') === false) {
             console.log(chalk_1.default.red(`Error: File "${appFilePath}" not found`));
@@ -54,8 +80,6 @@ class BuildUtils {
             console.log(chalk_1.default.red(`Error: Could not find workspace manifest for file "${appFilePath}".`));
             process.exit(1);
         }
-        // Tenant name
-        let tenantName = await this.fetchTenantName(clusterUrl);
         // Load workspace
         console.log("Loading workspace manifest...");
         let workspace = {
@@ -81,16 +105,18 @@ class BuildUtils {
         }
         ConsoleUtils_1.default.check(`App manifest loaded successfully (App name: "${appName}").\n`);
         // Define paths
+        // The workspace layout is mirrored directly under outDir (no 'src/' wrapper), so root
+        // config files (postcss.config.js, tailwind, ...) land where Vite looks for them
         let outDir = StringUtils_1.default.normalizePath(`${workspacePath}/.codenotch/${appName}-source`);
         let distDir = StringUtils_1.default.normalizePath(`${workspacePath}/.codenotch/${appName}-dist`);
         let fileName = StringUtils_1.default.firstUpper(StringUtils_1.default.getNameWithoutExtention(appFilename));
-        let outFilePath = StringUtils_1.default.normalizePath(`${appFilePath.replace(workspacePath, outDir + '/src')}`);
+        let outFilePath = StringUtils_1.default.normalizePath(`${appFilePath.replace(workspacePath, outDir)}`);
         let relativeOutFilePath = StringUtils_1.default.toRelativePath(outFilePath, outDir).replaceAll('\\', '/');
         // Clean previous builds
         if ((0, fs_1.existsSync)(outDir) || (0, fs_1.existsSync)(distDir)) {
             console.log("Cleaning previous builds...");
-            FileUtils_1.default.delete(outDir);
-            FileUtils_1.default.delete(distDir);
+            FileUtils_1.default.deleteRecursively(outDir);
+            FileUtils_1.default.deleteRecursively(distDir);
             ConsoleUtils_1.default.check(`Output directory cleaned (${outDir})\n`);
         }
         console.log("Creating build files...");
@@ -106,16 +132,12 @@ class BuildUtils {
         let indexJsx = this.createIndexJsx(relativeOutFilePath, fileName);
         FileUtils_1.default.writeFileSync(outDir + '/index.jsx', indexJsx);
         ConsoleUtils_1.default.check(`index.jsx created successfully`);
-        // vite.config.js
+        // vite.config.mjs (.mjs so it always loads as ESM, regardless of package.json "type")
         let viteConfig = this.createViteConfig(appName);
-        FileUtils_1.default.writeFileSync(outDir + '/vite.config.js', viteConfig);
-        ConsoleUtils_1.default.check(`vite.config.js created successfully`);
-        // empty-module.js
-        let emptyModule = this.createEmptyModule();
-        FileUtils_1.default.writeFileSync(outDir + '/empty-module.js', emptyModule);
-        ConsoleUtils_1.default.check(`empty-module.js created successfully`);
-        // tsconfig.json
-        let tsconfig = this.createTsConfig();
+        FileUtils_1.default.writeFileSync(outDir + '/vite.config.mjs', viteConfig);
+        ConsoleUtils_1.default.check(`vite.config.mjs created successfully`);
+        // tsconfig.json - layout is flat (mirrors the workspace), so typecheck the source trees
+        let tsconfig = this.createTsConfig(["**/*.ts", "**/*.tsx"]);
         FileUtils_1.default.writeFileSync(outDir + '/tsconfig.json', tsconfig);
         ConsoleUtils_1.default.check(`tsconfig.json created successfully`);
         let npmRcContent = fs_2.default.existsSync(StringUtils_1.default.normalizePath(`${workspacePath}/.npmrc`)) ?
@@ -128,41 +150,40 @@ class BuildUtils {
         // Find files to copy
         console.log("\n");
         console.log("Reading files...");
-        let includedExts = ['.css', '.scss', '.tsx', '.jsx', '.ts', '.js'];
-        let includedFiles = [];
-        for (let file of FileUtils_1.default.getAllFilesFromPath(workspacePath)) {
-            if (includedExts.some(ext => file.toLowerCase().endsWith(ext))) {
-                includedFiles.push(file);
-            }
-        }
+        let includedFiles = FileUtils_1.default.listFilesRecursively(workspacePath, {
+            fileExtensions: ['.css', '.scss', '.tsx', '.jsx', '.ts', '.js', '.cjs', '.mjs'],
+            // Without these the copy would swallow the dependencies, and the staging folder itself
+            ignoredFolderNames: ['.codenotch', 'node_modules', '.git']
+        });
         if (includedFiles.length === 0) {
             console.log(chalk_1.default.red(`Error: No files found in "${workspacePath}" to include in the build`));
             return;
         }
         for (let includedFile of includedFiles) {
-            let targetPath = StringUtils_1.default.normalizePath(`${includedFile.replace(workspacePath, outDir + '/src')}`);
+            let targetPath = StringUtils_1.default.normalizePath(`${includedFile.replace(workspacePath, outDir)}`);
             fs_extra_1.default.copySync(includedFile, targetPath);
         }
         ConsoleUtils_1.default.check(`${includedFiles.length} files copied successfully\n`);
         // execute npm i in the outDir
         await ShellUtils_1.default.exec(outDir, 'npm install', 'Installing dependencies', true);
-        // Install and use Node.js 20 with nvm (platform-specific)
-        if ((0, os_1.platform)() === 'win32') {
-            await ShellUtils_1.default.exec(outDir, 'nvm install 20 && nvm use 20 && npm run build', 'Setting up Node.js 20 and building project', true);
-        }
-        else {
-            await ShellUtils_1.default.exec(outDir, 'bash -c ". ~/.nvm/nvm.sh && nvm install 20 && nvm use 20 && npm run build"', 'Setting up Node.js 20 and building project', true);
+        // Vite 8 needs Node 20+: warn up front, its own error would be cryptic
+        const nodeMajor = parseInt(process.versions.node.split('.')[0], 10);
+        if (nodeMajor < 20) {
+            ConsoleUtils_1.default.checkWarning(`Node ${process.versions.node} detected, the build needs Node 20 or newer and may fail.`);
         }
-        ConsoleUtils_1.default.check(`Nvm and build executed successfully\n`);
+        await ShellUtils_1.default.exec(outDir, 'npm run build', 'Building project', true);
+        ConsoleUtils_1.default.check(`Build executed successfully\n`);
         // create .env file
         console.log("Creating .env file...");
         let envVariables = await this.getCodenotchEnvVariables(workspace, {
             appName: appName,
             app: appManifest,
-            tenantName: tenantName,
             clusterUrl: clusterUrl
         });
-        let envContent = Object.keys(envVariables).map(c => `${c}=${envVariables[c]}`).join('\n');
+        // A variable without value is left out, otherwise the page would read the string "undefined"
+        let envContent = Object.keys(envVariables)
+            .filter(c => envVariables[c] !== undefined && envVariables[c] !== null)
+            .map(c => `${c}=${envVariables[c]}`).join('\n');
         FileUtils_1.default.writeFileSync(distDir + '/.env', envContent);
         ConsoleUtils_1.default.check(`.env file created successfully\n`);
         let bundlePath = StringUtils_1.default.normalizePath(`${distDir}`);
@@ -183,11 +204,8 @@ class BuildUtils {
         if (`${appFilePath ?? ''}`.trim() === '') {
             throw new Error(`No target file provided for build command.`);
         }
-        let isRelative = !appFilePath.startsWith('/') && !appFilePath.match(/^[a-zA-Z]:\\/);
-        if (isRelative) {
-            let currentPath = process.cwd();
-            appFilePath = StringUtils_1.default.normalizePath(`${currentPath}/${appFilePath}`);
-        }
+        // resolve() already turns a relative path into an absolute one, based on the current directory
+        appFilePath = StringUtils_1.default.normalizePath((0, path_1.resolve)(appFilePath));
         // Check arguments
         if ((0, fs_1.existsSync)(appFilePath ?? '') === false) {
             throw new Error(`File "${appFilePath}" not found`);
@@ -230,9 +248,6 @@ class BuildUtils {
         // vite.config.mjs (.mjs so it always loads as ESM, regardless of package.json "type")
         let viteConfig = this.createViteConfig(appName);
         FileUtils_1.default.writeFileSync(outDir + '/vite.config.mjs', viteConfig);
-        // empty-module.js , needed to mock some modules crypto-browserify -> can we avoid this ?
-        let emptyModule = this.createEmptyModule();
-        FileUtils_1.default.writeFileSync(outDir + '/empty-module.js', emptyModule);
         // tsconfig.json — layout is flat (mirrors the workspace), so typecheck the source trees
         let tsconfig = this.createTsConfig(["**/*.ts", "**/*.tsx"]);
         FileUtils_1.default.writeFileSync(outDir + '/tsconfig.json', tsconfig);
@@ -244,18 +259,10 @@ class BuildUtils {
         }
         // Find files to copy
         //TODO what if we have 2 apps in the /apps folder ? if we build one it will copy the file from the other as they are not separated in different folders
-        let includedExts = ['.css', '.scss', '.tsx', '.jsx', '.ts', '.js', '.cjs', '.mjs'];
-        let includedFiles = [];
-        for (let file of FileUtils_1.default.getAllFilesFromPath(workspacePath)) {
-            // Skip generated/dependency trees so we don't copy the build output back into itself.
-            let normalized = file.replaceAll('\\', '/');
-            if (normalized.includes('/.codenotch/') || normalized.includes('/node_modules/')) {
-                continue;
-            }
-            if (includedExts.some(ext => file.toLowerCase().endsWith(ext))) {
-                includedFiles.push(file);
-            }
-        }
+        let includedFiles = FileUtils_1.default.listFilesRecursively(workspacePath, {
+            fileExtensions: ['.css', '.scss', '.tsx', '.jsx', '.ts', '.js', '.cjs', '.mjs'],
+            ignoredFolderNames: ['.codenotch', 'node_modules']
+        });
         if (includedFiles.length === 0) {
             throw new Error(`No files found in "${workspacePath}" to include in the build`);
         }
@@ -280,67 +287,49 @@ class BuildUtils {
         }
     }
     static createIndexJsx(relativeOutFilePath, fileName) {
-        return `
-import React from 'react';
-import ReactDOM from 'react-dom';
-import ${fileName} from './${relativeOutFilePath}';
-import { init } from 'codenotch-react';
-
-fetch('/api/env')
-	.then(response => response.json())
-	.then(data => {
-        init(data);
-		ReactDOM.render(<${fileName} />, document.getElementById('root'));
-	})
-	.catch(error => {
-        console.error('Error fetching environment variables:', error);
-        init(null);
-		ReactDOM.render(<${fileName} />, document.getElementById('root'));
-	});
+        return `
+import { createRoot } from 'react-dom/client';
+import ${fileName} from './${relativeOutFilePath}';
+import { init } from '@codenotch/codenotch.react';
+
+// The environment is exposed by the server hosting the bundle (see 'cn react serve')
+const root = createRoot(document.getElementById('root'));
+fetch('/api/env')
+	.then(response => response.json())
+	.then(data => {
+		init(data);
+		root.render(<${fileName} />);
+	})
+	.catch(error => {
+		console.error('Error fetching environment variables:', error);
+		init({});
+		root.render(<${fileName} />);
+	});
 `.trim();
     }
     /**
      * When served from the runtime env variables are not available, the variables are injected into the html file instead
      */
     static createIndexJsxDeployment(relativeOutFilePath, fileName) {
-        return `
-import React from 'react';
-import ReactDOM from 'react-dom';
-import ${fileName} from './${relativeOutFilePath}';
-import { init } from 'codenotch-react';
-
-// variables are injected into the html by the runtime, we can access them on the window object
-const data = {
-    clusterUrl: tenant.clusterUrl,
-    serviceName: serviceName,
-    theme: 'dark',
-    language: languages[0] ?? 'en',
-    appManifest: appManifest,
-    tenantName: tenant.name,
-    appName: appName
-};
-init(data);
-ReactDOM.render(<${fileName} />, document.getElementById('root'));
-
+        return `
+import { createRoot } from 'react-dom/client';
+import ${fileName} from './${relativeOutFilePath}';
+import { init } from '@codenotch/codenotch.react';
+
+// variables are injected into the html by the runtime, we can access them on the window object
+const data = {
+    clusterUrl: tenant.clusterUrl,
+    serviceName: serviceName,
+    theme: 'dark',
+    language: languages[0] ?? 'en',
+    appManifest: appManifest,
+    appName: appName
+};
+init(data);
+createRoot(document.getElementById('root')).render(<${fileName} />);
+
 `.trim();
     }
-    static async fetchTenantName(clusterUrl) {
-        let tenantName = undefined;
-        if (clusterUrl !== undefined) {
-            console.log('Fetching tenant name from cluster URL...');
-            tenantName = await this.getTenantName(clusterUrl);
-            if (tenantName) {
-                ConsoleUtils_1.default.check(`Tenant name "${tenantName}" fetched successfully\n`);
-            }
-            else {
-                console.log(chalk_1.default.yellow(`Warning: Unable to fetch tenant name from cluster URL "${clusterUrl}".\n`));
-            }
-        }
-        else {
-            console.log(chalk_1.default.yellow(`Warning: No cluster URL provided.\n`));
-        }
-        return tenantName;
-    }
     static async getCodenotchEnvVariables(workpace, options) {
         let result = {
             clusterUrl: options.clusterUrl,
@@ -352,12 +341,6 @@ ReactDOM.render(<${fileName} />, document.getElementById('root'));
         if (options.app) {
             result.appManifest = JSON.stringify(options.app);
         }
-        if (options.tenantName) {
-            result.tenantName = options.tenantName;
-        }
-        let tenantName = options.tenantName;
-        if (tenantName)
-            result.tenantName = tenantName;
         if (options.appName)
             result.appName = options.appName;
         if (options.accessToken)
@@ -366,19 +349,6 @@ ReactDOM.render(<${fileName} />, document.getElementById('root'));
             result.baseUrl = options.baseUrl;
         return result;
     }
-    static async getTenantName(cluster) {
-        try {
-            let obj = await (await (0, node_fetch_1.default)(`${cluster}/portal/tenant`)).json();
-            if (obj && obj.name && typeof obj.name === 'string') {
-                return obj.name;
-            }
-            return undefined;
-        }
-        catch (e) {
-            console.error("Error while fetching tenant name:", e);
-            return undefined;
-        }
-    }
     /** Compiler options shared by the generated build tsconfig and `cn validate` on script files. */
     static defaultCompilerOptions() {
         return {
@@ -391,11 +361,11 @@ ReactDOM.render(<${fileName} />, document.getElementById('root'));
             "strict": true,
             "forceConsistentCasingInFileNames": true,
             "module": "ESNext",
-            "moduleResolution": "Node",
+            "moduleResolution": "Bundler",
             "resolveJsonModule": true,
             "isolatedModules": true,
             "noEmit": true, // On demande à tsc de ne PAS générer de fichiers
-            "jsx": "react" // "react" correspond au mode classic pour React 16
+            "jsx": "react-jsx" // automatic runtime, the react 19 default
         };
     }
     static createTsConfig(include = ["src"]) {
@@ -405,97 +375,46 @@ ReactDOM.render(<${fileName} />, document.getElementById('root'));
         }, null, 4);
         return tsconfig;
     }
-    static createEmptyModule() {
-        let emptyModule = `
-const deepMock = new Proxy(() => null, {
-    get: (target, prop) => {
-        console.warn('Empty module proxy accessed property: ', prop);
-        if (prop === '__esModule') return true;
-        return deepMock;
-    }
-});
-export default deepMock;
-export class ComponentDescription {
-    constructor() {
-        this.tag = '';
-        this.props = {};
-        this.parentInheritedProps = {};
-        this.children = [];
-        this.storedData = {};
-    }
-};
-export const DeclarationState = {
-    IDLE : "idle",
-    LOADING : "loading",
-    SUCCESS : "success",
-    ERROR : "error"
-};
-export const DspVarType = {
-    STRING : "string",
-    BOOLEAN : "boolean",
-    NUMBER : "number",
-    INTEGER : "integer",
-    COLOR : "color",
-    THICKNESS : "thickness",
-    SIZE : "size",
-    BORDER : "border",
-    OBJECT : "object",
-    ARRAY : "array",
-    FUNCTION : "function",
-    ACTION : "action",
-    REACT_NODE : "reactNode",
-    RENDERER : "renderer"
-};`.trim();
-        return emptyModule;
-    }
     static createViteConfig(appName) {
-        let debugOptions = `
-        sourcemap: true,
-        terserOptions: {
-            mangle: false,
-            keep_fnames: true,
-            keep_classnames: true,
+        let debugOptions = `
+        sourcemap: true,
+        terserOptions: {
+            mangle: false,
+            keep_fnames: true,
+            keep_classnames: true,
         }`;
-        let viteConfig = `
-import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
-import path from 'path';
-export default defineConfig({
-    plugins: [
-        react({ jsxRuntime: 'classic' }),
-    ],
-    base: './',
-    build: {
-        outDir: '../${appName}-dist',
-        emptyOutDir: true, 
-        ${debugOptions}
-    },
-    resolve: {
-        alias: [
-            { find: 'crypto-browserify', replacement: './empty-module.js' },
-            { find: /^@echino\\/codenotch\\.ui\\.monaco(\\/.*)?$/, replacement: path.resolve(__dirname, './empty-module.js') },
-            { find: /^@echino\\/echino\\.ui\\.sdk(\\/.*)?$/, replacement: path.resolve(__dirname, './empty-module.js') },
-        ],
-    },
+        let viteConfig = `
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import path from 'path';
+export default defineConfig({
+    plugins: [
+        react(),
+    ],
+    base: './',
+    build: {
+        outDir: '../${appName}-dist',
+        emptyOutDir: true, 
+        ${debugOptions}
+    }
 })`.trim();
         return viteConfig;
     }
     static createIndexHtml(appManifest, appName) {
-        let indexHtml = `<!DOCTYPE html>
-<html lang="fr">
-    <head>
-        <meta charset="${appManifest.html?.charset ?? 'UTF-8'}" />
-        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-        <title>${appManifest.html?.title ?? appName}</title>
-        <meta name="description" content="${appManifest.html?.description ?? ''}" />
-        <meta name="author" content="${appManifest.html?.author ?? ''}" />
-        <meta name="keywords" content="${appManifest.html?.keywords ?? ''}" />
-        <script src="https://kit.fontawesome.com/cd9ce0b05e.js" crossorigin="anonymous" data-auto-replace-svg="nest"></script>
-    </head>
-    <body>
-        <div id="root"></div>
-        <script type="module" src="/index.jsx"></script>
-    </body>
+        let indexHtml = `<!DOCTYPE html>
+<html lang="fr">
+    <head>
+        <meta charset="${appManifest.html?.charset ?? 'UTF-8'}" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>${appManifest.html?.title ?? appName}</title>
+        <meta name="description" content="${appManifest.html?.description ?? ''}" />
+        <meta name="author" content="${appManifest.html?.author ?? ''}" />
+        <meta name="keywords" content="${appManifest.html?.keywords ?? ''}" />
+    </head>
+    <body>
+        <div id="root"></div>
+        <script type="module" src="/index.jsx"></script>
+    </body>
 </html>`;
         return indexHtml;
     }
@@ -513,7 +432,9 @@ export default defineConfig({
             "type": currentPkg.type ?? "commonjs",
             "scripts": {
                 "dev": "vite",
-                "build": "tsc && vite build",
+                // No tsc here: the copy holds the whole workspace, and its server files import
+                // packages a browser build must not need. Typechecking is the job of 'cn validate'.
+                "build": "vite build",
                 "preview": "vite preview"
             },
             "dependencies": currentPkg.dependencies ?? {},
@@ -526,7 +447,8 @@ export default defineConfig({
             }
         }
         if (pgkJson.devDependencies['vite'] === undefined) {
-            pgkJson.devDependencies['vite'] = "^7.3.1";
+            // Vite 8: what @vitejs/plugin-react 6 declares as peer
+            pgkJson.devDependencies['vite'] = "^8.0.0";
         }
         else {
             ConsoleUtils_1.default.checkWarning(`Warning: Using custom Vite version: ${pgkJson.devDependencies['vite']}`);
@@ -539,6 +461,151 @@ export default defineConfig({
         }
         return pgkJson;
     }
+    /**
+     * Starts the Vite dev server of one app, with hot reload on the real sources of the project.
+     * Behind the command: cn react dev <app>
+     *
+     * Unlike {@link BuildUtils.buildReactApp}, nothing of the project is copied: the staging
+     * folder `.codenotch/<appName>-dev` only holds the generated files (package.json, index.html,
+     * index.jsx, vite.config.mjs), and the config aliases the app component to its real path in
+     * the workspace. Editing a project file is therefore picked up live by Vite.
+     *
+     * The `/api/env` endpoint the app reads at startup is served by the dev server itself,
+     * through a small plugin of the generated config: the page behaves like the served bundle.
+     *
+     * Dependencies are installed in the staging on the first run only; delete the folder
+     * (or run 'cn react clean <app>') to force a fresh install.
+     *
+     * Blocks until the server is stopped (Ctrl+C), and returns the exit code it left.
+     */
+    static async devReactApp(appFilePath, options) {
+        // resolve() already turns a relative path into an absolute one, based on the current directory
+        appFilePath = StringUtils_1.default.normalizePath((0, path_1.resolve)(appFilePath));
+        if ((0, fs_1.existsSync)(appFilePath) === false) {
+            console.log(chalk_1.default.red(`Error: File "${appFilePath}" not found`));
+            return 1;
+        }
+        let workspacePath = this.findWorkspaceFromFile(appFilePath) ?? '';
+        if (workspacePath === '' || (0, fs_1.existsSync)(workspacePath) === false) {
+            console.log(chalk_1.default.red(`Error: Could not find workspace manifest for file "${appFilePath}".`));
+            return 1;
+        }
+        // App manifest, named like the component
+        let appFilename = StringUtils_1.default.getFilenameFromUri(appFilePath);
+        let appManifestPath = StringUtils_1.default.normalizePath(`${StringUtils_1.default.getFolder(appFilePath)}/${appFilename.replace(/\.[^/.]+$/, '.manifest.json')}`);
+        if ((0, fs_1.existsSync)(appManifestPath) === false) {
+            console.log(chalk_1.default.red(`Error: App manifest file not found at "${appManifestPath}"`));
+            return 1;
+        }
+        let appManifest = JSON.parse(fs_2.default.readFileSync(appManifestPath, 'utf-8'));
+        let appName = `${appManifest.app?.name ?? ''}`.trim();
+        if (appName === '') {
+            console.log(chalk_1.default.red(`Error: App name not found in manifest at "${appManifestPath}"`));
+            return 1;
+        }
+        // Same environment as the one a built bundle reads, served by the dev server itself
+        let workspace = { manifest: this.getFullManifestAt(workspacePath), path: workspacePath };
+        let envVariables = await this.getCodenotchEnvVariables(workspace, {
+            appName: appName,
+            app: appManifest,
+            clusterUrl: options.clusterUrl
+        });
+        // Only generated files live in the staging: the sources stay, and are watched, in the workspace
+        let devDir = StringUtils_1.default.normalizePath(`${workspacePath}/.codenotch/${appName}-dev`);
+        console.log("Creating dev files...");
+        FileUtils_1.default.writeFileSync(devDir + '/package.json', JSON.stringify(this.createPkgJson(workspacePath, appName), null, 4));
+        FileUtils_1.default.writeFileSync(devDir + '/index.html', this.createIndexHtml(appManifest, appName));
+        FileUtils_1.default.writeFileSync(devDir + '/index.jsx', this.createIndexJsxDev());
+        FileUtils_1.default.writeFileSync(devDir + '/vite.config.mjs', this.createViteDevConfig(workspacePath, devDir, appFilePath, envVariables, options.port));
+        ConsoleUtils_1.default.check(`Dev files created in ${devDir}\n`);
+        // Vite 8 needs Node 20+: warn up front, its own error would be cryptic
+        const nodeMajor = parseInt(process.versions.node.split('.')[0], 10);
+        if (nodeMajor < 20) {
+            ConsoleUtils_1.default.checkWarning(`Node ${process.versions.node} detected, the dev server needs Node 20 or newer and may fail.`);
+        }
+        if ((0, fs_1.existsSync)(StringUtils_1.default.normalizePath(`${devDir}/node_modules`)) === false) {
+            console.log("Installing dependencies...");
+            const installCode = await ShellUtils_1.default.run(devDir, 'npm install --no-audit --no-fund');
+            if (installCode !== 0) {
+                console.log(chalk_1.default.red(`Error: npm install failed (exit code ${installCode}).`));
+                return installCode;
+            }
+        }
+        console.log(chalk_1.default.green(`Starting dev server for "${appName}" (hot reload on ${workspacePath})...`));
+        // Vite runs FROM the workspace: tailwind 4 scans its sources from the working directory,
+        // and the staging holds none of them. The config still points everything at the staging.
+        const devDirPosix = devDir.replaceAll('\\', '/');
+        const viteCommand = `node "${devDirPosix}/node_modules/vite/bin/vite.js" --config "${devDirPosix}/vite.config.mjs"`;
+        return await ShellUtils_1.default.run(workspacePath, viteCommand);
+    }
+    /** The dev entry: same contract as the built one, the app itself comes through the '@app' alias */
+    static createIndexJsxDev() {
+        return `
+import { createRoot } from 'react-dom/client';
+import App from '@app';
+import { init } from '@codenotch/codenotch.react';
+
+// The environment is exposed by the dev server (see the codenotch-env plugin of vite.config.mjs)
+const root = createRoot(document.getElementById('root'));
+fetch('/api/env')
+\t.then(response => response.json())
+\t.then(data => {
+\t\tinit(data);
+\t\troot.render(<App />);
+\t})
+\t.catch(error => {
+\t\tconsole.error('Error fetching environment variables:', error);
+\t\tinit({});
+\t\troot.render(<App />);
+\t});
+`.trim();
+    }
+    /**
+     * The dev flavoured Vite config: the app is aliased to its real file in the workspace so that
+     * hot reload watches the project sources, and a tiny plugin serves the Codenotch environment.
+     */
+    static createViteDevConfig(workspacePath, devDir, appFilePath, envVariables, port) {
+        const workspacePosix = workspacePath.replaceAll('\\', '/');
+        const devDirPosix = devDir.replaceAll('\\', '/');
+        const appFilePosix = appFilePath.replaceAll('\\', '/');
+        return `
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+// The same environment a built bundle reads from its .env, served here by the dev server
+const codenotchEnv = ${JSON.stringify(envVariables, null, 4)};
+
+export default defineConfig({
+    // The server is rooted here (index.html, node_modules), but runs from the workspace
+    root: ${JSON.stringify(devDirPosix)},
+    plugins: [
+        react(),
+        {
+            name: 'codenotch-env',
+            configureServer(server) {
+                server.middlewares.use('/api/env', (req, res) => {
+                    res.setHeader('Content-Type', 'application/json');
+                    res.end(JSON.stringify(codenotchEnv));
+                });
+            }
+        },
+    ],
+    resolve: {
+        alias: [
+            // The app is NOT copied here: it is loaded, and watched, from the workspace
+            { find: '@app', replacement: ${JSON.stringify(appFilePosix)} },
+        ],
+    },
+    server: {
+        port: ${port},
+        strictPort: true,
+        fs: {
+            // The sources live outside the vite root, in the workspace
+            allow: [${JSON.stringify(workspacePosix)}],
+        },
+    },
+})`.trim();
+    }
     static getFullManifestAt(folderPath) {
         let manifest = this.getManifestAt(folderPath);
         return manifest;