create-aziz-app 3.1.2 → 3.1.3

package/template/docs/01-getting-started.md

@@ -1,151 +1,151 @@
-# 01 · Getting Started
-
-From zero to a running Aziz.js app in a few minutes.
-
-## Prerequisites
-
-- **Node.js 18+** (20 LTS or newer recommended)
-- **npm** (ships with Node)
-
-Check:
-
-```bash
-node -v
-npm -v
-```
-
-## Create a project
-
-```bash
-npx create-aziz-app my-app
-```
-
-The CLI walks you through a few choices:
-
-```
-📁 Project name (my-aziz-js-app): my-app
-🌐 Dev server port (3000):
-   Include example pages? (Y/n):
-   Include example API routes? (Y/n):
-   Include documentation? (Y/n):
-
-🎨 CSS Framework:
-   1. None (custom CSS)
-   2. Bootstrap 5
-   3. Tailwind CSS
-   Choose (1/2/3):
-```
-
-### Flags (skip the prompts)
-
-Every prompt has a flag, so CI and scripts can run non-interactively:
-
-```bash
-npx create-aziz-app my-app -y                 # accept all defaults
-npx create-aziz-app shop --css tailwind       # preselect CSS
-npx create-aziz-app blog --port 4000          # change the default port
-npx create-aziz-app min --no-examples --no-api --no-docs
-npx create-aziz-app --help
-```
-
-| Flag | Meaning |
-|------|---------|
-| `-y`, `--yes` | Accept defaults, no prompts |
-| `--port <n>` | Default dev-server port (3000) |
-| `--css <name>` | `none` \| `bootstrap` \| `tailwind` |
-| `--no-examples` | Skip the example `app/test` page |
-| `--no-api` | Empty the example `api/` routes |
-| `--no-docs` | Don't copy `docs/` |
-
-## Install and run
-
-```bash
-cd my-app
-npm install      # installs @babel/standalone (used for JSX) + any deps you add
-npm run dev
-```
-
-Open **<http://localhost:3000>**. You should see the home page with a working counter.
-
-The dev server watches your files and pushes a **live reload** to the browser whenever you save — no manual refresh.
-
-## npm scripts
-
-Defined in your project's `package.json`:
-
-```json
-{
-  "scripts": {
-    "dev":   "node scripts/dev-server.js",
-    "build": "node scripts/dev-server.js --production",
-    "start": "node scripts/dev-server.js --production",
-    "test":  "node --test"
-  }
-}
-```
-
-- `npm run dev` — development server with live reload and no caching.
-- `npm run build` / `npm start` — the same server in **production mode**: no live-reload socket, cache headers enabled. (Aziz.js has no bundling step; it serves your source compiled on demand and caches by file mtime.)
-- `npm test` — runs any `**/*.test.js` files via Node's built-in test runner. With no tests present it exits 0.
-
-## Your first page
-
-Create `app/hello/page.js`:
-
-```js
-// app/hello/page.js  →  /hello
-export default function Hello() {
-    const [name, setName] = useState('');
-
-    return (
-        <div style={{ padding: '40px' }}>
-            <h1>Hello 👋</h1>
-            <input
-                value={name}
-                onInput={e => setName(e.target.value)}
-                placeholder="Your name"
-            />
-            <p>{name ? `Hi, ${name}!` : 'Type something…'}</p>
-        </div>
-    );
-}
-```
-
-Save. The browser reloads and you're at **<http://localhost:3000/hello>**.
-
-Note: **you didn't import React or any hooks.** `useState`, `h` (the JSX factory), and the router are exposed globally by the framework. See [Hooks](./05-hooks.md).
-
-## Your first API route
-
-Create `api/greeting.js`:
-
-```js
-// api/greeting.js  →  /api/greeting
-module.exports = {
-    GET: async (request) => {
-        const name = request.query.get('name') || 'world';
-        return { hello: name };
-    },
-};
-```
-
-Visit **<http://localhost:3000/api/greeting?name=Aziz>** and you get JSON:
-
-```json
-{ "hello": "Aziz" }
-```
-
-Call it from a page with the global client:
-
-```js
-const data = await api.get('/api/greeting?name=Aziz');
-console.log(data.hello); // "Aziz"
-```
-
-See [API Routes](./06-api-routes.md) and [API Client](./07-api-client.md).
-
-## Next steps
-
-1. Understand the folder layout → [Project Structure](./02-project-structure.md)
-2. Build real screens → [Pages & Layouts](./03-pages-and-layouts.md)
-3. Master routes → [Routing](./04-routing.md)
+# 01 · Getting Started
+
+From zero to a running Aziz.js app in a few minutes.
+
+## Prerequisites
+
+- **Node.js 18+** (20 LTS or newer recommended)
+- **npm** (ships with Node)
+
+Check:
+
+```bash
+node -v
+npm -v
+```
+
+## Create a project
+
+```bash
+npx create-aziz-app my-app
+```
+
+The CLI walks you through a few choices:
+
+```
+📁 Project name (my-aziz-js-app): my-app
+🌐 Dev server port (3000):
+   Include example pages? (Y/n):
+   Include example API routes? (Y/n):
+   Include documentation? (Y/n):
+
+🎨 CSS Framework:
+   1. None (custom CSS)
+   2. Bootstrap 5
+   3. Tailwind CSS
+   Choose (1/2/3):
+```
+
+### Flags (skip the prompts)
+
+Every prompt has a flag, so CI and scripts can run non-interactively:
+
+```bash
+npx create-aziz-app my-app -y                 # accept all defaults
+npx create-aziz-app shop --css tailwind       # preselect CSS
+npx create-aziz-app blog --port 4000          # change the default port
+npx create-aziz-app min --no-examples --no-api --no-docs
+npx create-aziz-app --help
+```
+
+| Flag | Meaning |
+|------|---------|
+| `-y`, `--yes` | Accept defaults, no prompts |
+| `--port <n>` | Default dev-server port (3000) |
+| `--css <name>` | `none` \| `bootstrap` \| `tailwind` |
+| `--no-examples` | Skip the example `app/test` page |
+| `--no-api` | Empty the example `api/` routes |
+| `--no-docs` | Don't copy `docs/` |
+
+## Install and run
+
+```bash
+cd my-app
+npm install      # installs @babel/standalone (used for JSX) + any deps you add
+npm run dev
+```
+
+Open **<http://localhost:3000>**. You should see the home page with a working counter.
+
+The dev server watches your files and pushes a **live reload** to the browser whenever you save — no manual refresh.
+
+## npm scripts
+
+Defined in your project's `package.json`:
+
+```json
+{
+  "scripts": {
+    "dev":   "node scripts/dev-server.js",
+    "build": "node scripts/dev-server.js --production",
+    "start": "node scripts/dev-server.js --production",
+    "test":  "node --test"
+  }
+}
+```
+
+- `npm run dev` — development server with live reload and no caching.
+- `npm run build` / `npm start` — the same server in **production mode**: no live-reload socket, cache headers enabled. (Aziz.js has no bundling step; it serves your source compiled on demand and caches by file mtime.)
+- `npm test` — runs any `**/*.test.js` files via Node's built-in test runner. With no tests present it exits 0.
+
+## Your first page
+
+Create `app/hello/page.js`:
+
+```js
+// app/hello/page.js  →  /hello
+export default function Hello() {
+    const [name, setName] = useState('');
+
+    return (
+        <div style={{ padding: '40px' }}>
+            <h1>Hello 👋</h1>
+            <input
+                value={name}
+                onInput={e => setName(e.target.value)}
+                placeholder="Your name"
+            />
+            <p>{name ? `Hi, ${name}!` : 'Type something…'}</p>
+        </div>
+    );
+}
+```
+
+Save. The browser reloads and you're at **<http://localhost:3000/hello>**.
+
+Note: **you didn't import React or any hooks.** `useState`, `h` (the JSX factory), and the router are exposed globally by the framework. See [Hooks](./05-hooks.md).
+
+## Your first API route
+
+Create `api/greeting.js`:
+
+```js
+// api/greeting.js  →  /api/greeting
+module.exports = {
+    GET: async (request) => {
+        const name = request.query.get('name') || 'world';
+        return { hello: name };
+    },
+};
+```
+
+Visit **<http://localhost:3000/api/greeting?name=Aziz>** and you get JSON:
+
+```json
+{ "hello": "Aziz" }
+```
+
+Call it from a page with the global client:
+
+```js
+const data = await api.get('/api/greeting?name=Aziz');
+console.log(data.hello); // "Aziz"
+```
+
+See [API Routes](./06-api-routes.md) and [API Client](./07-api-client.md).
+
+## Next steps
+
+1. Understand the folder layout → [Project Structure](./02-project-structure.md)
+2. Build real screens → [Pages & Layouts](./03-pages-and-layouts.md)
+3. Master routes → [Routing](./04-routing.md)

