easy-starter 1.2.0 → 2.0.0

package/template/README.md

@@ -4,23 +4,54 @@ 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 --- -->
+
+---
 
 ## 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 +59,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 +76,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 +99,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 +111,53 @@ 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 --- -->
 
 ### 3. 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,10 +1,11 @@
 NODE_ENV=development # development/production
 SERVER_PORT=1111
-ADMIN_PASSWORD=admin
+
+SERVER_URL=https://your-production-url.com/
 
 # deploy
 SSH_HOST=[IP_ADDRESS]
 SSH_USERNAME=root
 SSH_PASSWORD=[PASSWORD]
-SERVER_URL=https://your-production-url.com/
+SSH_PATH=/root/easy-starter-app
 PM2_APP_NAME=easy-starter-app

package/template/gitignore

@@ -1,4 +1,4 @@
-.parcel-cache/
+.vite/
 node_modules/
 dist/
 easy-db/

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-180.png" />
+  <link rel="icon" type="image/png" sizes="32x32" href="/images/icon-32.png" />
+  <link rel="icon" type="image/png" sizes="16x16" href="/images/icon-16.png" />
+  <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,30 +6,29 @@
     "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-page-router": "^0.2.1",
     "express": "^5.2.1",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
-    "ssr-hook": "^0.2.0",
     "typed-client-server-api": "^1.1.0"
   },
   "devDependencies": {
     "@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/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
     "concurrently": "^9.2.1",
-    "parcel": "^2.16.4",
     "tsx": "^4.21.0",
-    "typescript": "^6.0.3"
+    "typescript": "^7.0.0",
+    "vite": "^8.1.5",
+    "@vitejs/plugin-react": "^6.0.3",
+    "vite-imagetools": "^10.0.1"
   }
 }

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

@@ -8,39 +8,33 @@
     "background_color": "#09090b",
     "icons": [
         {
-            "src": "./images/icon.png?width=16&height=16",
+            "src": "/images/icon-16.png",
             "sizes": "16x16",
             "type": "image/png",
             "purpose": "maskable"
         },
         {
-            "src": "./images/icon.png?width=32&height=32",
+            "src": "/images/icon-32.png",
             "sizes": "32x32",
             "type": "image/png",
             "purpose": "maskable"
         },
         {
-            "src": "./images/icon.png?width=180&height=180",
+            "src": "/images/icon-180.png",
             "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-192.png",
             "sizes": "192x192",
             "type": "image/png",
             "purpose": "maskable"
         },
         {
-            "src": "./images/icon.png?as=webp&width=512&height=512",
+            "src": "/images/icon-512.png",
             "sizes": "512x512",
-            "type": "image/webp",
+            "type": "image/png",
             "purpose": "maskable"
         }
     ]

package/template/scripts/deploy.ts

@@ -11,7 +11,7 @@ const password = process.env.SSH_PASSWORD;
 // Configuration for your target server
 const server = process.env.SERVER_URL;
 const pm2AppName = process.env.PM2_APP_NAME;
-const sshPath = resolve("/", "root", pm2AppName || ""); // Path on the remote VPS
+const sshPath = process.env.SSH_PATH; // Path on the remote VPS
 
 const path = resolve(process.cwd()); // Local project path
 const ignoreFiles = [
@@ -26,10 +26,11 @@ const ignoreFiles = [
     ".DS_Store",
 ];
 
-// Ensure credentials are provided
+// Ensure credentials and paths are provided
 if (host === undefined) throw new Error("SSH_HOST environment variable is not defined.");
 if (username === undefined) throw new Error("SSH_USERNAME environment variable is not defined.");
 if (password === undefined) throw new Error("SSH_PASSWORD environment variable is not defined.");
+if (sshPath === undefined) throw new Error("SSH_PATH environment variable is not defined.");
 
 deploy();