@nitronjs/framework 0.2.2 → 0.2.4

package/README.md

@@ -13,11 +13,13 @@ A modern full-stack Node.js framework with React Server Components, Islands Arch
 ## Installation
 
 ```bash
-npx @nitronjs/framework my-app
+npx -y @nitronjs/framework my-app
 cd my-app
 npm run dev
 ```
 
+> **Note:** The `-y` flag skips npm's confirmation prompt for a smoother experience.
+
 Your app will be running at `http://localhost:3000`
 
 ## Core Concepts

package/cli/create.js

@@ -18,64 +18,55 @@ const COLORS = {
     cyan: "\x1b[36m"
 };
 
-function log(message, color = COLORS.reset) {
-    console.log(`${color}${message}${COLORS.reset}`);
-}
+function getFrameworkVersion() {
+    const pkgPath = path.join(__dirname, "..", "package.json");
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
 
-function logStep(message, status = "pending") {
-    const icons = {
-        pending: `${COLORS.dim}○${COLORS.reset}`,
-        running: `${COLORS.yellow}◐${COLORS.reset}`,
-        success: `${COLORS.green}✓${COLORS.reset}`,
-        error: `${COLORS.red}✗${COLORS.reset}`
-    };
-    console.log(`  ${icons[status]} ${message}`);
+    return pkg.version;
 }
 
-function startSpinner(message) {
-    if (!process.stdout.isTTY) {
-        return () => {};
-    }
+function log(message, color = COLORS.reset) {
+    console.log(`${color}${message}${COLORS.reset}`);
+}
 
-    const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
-    let i = 0;
-    const line = () => `  ${COLORS.yellow}${frames[i]}${COLORS.reset} ${message}`;
-
-    process.stdout.write(line());
-    const timer = setInterval(() => {
-        i = (i + 1) % frames.length;
-        process.stdout.write(`\r${line()}`);
-    }, 120);
-
-    return () => {
-        clearInterval(timer);
-        process.stdout.write(`\r${" ".repeat(message.length + 4)}\r`);
-    };
+function logStep(icon, message) {
+    console.log(`  ${icon} ${message}`);
 }
 
 function printBanner() {
+    const version = getFrameworkVersion();
+    const versionText = `v${version}`;
+    const logoWidth = 66;
+    const versionLine = `${COLORS.dim}───${COLORS.reset} ${COLORS.bold}${versionText} ${COLORS.dim}───${COLORS.reset}`;
+    const versionTextLength = 3 + 1 + versionText.length + 1 + 3;
+    const innerWidth = logoWidth - 2;
+    const versionPadding = Math.floor((innerWidth - versionTextLength) / 2);
+    
     console.log();
-    log("███╗   ██╗██╗████████╗██████╗  ██████╗ ███╗   ██╗     ██╗███████╗", COLORS.cyan);
-    log("████╗  ██║██║╚══██╔══╝██╔══██╗██╔═══██╗████╗  ██║     ██║██╔════╝", COLORS.cyan);
-    log("██╔██╗ ██║██║   ██║   ██████╔╝██║   ██║██╔██╗ ██║     ██║███████╗", COLORS.cyan);
-    log("██║╚██╗██║██║   ██║   ██╔══██╗██║   ██║██║╚██╗██║██   ██║╚════██║", COLORS.cyan);
-    log("██║ ╚████║██║   ██║   ██║  ██║╚██████╔╝██║ ╚████║╚█████╔╝███████║", COLORS.cyan);
-    log("╚═╝  ╚═══╝╚═╝   ╚═╝   ╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═══╝ ╚════╝ ╚══════╝", COLORS.cyan);
+    console.log(`${COLORS.green}███╗   ██╗██╗████████╗██████╗  ██████╗ ███╗   ██╗     ██╗███████╗${COLORS.reset}`);
+    console.log(`${COLORS.green}████╗  ██║██║╚══██╔══╝██╔══██╗██╔═══██╗████╗  ██║     ██║██╔════╝${COLORS.reset}`);
+    console.log(`${COLORS.green}██╔██╗ ██║██║   ██║   ██████╔╝██║   ██║██╔██╗ ██║     ██║███████╗${COLORS.reset}`);
+    console.log(`${COLORS.green}██║╚██╗██║██║   ██║   ██╔══██╗██║   ██║██║╚██╗██║██   ██║╚════██║${COLORS.reset}`);
+    console.log(`${COLORS.green}██║ ╚████║██║   ██║   ██║  ██║╚██████╔╝██║ ╚████║╚█████╔╝███████║${COLORS.reset}`);
+    console.log(`${COLORS.green}╚═╝  ╚═══╝╚═╝   ╚═╝   ╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═══╝ ╚════╝ ╚══════╝${COLORS.reset}`);
+    console.log(`${COLORS.green}┌${"─".repeat(innerWidth)}┐${COLORS.reset}`);
+    console.log(`${COLORS.green}│${COLORS.reset}${" ".repeat(versionPadding)}${versionLine}${" ".repeat(innerWidth - versionPadding - versionTextLength)}${COLORS.green}│${COLORS.reset}`);
+    console.log(`${COLORS.green}└${"─".repeat(innerWidth)}┘${COLORS.reset}`);
     console.log();
 }
 
 function printHelp() {
     console.log(`
 ${COLORS.bold}Usage:${COLORS.reset}
-  npx nitronjs <project-name>
+  npx @nitronjs/framework <project-name>
 
 ${COLORS.bold}Arguments:${COLORS.reset}
   project-name    Name of the project directory to create
 
 ${COLORS.bold}Examples:${COLORS.reset}
-  ${COLORS.cyan}npx nitronjs my-app${COLORS.reset}
-  ${COLORS.cyan}npx nitronjs blog${COLORS.reset}
-  ${COLORS.cyan}npx nitronjs e-commerce${COLORS.reset}
+  ${COLORS.cyan}npx @nitronjs/framework my-app${COLORS.reset}
+  ${COLORS.cyan}npx @nitronjs/framework blog${COLORS.reset}
+  ${COLORS.cyan}npx @nitronjs/framework e-commerce${COLORS.reset}
 
 ${COLORS.bold}Project name rules:${COLORS.reset}
   - Can contain letters, numbers, hyphens, and underscores
@@ -122,7 +113,8 @@ function copyDir(src, dest) {
 
         if (entry.isDirectory()) {
             fileCount += copyDir(srcPath, destPath);
-        } else {
+        }
+        else {
             fs.copyFileSync(srcPath, destPath);
             fileCount++;
         }
@@ -135,12 +127,6 @@ function generateAppKey() {
     return crypto.randomBytes(32).toString("base64");
 }
 
-function getFrameworkVersion() {
-    const pkgPath = path.join(__dirname, "..", "package.json");
-    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
-    return pkg.version;
-}
-
 function updatePackageJson(projectPath, projectName) {
     const pkgPath = path.join(projectPath, "package.json");
 
@@ -168,20 +154,31 @@ function updateEnvFile(projectPath) {
     }
 }
 
-function runNpmInstall(projectPath) {
+function runNpmInstall(projectPath, onProgress) {
     return new Promise((resolve, reject) => {
         const isWindows = process.platform === "win32";
         const npm = isWindows ? (process.env.ComSpec || "cmd.exe") : "npm";
         const npmArgs = isWindows ? ["/d", "/s", "/c", "npm", "install"] : ["install"];
-        
+
         const child = spawn(npm, npmArgs, {
             cwd: projectPath,
             stdio: ["ignore", "pipe", "pipe"]
         });
 
         let output = "";
+        let packageCount = 0;
+
         child.stdout.on("data", (data) => {
             output += data.toString();
+            const matches = data.toString().match(/added (\d+) packages/);
+
+            if (matches) {
+                packageCount = parseInt(matches[1]);
+            }
+
+            if (onProgress) {
+                onProgress(data.toString());
+            }
         });
 
         child.stderr.on("data", (data) => {
@@ -190,27 +187,30 @@ function runNpmInstall(projectPath) {
 
         child.on("close", (code) => {
             if (code === 0) {
-                resolve();
-            } else {
+                resolve(packageCount);
+            }
+            else {
                 const error = new Error(`npm install failed with code ${code}`);
                 error.output = output.trim();
                 reject(error);
             }
         });
 
-        child.on("error", (err) => {
-            reject(err);
-        });
+        child.on("error", reject);
     });
 }
 
 function printSuccess(projectName) {
+    const logoWidth = 66;
+    const innerWidth = logoWidth - 2;
+    const stripAnsi = str => str.replace(/\x1b\[[0-9;]*m/g, "");
+    const pad = (content, length) => content + " ".repeat(Math.max(0, length - stripAnsi(content).length));
+    const successText = `${COLORS.green}${COLORS.bold}✓${COLORS.reset} ${COLORS.bold}Project created successfully!${COLORS.reset}`;
+
     console.log();
-    log("╔══════════════════════════════════════════════════════════════╗", COLORS.green);
-    log("║                                                              ║", COLORS.green);
-    log("║   ✓ Project created successfully!                           ║", COLORS.green);
-    log("║                                                              ║", COLORS.green);
-    log("╚══════════════════════════════════════════════════════════════╝", COLORS.green);
+    console.log(`${COLORS.green}┌${"─".repeat(innerWidth)}┐${COLORS.reset}`);
+    console.log(`${COLORS.green}│${COLORS.reset} ${pad(successText, innerWidth - 2)} ${COLORS.green}│${COLORS.reset}`);
+    console.log(`${COLORS.green}└${"─".repeat(innerWidth)}┘${COLORS.reset}`);
     console.log();
 
     log(`${COLORS.bold}Next steps:${COLORS.reset}`);
@@ -239,16 +239,18 @@ function printSuccess(projectName) {
 export default async function create(projectName, options = {}) {
     if (options.help || projectName === "--help" || projectName === "-h") {
         printHelp();
+
         return;
     }
 
     printBanner();
 
     const validation = validateProjectName(projectName);
+
     if (!validation.valid) {
         log(`${COLORS.red}Error: ${validation.error}${COLORS.reset}`);
         console.log();
-        log(`${COLORS.dim}Run 'npx nitronjs --help' for usage information${COLORS.reset}`);
+        log(`${COLORS.dim}Run 'npx @nitronjs/framework --help' for usage information${COLORS.reset}`);
         process.exit(1);
     }
 
@@ -270,30 +272,44 @@ export default async function create(projectName, options = {}) {
     log(`${COLORS.bold}Creating project: ${COLORS.cyan}${projectName}${COLORS.reset}`);
     console.log();
 
-    logStep("Copying project files...", "running");
+    logStep(`${COLORS.yellow}◐${COLORS.reset}`, "Copying project files...");
     const fileCount = copyDir(SKELETON_DIR, projectPath);
-    logStep(`Copied ${fileCount} files`, "success");
+    process.stdout.write("\x1b[1A\x1b[2K");
+    logStep(`${COLORS.green}✓${COLORS.reset}`, `Copied ${fileCount} files`);
 
-    logStep("Configuring package.json...", "running");
+    logStep(`${COLORS.yellow}◐${COLORS.reset}`, "Configuring package.json...");
     updatePackageJson(projectPath, projectName);
-    logStep("Package configured", "success");
+    process.stdout.write("\x1b[1A\x1b[2K");
+    logStep(`${COLORS.green}✓${COLORS.reset}`, "Package configured");
 
-    logStep("Generating APP_KEY...", "running");
+    logStep(`${COLORS.yellow}◐${COLORS.reset}`, "Generating APP_KEY...");
     updateEnvFile(projectPath);
-    logStep("APP_KEY generated", "success");
+    process.stdout.write("\x1b[1A\x1b[2K");
+    logStep(`${COLORS.green}✓${COLORS.reset}`, "APP_KEY generated");
+
+    const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+    let frameIndex = 0;
+
+    const spinner = setInterval(() => {
+        frameIndex = (frameIndex + 1) % frames.length;
+        process.stdout.write(`\r  ${COLORS.yellow}${frames[frameIndex]}${COLORS.reset} Installing dependencies...`);
+    }, 80);
 
-    logStep("Installing dependencies (this may take a moment)...", "running");
-    const stopSpinner = startSpinner("Installing dependencies...");
     try {
         await runNpmInstall(projectPath);
-        stopSpinner();
-        logStep("Dependencies installed", "success");
-    } catch (error) {
-        stopSpinner();
-        logStep("Failed to install dependencies", "error");
+        clearInterval(spinner);
+        process.stdout.write("\r\x1b[2K");
+        logStep(`${COLORS.green}✓${COLORS.reset}`, "Dependencies installed");
+    }
+    catch (error) {
+        clearInterval(spinner);
+        process.stdout.write("\r\x1b[2K");
+        logStep(`${COLORS.red}✗${COLORS.reset}`, "Failed to install dependencies");
+
         if (error.output) {
             log(`${COLORS.dim}${error.output}${COLORS.reset}`);
         }
+
         log(`${COLORS.yellow}Please run 'npm install' manually in the project directory${COLORS.reset}`);
     }
 

package/cli/njs.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 const COLORS = {
     reset: "\x1b[0m",
@@ -32,10 +32,8 @@ ${COLORS.bold}Database:${COLORS.reset}
   ${COLORS.cyan}njs migrate:status${COLORS.reset}        Show the status of each migration
   ${COLORS.cyan}njs migrate:fresh${COLORS.reset}         Drop all tables and re-migrate
   ${COLORS.cyan}njs migrate:fresh --seed${COLORS.reset}  Fresh migrate with seeders
-  ${COLORS.cyan}njs seed${COLORS.reset}                  Run prod seeders
-  ${COLORS.cyan}njs seed --dev${COLORS.reset}            Run dev seeders
-  ${COLORS.cyan}njs seed --all${COLORS.reset}            Run all seeders (prod + dev)
-  ${COLORS.cyan}njs seed --status${COLORS.reset}         Show the status of each seeder
+  ${COLORS.cyan}njs seed${COLORS.reset}                  Run all seeders
+  ${COLORS.cyan}njs seed <Name>${COLORS.reset}           Run a specific seeder
 
 ${COLORS.bold}Generators:${COLORS.reset}
   ${COLORS.cyan}njs make:controller${COLORS.reset}       Create a new controller
@@ -110,7 +108,8 @@ async function run() {
 
             case "migrate": {
                 const { default: Migrate } = await import("../lib/Console/Commands/MigrateCommand.js");
-                await Migrate({ seed: additionalArgs.includes("--seed") });
+                const success = await Migrate({ seed: additionalArgs.includes("--seed") });
+                process.exit(success ? 0 : 1);
                 break;
             }
 
@@ -119,39 +118,37 @@ async function run() {
                 const stepArg = additionalArgs.find(arg => arg.startsWith('--step='));
                 const step = stepArg ? parseInt(stepArg.split('=')[1], 10) : 1;
                 const all = additionalArgs.includes('--all');
-                await Rollback({ step, all });
+                const success = await Rollback({ step, all });
+                process.exit(success ? 0 : 1);
                 break;
             }
 
             case "migrate:status": {
                 const { default: Status } = await import("../lib/Console/Commands/MigrateStatusCommand.js");
                 await Status();
+                process.exit(0);
                 break;
             }
 
             case "migrate:fresh": {
                 const { default: MigrateFresh } = await import("../lib/Console/Commands/MigrateFreshCommand.js");
-                await MigrateFresh({ seed: additionalArgs.includes("--seed") });
+                const success = await MigrateFresh({ seed: additionalArgs.includes("--seed") });
+                process.exit(success ? 0 : 1);
                 break;
             }
 
             case "seed": {
                 const { default: Seed } = await import("../lib/Console/Commands/SeedCommand.js");
-                const showStatus = additionalArgs.includes('--status');
-                const isDev = additionalArgs.includes('--dev');
-                const isAll = additionalArgs.includes('--all');
-
-                let environment = 'prod';
-                if (isDev) environment = 'dev';
-                if (isAll) environment = 'all';
-
-                await Seed({ environment, status: showStatus });
+                const seederName = additionalArgs.find(a => !a.startsWith('--')) || null;
+                const success = await Seed(seederName);
+                process.exit(success ? 0 : 1);
                 break;
             }
 
             case "storage:link": {
                 const { default: StorageLink } = await import("../lib/Console/Commands/StorageLinkCommand.js");
-                await StorageLink();
+                const success = await StorageLink();
+                process.exit(success ? 0 : 1);
                 break;
             }
 
@@ -171,7 +168,8 @@ async function run() {
                 }
 
                 const { default: Make } = await import("../lib/Console/Commands/MakeCommand.js");
-                await Make(type, name);
+                const success = await Make(type, name);
+                process.exit(success ? 0 : 1);
                 break;
             }
 

package/lib/Auth/Auth.js

@@ -0,0 +1,167 @@
+import Hash from "../Hashing/Hash.js";
+import Config from "../Core/Config.js";
+
+/**
+ * Authentication manager for handling user login, logout, and session management.
+ * Supports multiple authentication guards for different user types (admin, user, etc.)
+ */
+class Auth {
+    /**
+     * Sets up authentication hooks on the Fastify server.
+     * Decorates requests with auth helper methods.
+     * @param {import("fastify").FastifyInstance} server - Fastify server instance
+     */
+    static setup(server) {
+        server.decorateRequest("auth", null);
+
+        server.addHook("onRequest", async (req, res) => {
+            req.auth = {
+                guard: (guardName = null) => ({
+                    attempt: (credentials) => Auth.attempt(req, credentials, guardName),
+                    logout: () => Auth.logout(req, guardName),
+                    user: () => Auth.user(req, guardName),
+                    check: () => Auth.check(req, guardName),
+                    home: () => Auth.home(res, guardName),
+                    redirect: () => Auth.redirect(res, guardName)
+                }),
+                attempt: (credentials) => Auth.attempt(req, credentials, null),
+                logout: () => Auth.logout(req, null),
+                user: () => Auth.user(req, null),
+                check: () => Auth.check(req, null),
+                home: () => Auth.home(res, null),
+                redirect: () => Auth.redirect(res, null)
+            };
+        });
+    }
+
+    /**
+     * Attempts to authenticate a user with the given credentials.
+     * @param {import("fastify").FastifyRequest} req - Fastify request object
+     * @param {Object} credentials - Login credentials (identifier + password)
+     * @param {string|null} guardName - Optional guard name
+     * @returns {Promise<boolean>} True if authentication successful
+     */
+    static async attempt(req, credentials, guardName = null) {
+        const authConfig = Config.all("auth");
+        const guard = guardName || authConfig.defaults.guard;
+        const config = authConfig.guards[guard];
+
+        if (!config) {
+            throw new Error(`Guard "${guard}" not configured`);
+        }
+
+        const { provider, identifier } = config;
+
+        const user = await provider
+            .where(identifier, "=", credentials[identifier])
+            .first();
+
+        if (!user) {
+            return false;
+        }
+
+        const isValid = await Hash.check(credentials.password, user.password);
+
+        if (!isValid) {
+            return false;
+        }
+
+        req.session.regenerate();
+        req.session.set(`auth_${guard}`, user.id);
+
+        return true;
+    }
+
+    /**
+     * Logs out the current user by clearing the session.
+     * @param {import("fastify").FastifyRequest} req - Fastify request object
+     * @param {string|null} guardName - Optional guard name
+     */
+    static logout(req, guardName = null) {
+        const authConfig = Config.all("auth");
+        const guard = guardName || authConfig.defaults.guard;
+
+        req.session.set(`auth_${guard}`, null);
+    }
+
+    /**
+     * Gets the currently authenticated user.
+     * @param {import("fastify").FastifyRequest} req - Fastify request object
+     * @param {string|null} guardName - Optional guard name
+     * @returns {Promise<Object|null>} User model instance or null
+     */
+    static async user(req, guardName = null) {
+        const authConfig = Config.all("auth");
+        const guard = guardName || authConfig.defaults.guard;
+        const config = authConfig.guards[guard];
+        const userId = req.session.get(`auth_${guard}`) || null;
+
+        if (!userId || !config) {
+            return null;
+        }
+
+        return await config.provider.find(userId);
+    }
+
+    /**
+     * Checks if a user is currently authenticated.
+     * @param {import("fastify").FastifyRequest} req - Fastify request object
+     * @param {string|null} guardName - Optional guard name
+     * @returns {boolean} True if user is authenticated
+     */
+    static check(req, guardName = null) {
+        const authConfig = Config.all("auth");
+        const guard = guardName || authConfig.defaults.guard;
+        const value = req.session.get(`auth_${guard}`);
+
+        return value !== null && value !== undefined;
+    }
+
+    /**
+     * Redirects to the authenticated user's home page.
+     * @param {import("fastify").FastifyReply} res - Fastify response object
+     * @param {string|null} guardName - Optional guard name
+     * @returns {import("fastify").FastifyReply} Redirect response
+     */
+    static home(res, guardName = null) {
+        const authConfig = Config.all("auth");
+        const guard = guardName || authConfig.defaults.guard;
+        const config = authConfig.guards[guard];
+        const path = config?.home;
+
+        if (!path) {
+            return res.redirect("/");
+        }
+
+        if (path.startsWith("/") || path.startsWith("http://") || path.startsWith("https://")) {
+            return res.redirect(path);
+        }
+
+        return res.redirect(route(path));
+    }
+
+    /**
+     * Redirects to the login page for unauthenticated users.
+     * @param {import("fastify").FastifyReply} res - Fastify response object
+     * @param {string|null} guardName - Optional guard name
+     * @returns {import("fastify").FastifyReply} Redirect response
+     */
+    static redirect(res, guardName = null) {
+        const authConfig = Config.all("auth");
+        const guard = guardName || authConfig.defaults.guard;
+        const config = authConfig.guards[guard];
+        const path = config?.redirect;
+
+        if (!path) {
+            return res.redirect("/");
+        }
+
+        if (path.startsWith("/") || path.startsWith("http://") || path.startsWith("https://")) {
+            return res.redirect(path);
+        }
+
+        return res.redirect(route(path));
+    }
+}
+
+export default Auth;

package/lib/Build/CssBuilder.js

@@ -4,6 +4,10 @@ import crypto from "crypto";
 import postcss from "postcss";
 import tailwindPostcss from "@tailwindcss/postcss";
 
+/**
+ * Handles CSS file building with Tailwind CSS support.
+ * Processes CSS files, handles caching, and detects Tailwind usage.
+ */
 class CssBuilder {
     #cache;
     #isDev;
@@ -18,6 +22,11 @@ class CssBuilder {
         this.#cssOutput = cssOutput;
     }
 
+    /**
+     * Builds all CSS files in the input directory.
+     * @param {boolean} viewsChanged - Whether views have changed (forces Tailwind rebuild).
+     * @returns {Promise<number>} Number of CSS files processed.
+     */
     async build(viewsChanged) {
         if (!fs.existsSync(this.#cssInput)) {
             return 0;

package/lib/Build/FileAnalyzer.js

@@ -6,6 +6,7 @@ import Paths from "../Core/Paths.js";
 import Layout from "../View/Layout.js";
 import COLORS from "./colors.js";
 
+/** React hooks that indicate a client component. */
 const CLIENT_HOOKS = new Set([
     "useState",
     "useEffect",
@@ -16,8 +17,13 @@ const CLIENT_HOOKS = new Set([
     "useMemo"
 ]);
 
+/** Maximum depth for dependency resolution to prevent infinite loops. */
 const MAX_DEPTH = 50;
 
+/**
+ * Analyzes TSX files to determine component types and dependencies.
+ * Detects client components, extracts imports, and builds dependency graphs.
+ */
 class FileAnalyzer {
     #traverse = traverse.default;
     #cache;
@@ -26,6 +32,11 @@ class FileAnalyzer {
         this.#cache = cache;
     }
 
+    /**
+     * Discovers entry points and layouts in a directory.
+     * @param {string} baseDir - Directory to scan for TSX files.
+     * @returns {{entries: string[], layouts: string[], meta: Map<string, object>}}
+     */
     discoverEntries(baseDir) {
         if (!fs.existsSync(baseDir)) {
             return { entries: [], layouts: [], meta: new Map() };
@@ -104,6 +115,11 @@ class FileAnalyzer {
         return { graph, imported, importedBy };
     }
 
+    /**
+     * Analyzes a single TSX file for metadata.
+     * @param {string} filePath - Path to the TSX file.
+     * @returns {{imports: Set<string>, css: Set<string>, hasDefault: boolean, named: string[], jsx: boolean, needsClient: boolean, isClient: boolean}}
+     */
     analyzeFile(filePath) {
         const stat = fs.statSync(filePath);
         const mtime = stat.mtimeMs;

package/lib/Build/HydrationBuilder.js

@@ -4,10 +4,19 @@ import crypto from "crypto";
 import Paths from "../Core/Paths.js";
 import Layout from "../View/Layout.js";
 
+/**
+ * Sanitizes a name to be a valid JavaScript identifier.
+ * @param {string} name - The name to sanitize.
+ * @returns {string} A valid JS identifier.
+ */
 function sanitizeName(name) {
     return name.replace(/[^a-zA-Z0-9_$]/g, "_");
 }
 
+/**
+ * Generates hydration scripts for client-side component rendering.
+ * Creates island bundles for React components that need client interactivity.
+ */
 class HydrationBuilder {
     #cache;
     #isDev;
@@ -21,6 +30,14 @@ class HydrationBuilder {
         this.#analyzer = analyzer;
     }
 
+    /**
+     * Builds hydration bundles for client components.
+     * @param {object} userBundle - User view bundle.
+     * @param {object} frameworkBundle - Framework view bundle.
+     * @param {object} manifest - Build manifest.
+     * @param {Set<string>|null} changedViews - Changed view files or null for full build.
+     * @returns {Promise<Array<{input: string, output: string}>>}
+     */
     async build(userBundle, frameworkBundle, manifest, changedViews = null) {
         const hydrationFiles = [];
         const allChangedFiles = new Set();

package/lib/Build/Manager.js

@@ -24,6 +24,14 @@ import COLORS from "./colors.js";
 
 dotenv.config({ quiet: true });
 
+/**
+ * Main build orchestrator for NitronJS applications.
+ * Compiles views, CSS, and hydration bundles with caching support.
+ * 
+ * @example
+ * const builder = new Builder();
+ * await builder.run(null, true, false); // Dev build with output
+ */
 class Builder {
     #isDev = false;
     #manifest = {};
@@ -69,6 +77,13 @@ class Builder {
         this.#hydrationBuilder = new HydrationBuilder(this.#cache, this.#isDev, this.#paths.templates, this.#analyzer);
     }
 
+    /**
+     * Runs the build process.
+     * @param {string|null} only - Build only "views" or "css", or null for full build.
+     * @param {boolean} isDev - Whether in development mode.
+     * @param {boolean} silent - Whether to suppress console output.
+     * @returns {Promise<{success: boolean, changedFiles?: string[], error?: string, time?: number}>}
+     */
     async run(only = null, isDev = false, silent = false) {
         this.#isDev = isDev;
         Environment.setDev(isDev);