easy-starter 1.2.1 → 2.1.0

package/template/README.md

@@ -4,23 +4,57 @@ This project was bootstrapped with `easy-starter`, giving you maximum freedom wi
 
 ## Features Included
 
-* **React 19 & TypeScript**: For a robust frontend experience.
+* **React 19 & TypeScript 7.0**: A modern, state-of-the-art type-safe frontend experience.
 * **Express Backend**: A simple Node.js server.
-* **Parcel Bundler**: Lightning-fast builds with zero configuration.
-* **SSR Ready**: Powered by [`ssr-hook`](https://www.npmjs.com/package/ssr-hook).
-* **Type-Safe API**: Connected via [`typed-client-server-api`](https://www.npmjs.com/package/typed-client-server-api).
-* **Local Database**: Ready to use with [`easy-db-node`](https://www.npmjs.com/package/easy-db-node).
+* **Vite v8 Bundler**: Zero-config client compilation with lightning-fast HMR and proxying.
+* **Type-Safe API**: RPC communication via [`typed-client-server-api`](https://www.npmjs.com/package/typed-client-server-api).
+* **Local Database**: local JSON-based document storage with [`easy-db-node`](https://www.npmjs.com/package/easy-db-node).
 * **Routing**: Managed by [`easy-page-router`](https://www.npmjs.com/package/easy-page-router).
+<!-- --- AUTH START --- -->
+* **User Authentication**: Pre-configured user registration, login dialogs, cookie rotation, and password reset flows via [`easy-user-auth`](https://www.npmjs.com/package/easy-user-auth).
+<!-- --- AUTH END --- -->
+<!-- --- SSR START --- -->
+* **SSR Ready**: Server-side rendering and hydration powered by [`ssr-hook`](https://www.npmjs.com/package/ssr-hook).
+<!-- --- SSR END --- -->
+<!-- --- ANALYTICS START --- -->
+* **Analytics**: Privacy-friendly local analytics tracked via [`easy-analytics`](https://www.npmjs.com/package/easy-analytics).
+<!-- --- ANALYTICS END --- -->
+<!-- --- OGIMAGE START --- -->
+* **og:image Generation**: Dynamic page screenshotting for social previews using headless `puppeteer`.
+<!-- --- OGIMAGE END --- -->
+<!-- --- RESIZER START --- -->
+* **Image Resizing**: Dynamic image resizing and WebP/JPEG conversion on the fly via [`easy-image-resizer`](https://www.npmjs.com/package/easy-image-resizer) with automatic disk caching.
+<!-- --- RESIZER END --- -->
+
+---
 
 ## Getting Started
 
-To start developing, run:
+To start developing:
 
-```bash
-npm run dev
-```
+1. Install dependencies (already completed by easy-starter):
+   ```bash
+   npm install
+   ```
+<!-- --- AUTH START --- -->
+2. **Configure SMTP settings:**
+   Open the generated `.env` file and fill in your SMTP credentials. This is required for sending password recovery links to users:
+   ```env
+   MAIL_SMTP=smtp.example.com
+   MAIL_PORT=587
+   MAIL_USER=your-email@example.com
+   MAIL_PASSWORD=your-email-password
+   ```
+<!-- --- AUTH END --- -->
+
+3. Run the development environment:
+   ```bash
+   npm run dev
+   ```
+
+This concurrently starts your Express server (port `1111`) and the Vite bundler (port `5173`). Open [http://localhost:5173](http://localhost:5173) in your browser. The page will automatically reload when you make changes.
 
-This will concurrently start your Express server and the Parcel bundler. Open [http://localhost:1234](http://localhost:1234) in your browser. The page will automatically reload when you make changes.
+---
 
 ## Core Concepts & Examples
 
@@ -28,10 +62,10 @@ This will concurrently start your Express server and the Parcel bundler. Open [h
 
 ### 1. Defining your API
 
-Your API contract is defined in a single file (`types.d.ts`). This ensures your frontend and backend are always perfectly in sync.
+Your API contract is defined in `types.ts`. This ensures your frontend and backend are always perfectly in sync.
 
 ```typescript
-// types.d.ts
+// types.ts
 import { APIDefinition, Endpoint } from "typed-client-server-api";
 
 export type API = APIDefinition<{
@@ -45,21 +79,21 @@ On the server, you implement these endpoints:
 
 ```typescript
 // server/index.tsx
-import { initApi } from "typed-client-server-api";
+import { setAPIBackend } from "typed-client-server-api";
 import { API } from "../types";
 
-initApi<API>(app, {
+setAPIBackend<API>(app, {
     getItems: async () => {
-        return db.select("item");
+        return selectArray("item");
     },
     addItem: async ({ name, value }) => {
-        return db.insert("item", { name, value });
+        return insert("item", { name, value });
     }
 });
 ```
 
-### 2. Fetching Data with SSR (`useSSRApi`)
-
+### 2. Fetching Data
+<!-- --- SSR START --- -->
 To fetch data on the server during SSR and seamlessly hydrate it on the client without loading spinners, use `useSSRApi` in your React components.
 
 ```tsx
@@ -68,8 +102,6 @@ import React from "react";
 import { useSSRApi } from "../services/api";
 
 export default function Index() {
-    // This will run on the server, fetch the data, embed it in the HTML,
-    // and hydrate perfectly on the client. Fully type-safe!
     const [items, error, isLoading, reload] = useSSRApi.getItems({});
 
     if (isLoading) return <p>Loading...</p>;
@@ -82,25 +114,97 @@ export default function Index() {
     );
 }
 ```
+<!-- --- SSR END --- -->
+<!-- --- NO_SSR START --- -->
+To fetch data on the client reactively, use `useApi` in your React components.
+
+```tsx
+// src/pages/Index.tsx
+import React from "react";
+import { useApi } from "../services/api";
+
+export default function Index() {
+    const [items, error, isLoading, reload] = useApi.getItems({});
+
+    if (isLoading) return <p>Loading...</p>;
+    if (error) return <p>Error: {error.message}</p>;
+
+    return (
+        <ul>
+            {items?.map(item => <li key={item._id}>{item.name}</li>)}
+        </ul>
+    );
+}
+```
+<!-- --- NO_SSR END --- -->
+
+<!-- --- RESIZER START --- -->
+### 3. Dynamic Image Resizing (`easy-image-resizer`)
+
+All images stored in `/public` (e.g., `/public/images/logo.png`) can be dynamically resized, cropped, and converted on the fly using `easy-image-resizer` Express middleware.
+
+#### Using `<Img />` Component in React (TSX)
+
+Use the `<Img />` component imported from `../components/Img` instead of standard `<img>` tags. It automatically appends query parameters and defaults to `"webp"` format for optimal performance:
+
+```tsx
+import { Img } from "../components/Img";
+
+export default function MyComponent() {
+    return (
+        <Img
+            src="/images/logo.png"
+            w={300}
+            h={150}
+            format="webp"
+            quality={85}
+            alt="App Logo"
+        />
+    );
+}
+```
+
+Available props on `<Img />`:
+* `w` or `width`: Target width in pixels
+* `h` or `height`: Target height in pixels
+* `mw` or `maxWidth`, `mh` or `maxHeight`: Max dimension constraints
+* `format` or `type`: `"webp"` (default), `"jpeg"`, or `"png"`
+* `q` or `quality`: Image quality (1-100)
+
+#### Using Image Resizing in CSS
+
+You can also use URL query parameters directly inside CSS `url()` declarations:
+
+```css
+.hero-banner {
+    background-image: url("/images/hero.png?w=1200&format=webp&q=85");
+}
+```
+<!-- --- RESIZER END --- -->
 
-### 3. AI Integration (`.cursorrules`)
+### 4. AI Integration (`.cursorrules`)
 
-This template includes a pre-configured `.cursorrules` file in the root. If you develop using AI assistants such as Cursor, Windsurf, or GitHub Copilot, they will automatically read this file to understand the specific conventions of `easy-starter`:
+This template includes a pre-configured `.cursorrules` file in the root. If you develop using AI assistants such as Cursor, Windsurf, or GitHub Copilot, they will automatically read this file to understand the specific conventions of `easy-starter`.
+
+---
 
 ## Scripts
 
-* `npm run dev` - Starts the development server.
+* `npm run dev` - Starts backend and Vite dev server.
 * `npm run build` - Builds the application for production.
 * `npm start` - Starts the production server (run build first).
 * `npm run deploy` - (If included) Deploys your app to a remote server via SSH.
 
+---
+
 ## Project Structure
 
 * `/src` - Your React frontend code.
 * `/server` - Your Express backend code.
 * `/types.ts` - Shared TypeScript definitions for your API and Database.
 * `/.cursorrules` - Rules instructing AI coding assistants how to interact with the project stack.
-* `/public` - Static assets (images, fonts, etc.).
-* `/easy-db` - Where your local database JSON files are stored.
+* `/public` - Static assets served at the root (images, favicon, site.webmanifest).
+* `/easy-db-files` - Where uploaded database files are served.
+* `/easy-db-backup` - Automated backup folder for your JSON collections.
 
 Enjoy building with freedom!

package/template/env

@@ -1,6 +1,5 @@
 NODE_ENV=development # development/production
 SERVER_PORT=1111
-ADMIN_PASSWORD=admin
 
 SERVER_URL=https://your-production-url.com/
 

package/template/gitignore

@@ -1,6 +1,7 @@
-.parcel-cache/
+.vite/
 node_modules/
 dist/
+cache/
 easy-db/
 easy-db-files/
 easy-db-backup/

package/template/index.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <link rel="apple-touch-icon" sizes="180x180" href="/images/icon.png?w=180&h=180&format=webp" />
+  <link rel="icon" type="image/png" sizes="32x32" href="/images/icon.png?w=32&h=32" />
+  <link rel="icon" type="image/png" sizes="16x16" href="/images/icon.png?w=16&h=16" />
+  <link rel="manifest" href="/site.webmanifest" />
+</head>
+<body>
+  <div id="root"></div>
+  <script type="module" src="/src/index.tsx"></script>
+</body>
+</html>

package/template/package.json

@@ -6,16 +6,19 @@
     "start": "tsx --env-file=.env server/index.tsx",
     "dev": "concurrently --kill-others \"npm run server:dev\" \"npm run fe:dev\"",
     "server:dev": "tsx --env-file=.env --watch server/index.tsx",
-    "fe:dev": "parcel src/index.html --no-cache",
-    "build": "parcel build src/index.html",
-    "deploy": "tsx scripts/deploy.ts"
+    "fe:dev": "vite",
+    "build": "vite build"
   },
   "dependencies": {
     "cors": "^2.8.6",
     "easy-analytics": "^1.0.1",
     "easy-db-node": "^3.0.1",
+    "easy-image-resizer": "^2.0.1",
     "easy-page-router": "^0.2.1",
+    "easy-user-auth": "^1.1.0",
     "express": "^5.2.1",
+    "nodemailer": "^7.0.9",
+    "puppeteer": "^25.3.0",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
     "ssr-hook": "^0.2.0",
@@ -25,11 +28,14 @@
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.6",
     "@types/node": "^24.0.0",
-    "@types/react": "^19.2.14",
-    "@types/react-dom": "^19.2.3",
+    "@types/nodemailer": "^6.4.15",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^6.0.3",
     "concurrently": "^9.2.1",
-    "parcel": "^2.16.4",
+    "node-ssh": "^13.2.1",
     "tsx": "^4.21.0",
-    "typescript": "^6.0.3"
+    "typescript": "^7.0.0",
+    "vite": "^8.1.5"
   }
-}
+}

package/template/{src → public}/site.webmanifest

@@ -8,37 +8,31 @@
     "background_color": "#09090b",
     "icons": [
         {
-            "src": "./images/icon.png?width=16&height=16",
+            "src": "/images/icon.png?w=16&h=16",
             "sizes": "16x16",
             "type": "image/png",
             "purpose": "maskable"
         },
         {
-            "src": "./images/icon.png?width=32&height=32",
+            "src": "/images/icon.png?w=32&h=32",
             "sizes": "32x32",
             "type": "image/png",
             "purpose": "maskable"
         },
         {
-            "src": "./images/icon.png?width=180&height=180",
+            "src": "/images/icon.png?w=180&h=180&format=webp",
             "sizes": "180x180",
-            "type": "image/png",
-            "purpose": "maskable"
-        },
-        {
-            "src": "./images/icon.png?as=webp&width=192&height=192",
-            "sizes": "192x192",
             "type": "image/webp",
             "purpose": "maskable"
         },
         {
-            "src": "./images/icon.png?width=192&height=192",
+            "src": "/images/icon.png?w=192&h=192&format=webp",
             "sizes": "192x192",
-            "type": "image/png",
+            "type": "image/webp",
             "purpose": "maskable"
         },
         {
-            "src": "./images/icon.png?as=webp&width=512&height=512",
+            "src": "/images/icon.png?w=512&h=512&format=webp",
             "sizes": "512x512",
             "type": "image/webp",
             "purpose": "maskable"

package/template/scripts/deploy.ts

@@ -17,7 +17,8 @@ const path = resolve(process.cwd()); // Local project path
 const ignoreFiles = [
     ".git",
     ".github",
-    ".parcel-cache",
+    ".vite",
+    "dist",
     "node_modules",
     "scripts",
     "easy-db",
@@ -70,7 +71,7 @@ async function deploy() {
     const timeServerOff = new Date().getTime();
 
     console.log(`Removing old build...`);
-    await sshExec(ssh, "rm -rf .parcel-cache", "Failed to remove .parcel-cache folder.");
+    await sshExec(ssh, "rm -rf .vite", "Failed to remove .vite folder.");
     await sshExec(ssh, "rm -rf dist", "Failed to remove dist folder.");
     console.log(`✔ Old build removed.\n`);