create-aziz-app 3.1.1 → 3.1.3

package/template/docs/09-imports-and-modules.md

@@ -1,97 +1,97 @@
-# 09 · Imports & Modules
-
-Browser code imports work in two "flavors": **browser modules** served by the dev server, and **npm packages**. Everything goes through the same transform pipeline (JSX → `h()`, import rewriting).
-
-## How imports are resolved
-
-| Specifier | Becomes / behavior | Notes |
-|------------|-------------------|-------|
-| `./Component.js` or `../lib/utils` | stays relative | The dev server loads files by path |
-| `/components/Navbar.js` | absolute in browser → maps to your project root | Works from anywhere |
-| `@/lib/db` | rewritten to `/lib/db` | Handy when deeply nested |
-| `mongoose` | rewritten to `/_modules/mongoose` | Bare npm package |
-| `lodash-es` | rewritten to `/_modules/lodash-es` | Exports field respected |
-| `node:fs`, `data:`, `file:`, `http://…` | left untouched | Skipped by the rewriter |
-
-The rewriter runs on **entire modules** (so multi-line `import { … } from 'pkg'` is handled correctly). It rewrites:
-
-- `import X from '…'` and `export … from '…'`
-- side-effect `import '…'`
-- dynamic `import('…')`
-
-## In your pages/components
-
-Pages and components run in the browser (ES modules). You can import shared components, utilities, or anything you ship.
-
-```js
-// app/dashboard/page.js
-import Navbar from '/components/Navbar.js';
-import { format } from '@/lib/format.js';
-import Button from './Button.js';        // co-located
-
-export default function Dashboard() {
-    return (
-        <div>
-            <Navbar />
-            <Button label={format('hello')} />
-        </div>
-    );
-}
-```
-
-**No imports of React/hooks are needed.** `h`, `Fragment`, `useState`, etc. are global.
-
-## npm packages
-
-1. Install first:
-
-   ```bash
-   npm install lodash-es
-   ```
-
-2. Import normally:
-
-   ```js
-   import { pick } from 'lodash-es';
-
-   const user = pick(obj, ['id', 'name']);
-   ```
-
-The dev server resolves `lodash-es` to `/_modules/lodash-es`. Internally it looks into `node_modules/` and honors the `exports`/`browser`/`module`/`main` fields (see `scripts/lib/module-resolver.js`). If a module can't be found, the server returns a 404 and the browser throws — `npm install` fixes it.
-
-## In API routes (server side)
-
-API routes are **Node.js code** (`api/*.js` or `.mjs`). Use Node's resolution:
-
-```js
-// api/users.js
-const { NextResponse } = require('../_framework/next-response');
-const { connect } = require('../lib/db');   // server utility
-const User = require('../models/User');
-
-module.exports = {
-    GET: async () => {
-        await connect();
-        return NextResponse.json(await User.find());
-    },
-};
-```
-
-Bare `mongoose` in API routes is the usual `require('mongoose')` (no `/_modules` rewrite needed).
-
-## Loading strategy
-
-- `/_modules/*` is **on-the-fly**. The dev server reads the module file, runs the same transform pipeline (JSX transform only affects files inside your app tree; modules usually don't contain JSX), and serves it as ES module text.
-- Transforms for your own files (`app/`, `components/`) are **mtime-cached** to make hot reload snappy.
-- Framework internals (`/_framework/*`) are served as-is (no JSX rewrite).
-
-## Tips
-
-- Use **absolute** (`/…`) for imports from the root, or `@/` for ergonomic deep imports.
-- Keep imports **explicit** with `.js` extensions when referencing local files in browser code (works fine in this system).
-- Dynamic `import()` is rewritten in browser code (`import('lodash-es')` → `import('/_modules/lodash-es')`) and also works natively in Node (`.mjs` context).
-- Avoid mixing `require` into browser code — it's never injected. Stick to `import/export`.
-
-## Continue
-
-→ [Database & Models](./10-database-and-models.md)
+# 09 · Imports & Modules
+
+Browser code imports work in two "flavors": **browser modules** served by the dev server, and **npm packages**. Everything goes through the same transform pipeline (JSX → `h()`, import rewriting).
+
+## How imports are resolved
+
+| Specifier | Becomes / behavior | Notes |
+|------------|-------------------|-------|
+| `./Component.js` or `../lib/utils` | stays relative | The dev server loads files by path |
+| `/components/Navbar.js` | absolute in browser → maps to your project root | Works from anywhere |
+| `@/lib/db` | rewritten to `/lib/db` | Handy when deeply nested |
+| `mongoose` | rewritten to `/_modules/mongoose` | Bare npm package |
+| `lodash-es` | rewritten to `/_modules/lodash-es` | Exports field respected |
+| `node:fs`, `data:`, `file:`, `http://…` | left untouched | Skipped by the rewriter |
+
+The rewriter runs on **entire modules** (so multi-line `import { … } from 'pkg'` is handled correctly). It rewrites:
+
+- `import X from '…'` and `export … from '…'`
+- side-effect `import '…'`
+- dynamic `import('…')`
+
+## In your pages/components
+
+Pages and components run in the browser (ES modules). You can import shared components, utilities, or anything you ship.
+
+```js
+// app/dashboard/page.js
+import Navbar from '/components/Navbar.js';
+import { format } from '@/lib/format.js';
+import Button from './Button.js';        // co-located
+
+export default function Dashboard() {
+    return (
+        <div>
+            <Navbar />
+            <Button label={format('hello')} />
+        </div>
+    );
+}
+```
+
+**No imports of React/hooks are needed.** `h`, `Fragment`, `useState`, etc. are global.
+
+## npm packages
+
+1. Install first:
+
+   ```bash
+   npm install lodash-es
+   ```
+
+2. Import normally:
+
+   ```js
+   import { pick } from 'lodash-es';
+
+   const user = pick(obj, ['id', 'name']);
+   ```
+
+The dev server resolves `lodash-es` to `/_modules/lodash-es`. Internally it looks into `node_modules/` and honors the `exports`/`browser`/`module`/`main` fields (see `scripts/lib/module-resolver.js`). If a module can't be found, the server returns a 404 and the browser throws — `npm install` fixes it.
+
+## In API routes (server side)
+
+API routes are **Node.js code** (`api/*.js` or `.mjs`). Use Node's resolution:
+
+```js
+// api/users.js
+const { NextResponse } = require('../_framework/next-response');
+const { connect } = require('../lib/db');   // server utility
+const User = require('../models/User');
+
+module.exports = {
+    GET: async () => {
+        await connect();
+        return NextResponse.json(await User.find());
+    },
+};
+```
+
+Bare `mongoose` in API routes is the usual `require('mongoose')` (no `/_modules` rewrite needed).
+
+## Loading strategy
+
+- `/_modules/*` is **on-the-fly**. The dev server reads the module file, runs the same transform pipeline (JSX transform only affects files inside your app tree; modules usually don't contain JSX), and serves it as ES module text.
+- Transforms for your own files (`app/`, `components/`) are **mtime-cached** to make hot reload snappy.
+- Framework internals (`/_framework/*`) are served as-is (no JSX rewrite).
+
+## Tips
+
+- Use **absolute** (`/…`) for imports from the root, or `@/` for ergonomic deep imports.
+- Keep imports **explicit** with `.js` extensions when referencing local files in browser code (works fine in this system).
+- Dynamic `import()` is rewritten in browser code (`import('lodash-es')` → `import('/_modules/lodash-es')`) and also works natively in Node (`.mjs` context).
+- Avoid mixing `require` into browser code — it's never injected. Stick to `import/export`.
+
+## Continue
+
+→ [Database & Models](./10-database-and-models.md)

package/template/docs/10-database-and-models.md

@@ -1,154 +1,154 @@
-# 10 · Database & Models
-
-Since API routes run in **real Node.js**, you can connect to databases, send emails, and touch secrets. Do **not** put secrets or DB connections in browser code.
-
-## Where DB code lives
-
-Put utilities and models under `lib/` and `models/`. Import them from API routes using CommonJS:
-
-```text
-api/users.js        → talks to HTTP
-lib/db.js           → connects to MongoDB
-models/User.js      → schema + model
-```
-
-## MongoDB + Mongoose (working example)
-
-### 1. Install
-
-```bash
-npm install mongoose
-```
-
-### 2. `lib/db.js`
-
-```js
-// lib/db.js
-const mongoose = require('mongoose');
-
-const URI = process.env.MONGODB_URI || 'mongodb://localhost:27017/azizjs';
-
-let conn = null;
-
-async function connectDB() {
-    if (conn) return conn;
-    conn = await mongoose.connect(URI, { maxPoolSize: 10 });
-    console.log('✅ MongoDB connected');
-    return conn;
-}
-
-module.exports = { connectDB };
-```
-
-### 3. `models/User.js`
-
-```js
-// models/User.js
-const mongoose = require('mongoose');
-
-const UserSchema = new mongoose.Schema({
-    name: String,
-    email: String,
-    createdAt: { type: Date, default: Date.now },
-});
-
-const User = mongoose.models.User || mongoose.model('User', UserSchema);
-module.exports = User;
-```
-
-### 4. `api/users.js`
-
-```js
-// api/users.js
-const { NextResponse } = require('../_framework/next-response');
-const { connectDB } = require('../lib/db');
-const User = require('../models/User');
-
-module.exports = {
-    GET: async () => {
-        await connectDB();
-        const users = await User.find().select('-__v').lean();
-        return NextResponse.json(users);
-    },
-
-    POST: async (request) => {
-        const body = await request.json();
-        await connectDB();
-        const user = await User.create(body);
-        return NextResponse.json(user, { status: 201 });
-    },
-};
-```
-
-### 5. `api/users/[id].js`
-
-```js
-// api/users/[id].js
-const { NextResponse } = require('../_framework/next-response');
-const { connectDB } = require('../lib/db');
-const User = require('../models/User');
-
-module.exports = {
-    GET: async (request) => {
-        await connectDB();
-        const user = await User.findById(request.params.id);
-        if (!user) return NextResponse.json({ error: 'Not found' }, { status: 404 });
-        return NextResponse.json(user);
-    },
-
-    PUT: async (request) => {
-        const body = await request.json();
-        await connectDB();
-        const user = await User.findByIdAndUpdate(request.params.id, body, { new: true });
-        if (!user) return NextResponse.json({ error: 'Not found' }, { status: 404 });
-        return NextResponse.json(user);
-    },
-
-    DELETE: async (request) => {
-        await connectDB();
-        const user = await User.findByIdAndDelete(request.params.id);
-        if (!user) return NextResponse.json({ error: 'Not found' }, { status: 404 });
-        return NextResponse.json({ ok: true });
-    },
-};
-```
-
-## Fetching from the browser
-
-Use `api` or `useFetch`:
-
-```js
-// declarative
-const { data, loading, error } = useFetch('/api/users');
-
-// imperative
-async function addUser() {
-    await api.post('/api/users', { name: 'Aziz', email: 'aziz@example.com' });
-}
-```
-
-## Other databases
-
-You don't need to change anything. Use native drivers:
-
-```js
-// lib/pg.js
-const { Pool } = require('pg');
-const pool = new Pool({ connectionString: process.env.DATABASE_URL });
-module.exports = { query: (text, params) => pool.query(text, params) };
-```
-
-## Hot reload & caching
-
-Editing `lib/db.js` or `models/User.js` triggers server reload — the dev server purges project `require.cache` entries (excluding `node_modules`). Active DB connections may persist; keep your connection logic idempotent (`conn = null` singleton) as above.
-
-## Tips
-
-- **Never** store DB credentials in browser files. Use environment variables (`.env`) and read them in API routes (`process.env.MONGODB_URI`). A future improvement could load `.env`, but today it's manual.
-- **Return lean objects** (`.lean()`) to cut JSON overhead.
-- **Validate input** — throw `Error` with `err.status = 400` on bad payloads.
-- **Use transactions** for multi-step operations.
-
-## Continue
-
-→ [Authentication](./11-authentication.md)
+# 10 · Database & Models
+
+Since API routes run in **real Node.js**, you can connect to databases, send emails, and touch secrets. Do **not** put secrets or DB connections in browser code.
+
+## Where DB code lives
+
+Put utilities and models under `lib/` and `models/`. Import them from API routes using CommonJS:
+
+```text
+api/users.js        → talks to HTTP
+lib/db.js           → connects to MongoDB
+models/User.js      → schema + model
+```
+
+## MongoDB + Mongoose (working example)
+
+### 1. Install
+
+```bash
+npm install mongoose
+```
+
+### 2. `lib/db.js`
+
+```js
+// lib/db.js
+const mongoose = require('mongoose');
+
+const URI = process.env.MONGODB_URI || 'mongodb://localhost:27017/azizjs';
+
+let conn = null;
+
+async function connectDB() {
+    if (conn) return conn;
+    conn = await mongoose.connect(URI, { maxPoolSize: 10 });
+    console.log('✅ MongoDB connected');
+    return conn;
+}
+
+module.exports = { connectDB };
+```
+
+### 3. `models/User.js`
+
+```js
+// models/User.js
+const mongoose = require('mongoose');
+
+const UserSchema = new mongoose.Schema({
+    name: String,
+    email: String,
+    createdAt: { type: Date, default: Date.now },
+});
+
+const User = mongoose.models.User || mongoose.model('User', UserSchema);
+module.exports = User;
+```
+
+### 4. `api/users.js`
+
+```js
+// api/users.js
+const { NextResponse } = require('../_framework/next-response');
+const { connectDB } = require('../lib/db');
+const User = require('../models/User');
+
+module.exports = {
+    GET: async () => {
+        await connectDB();
+        const users = await User.find().select('-__v').lean();
+        return NextResponse.json(users);
+    },
+
+    POST: async (request) => {
+        const body = await request.json();
+        await connectDB();
+        const user = await User.create(body);
+        return NextResponse.json(user, { status: 201 });
+    },
+};
+```
+
+### 5. `api/users/[id].js`
+
+```js
+// api/users/[id].js
+const { NextResponse } = require('../_framework/next-response');
+const { connectDB } = require('../lib/db');
+const User = require('../models/User');
+
+module.exports = {
+    GET: async (request) => {
+        await connectDB();
+        const user = await User.findById(request.params.id);
+        if (!user) return NextResponse.json({ error: 'Not found' }, { status: 404 });
+        return NextResponse.json(user);
+    },
+
+    PUT: async (request) => {
+        const body = await request.json();
+        await connectDB();
+        const user = await User.findByIdAndUpdate(request.params.id, body, { new: true });
+        if (!user) return NextResponse.json({ error: 'Not found' }, { status: 404 });
+        return NextResponse.json(user);
+    },
+
+    DELETE: async (request) => {
+        await connectDB();
+        const user = await User.findByIdAndDelete(request.params.id);
+        if (!user) return NextResponse.json({ error: 'Not found' }, { status: 404 });
+        return NextResponse.json({ ok: true });
+    },
+};
+```
+
+## Fetching from the browser
+
+Use `api` or `useFetch`:
+
+```js
+// declarative
+const { data, loading, error } = useFetch('/api/users');
+
+// imperative
+async function addUser() {
+    await api.post('/api/users', { name: 'Aziz', email: 'aziz@example.com' });
+}
+```
+
+## Other databases
+
+You don't need to change anything. Use native drivers:
+
+```js
+// lib/pg.js
+const { Pool } = require('pg');
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+module.exports = { query: (text, params) => pool.query(text, params) };
+```
+
+## Hot reload & caching
+
+Editing `lib/db.js` or `models/User.js` triggers server reload — the dev server purges project `require.cache` entries (excluding `node_modules`). Active DB connections may persist; keep your connection logic idempotent (`conn = null` singleton) as above.
+
+## Tips
+
+- **Never** store DB credentials in browser files. Use environment variables (`.env`) and read them in API routes (`process.env.MONGODB_URI`). A future improvement could load `.env`, but today it's manual.
+- **Return lean objects** (`.lean()`) to cut JSON overhead.
+- **Validate input** — throw `Error` with `err.status = 400` on bad payloads.
+- **Use transactions** for multi-step operations.
+
+## Continue
+
+→ [Authentication](./11-authentication.md)