package/template/docs/02-project-structure.md

@@ -1,109 +1,109 @@
-# 02 · Project Structure
-
-Every folder in a generated Aziz.js app, and what goes in it.
-
-```
-my-app/
-├── index.html              ← entry point (loaded first, then the router takes over)
-├── package.json            ← name, scripts, dependencies
-│
-├── app/                    ← PAGES + LAYOUTS (file-based routing)
-│   ├── layout.js           ← root layout, wraps every page
-│   ├── page.js             ← route: /
-│   ├── not-found.js        ← custom 404 screen
-│   ├── about/
-│   │   └── page.js         ← route: /about
-│   └── blog/
-│       └── [slug]/
-│           └── page.js     ← route: /blog/:slug  (dynamic)
-│
-├── api/                    ← SERVER-SIDE API ROUTES (Node.js)
-│   ├── hello.js            ← /api/hello
-│   └── users.js            ← /api/users
-│
-├── components/             ← shared UI components
-│   ├── Navbar.js
-│   └── Footer.js
-│
-├── lib/                    ← utilities, DB connections, helpers
-│   └── db.js
-├── models/                 ← data models / schema definitions
-│   └── User.js
-├── styles/                 ← CSS
-│   └── globals.css
-│
-├── _framework/             ← the framework itself (don't edit casually)
-│   ├── runtime.js          ← h(), fibers, DOM materialization
-│   ├── hooks.js            ← useState, useEffect, …
-│   ├── router.js           ← client router, Link, navigation
-│   ├── route-match.js      ← path matching / layout collection
-│   ├── api.js              ← browser API client (api.get, …)
-│   ├── next-response.js    ← NextResponse for API routes
-│   └── boot.js             ← boot sequence, exposes globals
-│
-├── scripts/                ← dev server + tooling
-│   ├── dev-server.js       ← the HTTP server (dev + production)
-│   ├── live-reload-client.js
-│   └── lib/                ← js-transform, module-resolver, api-router
-│
-└── docs/                   ← these guides (optional, --no-docs to skip)
-```
-
-## The two "worlds"
-
-Aziz.js runs code in two places. Confusing them is the #1 beginner mistake.
-
-| | **Browser** (`app/`, `components/`) | **Server** (`api/`, `lib/`, `models/`) |
-|--|-------------------------------------|-----------------------------------------|
-| Runs in | the browser | Node.js |
-| Module system | ES modules (`import` / `export`) | CommonJS (`require`) or `.mjs` ESM |
-| Imports | `/…`, `@/…`, bare npm → `/_modules/…` | normal Node resolution |
-| Framework | `h`, hooks, router, `api` client | `NextResponse`, `require('../_framework/…')` |
-| Can touch | DOM, `window` | filesystem, DB, env vars, secrets |
-
-- **Pages and components** are compiled (JSX → `h()` calls) and sent to the browser.
-- **API routes** are loaded by the dev server in Node and executed per request.
-
-### Why API files use `require`
-
-`api/*.js` files run in Node with the CommonJS loader, so you `require`:
-
-```js
-const { NextResponse } = require('../_framework/next-response');
-```
-
-If you prefer native ESM on the server, name the file `.mjs` and use `export`:
-
-```js
-// api/todos.mjs
-import { NextResponse } from '../_framework/next-response.js';
-
-export async function GET() {
-    return NextResponse.json({ todos: [] });
-}
-```
-
-Both styles are supported — see [API Routes](./06-api-routes.md).
-
-## What the dev server does
-
-`scripts/dev-server.js`:
-
-1. Builds a **route manifest** by scanning `app/` and serves it at `/_framework/routes.json`.
-2. Transforms **JSX** to `h()` calls on demand (cached by file mtime).
-3. Resolves **bare npm imports** (`import mongoose from 'mongoose'`) via `/_modules/mongoose`.
-4. Dispatches **API requests** to `api/**` and `app/api/**/route.js`.
-5. Serves static files, with **path-traversal confined to the project root** (403 otherwise).
-6. In development, opens a **WebSocket** and pushes reload events when you save.
-
-## Conventions worth keeping
-
-- **`app/`** is for pages and layouts only — not arbitrary components.
-- **`components/`** is for reusable UI shared across pages.
-- **`lib/`** for shared server/browser helpers; **`models/`** for data shapes.
-- **`_framework/`** and **`scripts/`** are framework internals — prefer not to edit them, so upgrades stay easy.
-- Names like `page.js`, `layout.js`, `route.js` are **reserved** by the file-based router. A `page.js` becomes a route; a random `utils.js` does not.
-
-## Continue
-
-→ [Pages & Layouts](./03-pages-and-layouts.md)
+# 02 · Project Structure
+
+Every folder in a generated Aziz.js app, and what goes in it.
+
+```
+my-app/
+├── index.html              ← entry point (loaded first, then the router takes over)
+├── package.json            ← name, scripts, dependencies
+│
+├── app/                    ← PAGES + LAYOUTS (file-based routing)
+│   ├── layout.js           ← root layout, wraps every page
+│   ├── page.js             ← route: /
+│   ├── not-found.js        ← custom 404 screen
+│   ├── about/
+│   │   └── page.js         ← route: /about
+│   └── blog/
+│       └── [slug]/
+│           └── page.js     ← route: /blog/:slug  (dynamic)
+│
+├── api/                    ← SERVER-SIDE API ROUTES (Node.js)
+│   ├── hello.js            ← /api/hello
+│   └── users.js            ← /api/users
+│
+├── components/             ← shared UI components
+│   ├── Navbar.js
+│   └── Footer.js
+│
+├── lib/                    ← utilities, DB connections, helpers
+│   └── db.js
+├── models/                 ← data models / schema definitions
+│   └── User.js
+├── styles/                 ← CSS
+│   └── globals.css
+│
+├── _framework/             ← the framework itself (don't edit casually)
+│   ├── runtime.js          ← h(), fibers, DOM materialization
+│   ├── hooks.js            ← useState, useEffect, …
+│   ├── router.js           ← client router, Link, navigation
+│   ├── route-match.js      ← path matching / layout collection
+│   ├── api.js              ← browser API client (api.get, …)
+│   ├── next-response.js    ← NextResponse for API routes
+│   └── boot.js             ← boot sequence, exposes globals
+│
+├── scripts/                ← dev server + tooling
+│   ├── dev-server.js       ← the HTTP server (dev + production)
+│   ├── live-reload-client.js
+│   └── lib/                ← js-transform, module-resolver, api-router
+│
+└── docs/                   ← these guides (optional, --no-docs to skip)
+```
+
+## The two "worlds"
+
+Aziz.js runs code in two places. Confusing them is the #1 beginner mistake.
+
+| | **Browser** (`app/`, `components/`) | **Server** (`api/`, `lib/`, `models/`) |
+|--|-------------------------------------|-----------------------------------------|
+| Runs in | the browser | Node.js |
+| Module system | ES modules (`import` / `export`) | CommonJS (`require`) or `.mjs` ESM |
+| Imports | `/…`, `@/…`, bare npm → `/_modules/…` | normal Node resolution |
+| Framework | `h`, hooks, router, `api` client | `NextResponse`, `require('../_framework/…')` |
+| Can touch | DOM, `window` | filesystem, DB, env vars, secrets |
+
+- **Pages and components** are compiled (JSX → `h()` calls) and sent to the browser.
+- **API routes** are loaded by the dev server in Node and executed per request.
+
+### Why API files use `require`
+
+`api/*.js` files run in Node with the CommonJS loader, so you `require`:
+
+```js
+const { NextResponse } = require('../_framework/next-response');
+```
+
+If you prefer native ESM on the server, name the file `.mjs` and use `export`:
+
+```js
+// api/todos.mjs
+import { NextResponse } from '../_framework/next-response.js';
+
+export async function GET() {
+    return NextResponse.json({ todos: [] });
+}
+```
+
+Both styles are supported — see [API Routes](./06-api-routes.md).
+
+## What the dev server does
+
+`scripts/dev-server.js`:
+
+1. Builds a **route manifest** by scanning `app/` and serves it at `/_framework/routes.json`.
+2. Transforms **JSX** to `h()` calls on demand (cached by file mtime).
+3. Resolves **bare npm imports** (`import mongoose from 'mongoose'`) via `/_modules/mongoose`.
+4. Dispatches **API requests** to `api/**` and `app/api/**/route.js`.
+5. Serves static files, with **path-traversal confined to the project root** (403 otherwise).
+6. In development, opens a **WebSocket** and pushes reload events when you save.
+
+## Conventions worth keeping
+
+- **`app/`** is for pages and layouts only — not arbitrary components.
+- **`components/`** is for reusable UI shared across pages.
+- **`lib/`** for shared server/browser helpers; **`models/`** for data shapes.
+- **`_framework/`** and **`scripts/`** are framework internals — prefer not to edit them, so upgrades stay easy.
+- Names like `page.js`, `layout.js`, `route.js` are **reserved** by the file-based router. A `page.js` becomes a route; a random `utils.js` does not.
+
+## Continue
+
+→ [Pages & Layouts](./03-pages-and-layouts.md)