easy-starter 1.2.0 → 2.0.0

package/README.md

@@ -1,33 +1,35 @@
 # easy-starter 🚀
 
-A lightweight CLI tool to bootstrap modern fullstack React web projects.
+A lightweight CLI tool to bootstrap modern fullstack React web projects with Vite v8, TypeScript 7.0, and optional authentication.
 
 ```bash
 npx easy-starter [your-project-name]
 ```
 
-**Keywords:** React, Server-Side Rendering (SSR), Database (DB), Analytics, Type-Safe API, Fullstack, Minimalist
+**Keywords:** React, Server-Side Rendering (SSR), Vite, Database (DB), Analytics, Type-Safe API, User Authentication, Fullstack, Minimalist
 
 Tired of rigid frameworks forcing you into complex folder structures and steep learning curves? **easy-starter** is built on the philosophy of maximum freedom and modularity. It provides a solid foundation by combining a set of carefully curated, simple, and powerful tools without locking you into a monolithic architecture like Next.js or Remix.
 
-## Why easy-starter? (The Philosophy)
+---
 
-Modern full-stack frameworks are incredibly powerful, but they often come with significant trade-offs: strict file-system routing rules, immense complexity under the hood, and the modern paradigm of strictly dividing components into "client" and "server" boundaries. 
+## What's New in v2.0.0?
 
-**easy-starter solves this by giving you back control.**
+* **Vite v8 Bundler:** Switched from Parcel to Vite v8, offering lightning-fast HMR and seamless dev proxying.
+* **TypeScript 7.0:** Fully upgraded dependencies and compiler options to support TypeScript 7.
+* **Interactive Installer:** Run `npx easy-starter` and configure exactly what you need. Zero bloat — files, comments, and package dependencies are completely omitted if a feature is disabled.
+* **User Authentication:** Out-of-the-box integration with `easy-user-auth` including secure cookie rotation, user registration/login modals, role checking, and custom password recovery emails.
+* **Dynamic Social Previews:** Generate dynamic `og:image` screenshots of your pages automatically using headless browser rendering (`puppeteer`) and cached locally in `easy-db-node`.
+* **Flexible Viewport Tuning:** Optional script injection to scale mobile layouts to a standard viewport width (min-width: 600px).
 
-* **No Server/Client Component Split:** Forget about adding `'use client'` everywhere or stressing about what runs where. With `easy-starter`, you just write standard React components. The integrated `ssr-hook` elegantly handles data fetching on the server and seamless hydration on the client for you.
-* **No rigid structure:** You decide where your components, pages, and server logic live.
-* **Clear Backend/Frontend separation:** Server code stays on the Express server, client code stays in React, connected by a seamlessly typed RPC API.
-* **Minimalist dependencies:** We rely on simple, purpose-built libraries instead of heavy abstractions.
-* **Instant Productivity:** You get SSR, a Database, Analytics, and a Type-Safe API out of the box in seconds.
+---
 
 ## What's included in the box?
 
-The generated boilerplate comes pre-configured with a stack designed for developer happiness and raw performance:
+The generated boilerplate can be configured to contain:
 
-* **Frontend/Backend:** React 19, TypeScript, and Express.
-* **Bundler:** Parcel - zero-configuration, lightning-fast builds.
+* **Frontend/Backend:** React 19, TypeScript 7.0, and Express.
+* **Bundler:** Vite v8 - lightning-fast client bundles with native dev proxying.
+* **User Authentication:** [`easy-user-auth`](https://www.npmjs.com/package/easy-user-auth) - Highly secure password-recovery, registration, and cookie rotation framework.
 * **Server-Side Rendering (SSR):** [`ssr-hook`](https://www.npmjs.com/package/ssr-hook) - Dead-simple SSR for React. Fetches data on the server and hydrates on the client without the flash of loading content.
 * **Type-Safe API:** [`typed-client-server-api`](https://www.npmjs.com/package/typed-client-server-api) - An RPC-like interface giving you full TypeScript autocomplete and safety between your Express server and React client.
 * **Database:** [`easy-db-node`](https://www.npmjs.com/package/easy-db-node) - A simple, local JSON-based database perfect for small to medium projects where setting up Postgres/MongoDB is overkill.
@@ -36,83 +38,31 @@ The generated boilerplate comes pre-configured with a stack designed for develop
 * **AI-Friendly (.cursorrules):** Pre-configured, LLM-optimized guidelines in the project root so AI coding assistants (Cursor, Windsurf, Copilot, etc.) immediately understand the codebase conventions, API restrictions, routing patterns, and database operations.
 * **Deployment:** Integrated Github Actions workflow and PM2 deployment script for seamless, automated deployment straight to your own VPS.
 
-## Core Concepts & Examples
+---
 
-> **Note:** `easy-starter` gives you a solid foundation, but you are not forced into any of these patterns. If you prefer a different routing library (like `react-router`), another data fetching solution (like `react-query` or `swr`), or standard REST endpoints, you are completely free to swap them out and use your own libraries!
+## Interactive Configuration Prompts
 
-### 1. Defining your API
+When you run `npx easy-starter`, the CLI will prompt you with the following configuration questions:
 
-Your API contract is defined in a single file (`types.d.ts`). This ensures your frontend and backend are always perfectly in sync.
+1. **Project name:** Choose the name of the folder and the app.
+2. **User Authentication:** Do you want to add user login/registration widgets? (Installs `easy-user-auth` and nodemailer, generates JWT secrets in `.env`).
+3. **Viewport Width Fix:** Do you want to fix iOS mobile viewport issues by ensuring a minimum width of 600px? (Adds JS viewport resizing listener and sets CSS `min-width`).
+4. **Admin Dashboard:** Do you want to include `/admin` page? (If Auth is enabled, protects it using user roles. If Auth is disabled, protects it using a static password).
+5. **Analytics:** Do you want local visitor analytics? (Installs `easy-analytics`, adds dashboard visualization).
+6. **SSR Rendering:** Do you want Server-Side Rendering? (Installs `ssr-hook`, configures hydration).
+7. **og:image Generation:** Do you want dynamic `og:image` generation? (Installs `puppeteer` to automatically screenshot URLs for social cards, cached via easy-db).
+8. **Deployment Script:** Do you want to deploy to your VPS using GitHub Actions? (Installs `node-ssh`, adds SSH deploy script).
 
-```typescript
-// types.d.ts
-import { APIDefinition, Endpoint } from "typed-client-server-api";
-
-export type API = APIDefinition<{
-    // Define an endpoint: parameters -> response
-    getItems: Endpoint<{}, Item[]>;
-    addItem: Endpoint<{ name: string; value: number }, string>;
-}>;
-```
-
-On the server, you implement these endpoints:
-
-```typescript
-// server/index.tsx
-import { initApi } from "typed-client-server-api";
-import { API } from "../types";
-
-initApi<API>(app, {
-    getItems: async () => {
-        return db.select("item");
-    },
-    addItem: async ({ name, value }) => {
-        return db.insert("item", { name, value });
-    }
-});
-```
-
-### 2. Fetching Data with SSR (`useSSRApi`)
-
-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
-// src/pages/Index.tsx
-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>;
-    if (error) return <p>Error: {error.message}</p>;
-
-    return (
-        <ul>
-            {items?.map(item => <li key={item._id}>{item.name}</li>)}
-        </ul>
-    );
-}
-```
-
-### 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`.
+---
 
 ## Getting Started
 
-Bootstrapping a new project is as simple as running one command:
+Bootstrapping a new project is as simple as running:
 
 ```bash
 npx easy-starter [your-project-name]
 ```
 
-### Interactive CLI
-
-If you run `npx easy-starter` without a project name, the CLI will guide you interactively. It will also ask if you want to include a ready-to-use **Deployment Script** (`scripts/deploy.ts` and GitHub Actions workflow) utilizing `node-ssh` and PM2 for dead-simple automated deployments to your VPS.
-
 ### Running your project
 
 Once created, navigate to your new project folder and start the development server:
@@ -122,13 +72,15 @@ cd your-project-name
 npm run dev
 ```
 
-This command runs both the Express backend and the Parcel frontend bundler concurrently. Your app will be live at `http://localhost:1234`!
+This command starts both the Express backend on port `1111` and the Vite dev server on port `5173`. Your app will be live at `http://localhost:5173`!
+
+---
 
 ## Available Scripts
 
 Inside your newly generated project, you can use the following scripts:
 
-* `npm run dev`: Starts the development server with hot-reloading for both backend and frontend.
+* `npm run dev`: Starts the development server with hot-reloading. Open `http://localhost:5173`.
 * `npm run build`: Builds the project for production.
 * `npm start`: Starts the production server (make sure to build first).
 * `npm run deploy`: (Optional) Executes the `scripts/deploy.ts` script to deploy your built project via SSH and PM2.

package/bin/index.js

@@ -3,6 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 const readline = require('readline');
+const crypto = require('crypto');
 const { execSync } = require('child_process');
 
 const rl = readline.createInterface({
@@ -13,34 +14,95 @@ const rl = readline.createInterface({
 const askQuestion = (query) => new Promise(resolve => rl.question(query, resolve));
 
 async function main() {
-  console.log('🚀 Welcome to easy-starter!');
+  console.log('🚀 Welcome to easy-starter v2.0.0!');
 
   let projectName = process.argv[2];
   if (!projectName) {
     projectName = await askQuestion('Enter the project name (e.g., my-awesome-app): ');
   }
+  projectName = projectName.trim();
 
   if (!projectName) {
-    console.error('Project name cannot be empty!');
+    console.error('❌ Project name cannot be empty!');
     rl.close();
     process.exit(1);
   }
 
-  const useAdminDashboard = await askQuestion('Do you want to include an admin dashboard for analytics? (y/n) [y]: ');
-  const includeAdmin = useAdminDashboard.toLowerCase() !== 'n';
+  console.log('\n🔒 1. User Authentication & Login (easy-user-auth)');
+  console.log('   Provides out-of-the-box user registration, login dialogs, secure cookie-based');
+  console.log('   sessions, and forgotten password recovery emails.');
+  const ansAuth = await askQuestion('   Do you want to include user authentication? (y/n) [y]: ');
+  const useAuth = ansAuth.trim().toLowerCase() !== 'n';
 
-  console.log('\n🚢 Deployment (GitHub Actions, VPS, SSH, PM2)');
-  console.log('You can automatically include a deployment script designed for GitHub Actions.');
-  console.log('It connects to your VPS via SSH, uploads your project, builds it, and runs it via PM2.');
-  const useDeployScript = await askQuestion('Do you want to include this GitHub Actions deploy script? (y/n) [y]: ');
-  const includeDeploy = useDeployScript.toLowerCase() !== 'n';
+  console.log('\n📊 2. Analytics Tracking (easy-analytics)');
+  console.log('   Tracks page visits, referrers, resolutions, and browsers locally without cookies.');
+  console.log('   Also captures and records client-side/frontend errors encountered by users.');
+  console.log('   If the Admin Dashboard is enabled, it generates interactive visual graphs inside /admin.');
+  const ansAnalytics = await askQuestion('   Do you want to include privacy-friendly analytics? (y/n) [y]: ');
+  const useAnalytics = ansAnalytics.trim().toLowerCase() !== 'n';
+
+  console.log('\n🛠️  3. Admin Dashboard (/admin)');
+  console.log('   A secure section to manage your app. Protected by user authentication roles');
+  console.log('   (admin/user) if auth is enabled, or a static environment password if disabled.');
+  const ansAdmin = await askQuestion('   Do you want to include the admin dashboard? (y/n) [y]: ');
+  const useAdmin = ansAdmin.trim().toLowerCase() !== 'n';
+
+  let useAdminUsers = false;
+  let useAdminErrors = false;
+
+  if (useAdmin) {
+    if (useAuth) {
+      console.log('\n👥 3a. Admin User Management');
+      console.log('    Allows administrators to list registered users and change their roles');
+      console.log('    directly from the admin dashboard.');
+      const ansAdminUsers = await askQuestion('    Do you want to include User Management in the admin panel? (y/n) [y]: ');
+      useAdminUsers = ansAdminUsers.trim().toLowerCase() !== 'n';
+    } else {
+      console.log('\nℹ️  Note: User Management is disabled in the admin panel because it requires User Authentication.');
+    }
+
+    if (useAnalytics) {
+      console.log('\n🚨 3b. Admin Error Logging');
+      console.log('    Captures frontend/client-side errors (requires easy-analytics) and lists them');
+      console.log('    inside the admin panel, including descriptions and collapsible stack traces.');
+      const ansAdminErrors = await askQuestion('    Do you want to include Error Logging in the admin panel? (y/n) [y]: ');
+      useAdminErrors = ansAdminErrors.trim().toLowerCase() !== 'n';
+    } else {
+      console.log('\nℹ️  Note: Error Logging is disabled in the admin panel because it requires');
+      console.log('   Analytics Tracking to be enabled.');
+    }
+  }
+
+  console.log('\n⚡ 4. Server-Side Rendering (ssr-hook)');
+  console.log('   Enables server-side pre-rendering for React. Enhances initial load speeds,');
+  console.log('   prevents content flashes, and optimizes your site for search engine crawlers (SEO).');
+  const ansSSR = await askQuestion('   Do you want to enable Server-Side Rendering (SSR)? (y/n) [y]: ');
+  const useSSR = ansSSR.trim().toLowerCase() !== 'n';
+
+  console.log('\n🖼️  5. Social Preview og:image');
+  console.log('   Automatically screenshots and generates social preview card og:images for your pages');
+  console.log('   using a headless browser rendering engine (puppeteer) and caches them in the database.');
+  const ansOgImage = await askQuestion('   Do you want to include dynamic og:image generation? (y/n) [y]: ');
+  const useOgImage = ansOgImage.trim().toLowerCase() !== 'n';
+
+  console.log('\n📱 6. Viewport Tuning');
+  console.log('   Injects a viewport event listener that forces a minimum width layout (600px)');
+  console.log('   for mobile devices, resolving scaling/rendering issues on iOS Safari.');
+  const ansViewport = await askQuestion('   Do you want to fix iOS Safari viewport width issues? (y/n) [y]: ');
+  const useViewport = ansViewport.trim().toLowerCase() !== 'n';
+
+  console.log('\n🚢 7. Deployment Integration (node-ssh)');
+  console.log('   Configures deploy scripts and GitHub Actions workflows to build and transfer your code');
+  console.log('   via SSH straight to your own VPS (Virtual Private Server), where it runs managed by PM2.');
+  const ansDeploy = await askQuestion('   Do you want to include VPS deploy scripts? (y/n) [y]: ');
+  const useDeploy = ansDeploy.trim().toLowerCase() !== 'n';
 
   rl.close();
 
   const targetPath = path.join(process.cwd(), projectName);
 
   if (fs.existsSync(targetPath)) {
-    console.error(`Folder ${projectName} already exists!`);
+    console.error(`❌ Folder ${projectName} already exists!`);
     process.exit(1);
   }
 
@@ -49,6 +111,20 @@ async function main() {
 
   const templatePath = path.join(__dirname, '..', 'template');
 
+  // Ignored files based on configuration
+  const ignoreList = ['env'];
+  if (!useDeploy) {
+    ignoreList.push('scripts');
+    ignoreList.push('.github');
+  }
+  if (!useAuth) {
+    ignoreList.push('mail.tsx');
+    ignoreList.push('ResetPassword.tsx');
+  }
+  if (!useAdmin) {
+    ignoreList.push('admin');
+  }
+
   function copyFolderSync(from, to, ignoreFiles = []) {
     fs.mkdirSync(to, { recursive: true });
     fs.readdirSync(from).forEach(element => {
@@ -64,78 +140,177 @@ async function main() {
     });
   }
 
-  const ignoreList = includeDeploy ? [] : ['scripts', '.github'];
   copyFolderSync(templatePath, targetPath, ignoreList);
 
-  // Rename safe files back to dotfiles
-  if (fs.existsSync(path.join(targetPath, 'env'))) {
-    fs.renameSync(path.join(targetPath, 'env'), path.join(targetPath, '.env'));
-  }
+  // Rename gitignore to .gitignore
   if (fs.existsSync(path.join(targetPath, 'gitignore'))) {
     fs.renameSync(path.join(targetPath, 'gitignore'), path.join(targetPath, '.gitignore'));
   }
 
-  // Update site.webmanifest
-  const manifestPath = path.join(targetPath, 'src', 'site.webmanifest');
+  // Update site.webmanifest name
+  const manifestPath = path.join(targetPath, 'public', 'site.webmanifest');
   if (fs.existsSync(manifestPath)) {
     let manifestContent = fs.readFileSync(manifestPath, 'utf-8');
     manifestContent = manifestContent.replace(/__NAME__/g, projectName);
     fs.writeFileSync(manifestPath, manifestContent);
   }
 
-  // Handle Admin section removal if the user doesn't want it
-  if (!includeAdmin) {
-    const adminPath = path.join(targetPath, 'src', 'pages', 'admin');
-    if (fs.existsSync(adminPath)) {
-      fs.rmSync(adminPath, { recursive: true, force: true });
+  // Helper for processing feature block comments recursively
+  const startRegex = (blockName) => new RegExp(`(?:\\/\\/|\\/\\*|<!--)\\s*---\\s*${blockName}\\s*START\\s*---\\s*(?:\\*\\/|-->)?\\r?\\n?`, 'g');
+  const endRegex = (blockName) => new RegExp(`(?:\\/\\/|\\/\\*|<!--)\\s*---\\s*${blockName}\\s*END\\s*---\\s*(?:\\*\\/|-->)?\\r?\\n?`, 'g');
+  const fullRegex = (blockName) => new RegExp(`(?:\\/\\/|\\/\\*|<!--)\\s*---\\s*${blockName}\\s*START\\s*---\\s*(?:\\*\\/|-->)?\\r?\\n?[\\s\\S]*?(?:\\/\\/|\\/\\*|<!--)\\s*---\\s*${blockName}\\s*END\\s*---\\s*(?:\\*\\/|-->)?\\r?\\n?`, 'g');
+
+  function handleBlock(content, name, enabled) {
+    if (enabled) {
+      return content.replace(startRegex(name), '').replace(endRegex(name), '');
+    } else {
+      return content.replace(fullRegex(name), '');
     }
+  }
 
-    // Strip // --- ADMIN START --- ... // --- ADMIN END --- blocks
-    const stripAdminBlocks = (filePath) => {
-      if (fs.existsSync(filePath)) {
-        let content = fs.readFileSync(filePath, 'utf-8');
-        content = content.replace(/\/\/ --- ADMIN START ---[\s\S]*?\/\/ --- ADMIN END ---\n?/g, '');
-        fs.writeFileSync(filePath, content);
-      }
-    };
+  function processBlocks(content) {
+    content = handleBlock(content, 'AUTH', useAuth);
+    content = handleBlock(content, 'NO_AUTH', !useAuth);
+
+    content = handleBlock(content, 'VIEWPORT', useViewport);
+    
+    content = handleBlock(content, 'ADMIN', useAdmin);
+    content = handleBlock(content, 'NO_ADMIN', !useAdmin);
+
+    if (useAdmin) {
+      content = handleBlock(content, 'ADMIN_WITH_AUTH', useAuth);
+      content = handleBlock(content, 'ADMIN_NO_AUTH', !useAuth);
+      
+      content = handleBlock(content, 'ADMIN_USERS', useAuth && useAdminUsers);
+      content = handleBlock(content, 'NO_ADMIN_USERS', !(useAuth && useAdminUsers));
+
+      content = handleBlock(content, 'ADMIN_ERRORS', useAdminErrors);
+      content = handleBlock(content, 'NO_ADMIN_ERRORS', !useAdminErrors);
+
+      content = handleBlock(content, 'ADMIN_ERRORS_WITH_AUTH', useAdminErrors && useAuth);
+      content = handleBlock(content, 'ADMIN_ERRORS_NO_AUTH', useAdminErrors && !useAuth);
+    } else {
+      content = handleBlock(content, 'ADMIN_WITH_AUTH', false);
+      content = handleBlock(content, 'ADMIN_NO_AUTH', false);
+
+      content = handleBlock(content, 'ADMIN_USERS', false);
+      content = handleBlock(content, 'NO_ADMIN_USERS', true);
+
+      content = handleBlock(content, 'ADMIN_ERRORS', false);
+      content = handleBlock(content, 'NO_ADMIN_ERRORS', true);
 
-    stripAdminBlocks(path.join(targetPath, 'src', 'Router.tsx'));
-    stripAdminBlocks(path.join(targetPath, 'server', 'index.tsx'));
-    stripAdminBlocks(path.join(targetPath, 'src', 'styles.scss'));
+      content = handleBlock(content, 'ADMIN_ERRORS_WITH_AUTH', false);
+      content = handleBlock(content, 'ADMIN_ERRORS_NO_AUTH', false);
+    }
+
+    content = handleBlock(content, 'ANALYTICS', useAnalytics);
+    content = handleBlock(content, 'NO_ANALYTICS', !useAnalytics);
+
+    content = handleBlock(content, 'SSR', useSSR);
+    content = handleBlock(content, 'NO_SSR', !useSSR);
+
+    content = handleBlock(content, 'OGIMAGE', useOgImage);
+
+    return content;
   }
 
-  // Update package.json from template
+  function processDirectory(directory) {
+    fs.readdirSync(directory).forEach(element => {
+      const fullPath = path.join(directory, element);
+      const stat = fs.lstatSync(fullPath);
+      if (stat.isDirectory()) {
+        processDirectory(fullPath);
+      } else if (stat.isFile()) {
+        const ext = path.extname(element);
+        const textExtensions = ['.ts', '.tsx', '.js', '.jsx', '.css', '.html', '.cursorrules', '.webmanifest', 'README.md'];
+        if (textExtensions.includes(ext) || element === '.cursorrules' || element === 'README.md') {
+          let fileContent = fs.readFileSync(fullPath, 'utf-8');
+          fileContent = processBlocks(fileContent);
+          fileContent = fileContent.replace(/__NAME__/g, projectName);
+          fs.writeFileSync(fullPath, fileContent);
+        }
+      }
+    });
+  }
+
+  processDirectory(targetPath);
+
+  // Generate dynamic package.json
   const packageJsonPath = path.join(targetPath, 'package.json');
   if (fs.existsSync(packageJsonPath)) {
     const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
     pkg.name = projectName;
 
-    if (includeDeploy) {
-      pkg.devDependencies = pkg.devDependencies || {};
+    if (useAnalytics) {
+      pkg.dependencies['easy-analytics'] = '^1.0.1';
+    }
+    if (useAuth) {
+      pkg.dependencies['easy-user-auth'] = '^1.0.6';
+      pkg.dependencies['nodemailer'] = '^7.0.9';
+      pkg.devDependencies['@types/nodemailer'] = '^6.4.15';
+    }
+    if (useSSR) {
+      pkg.dependencies['ssr-hook'] = '^0.2.0';
+    }
+    if (useOgImage) {
+      pkg.dependencies['puppeteer'] = '^25.3.0';
+    }
+    if (useDeploy) {
       pkg.devDependencies['node-ssh'] = '^13.2.1';
       pkg.scripts = pkg.scripts || {};
       pkg.scripts['deploy'] = 'tsx scripts/deploy.ts';
-    } else if (pkg.scripts && pkg.scripts.deploy) {
-      delete pkg.scripts.deploy;
+    } else {
+      if (pkg.scripts && pkg.scripts.deploy) {
+        delete pkg.scripts.deploy;
+      }
     }
 
     fs.writeFileSync(packageJsonPath, JSON.stringify(pkg, null, 2));
   }
 
+  // Generate dynamic .env file
+  const envPath = path.join(targetPath, '.env');
+  let envContent = `SERVER_PORT=1111\nSERVER_URL=https://${projectName}.com\n`;
+
+  if (useAdmin && !useAuth) {
+    envContent += `ADMIN_PASSWORD=admin123\n`;
+  }
+
+  if (useAuth) {
+    const jwtSecret = crypto.randomBytes(32).toString('hex');
+    envContent += `\n# Authentication\nJWT_SECRET=${jwtSecret}\n`;
+    envContent += `# SMTP mail configuration (required for forgotten password recovery)\nMAIL_SMTP=smtp.example.com\nMAIL_PORT=587\nMAIL_USER=your-email@example.com\nMAIL_PASSWORD=your-email-password\n`;
+  }
+
+  fs.writeFileSync(envPath, envContent);
+
   console.log('📦 Installing dependencies (this may take a while)...');
   try {
     execSync('npm install', { cwd: targetPath, stdio: 'inherit' });
   } catch (error) {
-    console.error('❌ Failed to install dependencies.', error);
-    process.exit(1);
+    console.warn('\n⚠️  Failed to install dependencies with default npm install (often due to Puppeteer browser download issue).');
+    console.log('Retrying with PUPPETEER_SKIP_DOWNLOAD=1...');
+    try {
+      execSync('npm install', { cwd: targetPath, stdio: 'inherit', env: { ...process.env, PUPPETEER_SKIP_DOWNLOAD: '1' } });
+    } catch (retryError) {
+      console.error('❌ Failed to install dependencies on retry.', retryError);
+      process.exit(1);
+    }
   }
 
   console.log(`\n🎉 Project ${projectName} has been successfully created!`);
-  console.log('\nGetting started:');
+  console.log('\n🚀 Getting started:');
   console.log(`  cd ${projectName}`);
-  console.log('  npm run dev -> http://localhost:1234');
-  if (includeDeploy) {
-    console.log('  npm run deploy');
+  console.log('  npm run dev  (Starts backend and Vite frontend dev server at http://localhost:5173)');
+  
+  if (useAuth) {
+    console.log('\n⚠️  IMPORTANT FOR AUTHENTICATION:');
+    console.log('   Configure your SMTP settings inside the generated .env file');
+    console.log('   to enable password recovery email delivery.');
+  }
+
+  if (useDeploy) {
+    console.log('  npm run deploy (Deploy to your VPS)');
   }
 }
 

package/package.json

@@ -1,24 +1,33 @@
 {
     "name": "easy-starter",
-    "version": "1.2.0",
-    "description": "A lightweight CLI tool to bootstrap modern fullstack React web projects.",
+    "version": "2.0.0",
+    "description": "A lightweight, production-ready fullstack React boilerplate generator with Vite v8, TypeScript 7, server-side rendering (SSR), local analytics, SSH deploy script, PM2, and secure user authentication.",
     "bin": {
         "easy-starter": "./bin/index.js"
     },
     "keywords": [
         "cli",
-        "bootstrap",
-        "starter",
-        "react",
-        "easy",
+        "boilerplate",
+        "starter-kit",
+        "react-starter",
+        "vite-template",
+        "typescript-boilerplate",
+        "fullstack-boilerplate",
+        "server-side-rendering",
         "ssr",
-        "typescript",
-        "fullstack",
+        "user-authentication",
+        "user-login",
+        "easy-user-auth",
+        "easy-analytics",
         "easy-db",
-        "parcel",
-        "ai",
+        "local-database",
+        "pm2-deployment",
+        "vps-deploy",
+        "ssh-deployment",
+        "ai-friendly",
         "cursorrules",
-        "ai-friendly"
+        "quickstart",
+        "zero-config"
     ],
     "author": "Filip Paulů <ing.fenix@seznam.cz>",
     "license": "MIT",

package/template/.cursorrules

@@ -90,3 +90,26 @@ export type Database = {
   // CORRECT (custom ID):
   await update("item", "explicit-custom-id", { name: "Custom ID Item", value: 99 });
   ```
+
+---
+
+## 4. Styling & Image Manipulation Guidelines
+
+### CSS Implementation
+* **Centralized & Generic**: Implement as many styles as possible in `src/styles.css` using generic, reusable selectors.
+* **Minimize Inline Styles**: Avoid inline styles (e.g., `style={{ ... }}`) in React components. Keep style declarations in the central CSS file to maintain design consistency and code quality.
+
+### Image Asset Handling
+* **Use `vite-imagetools` Exclusively in CSS:**
+  - When loading local images for styling and background layouts, reference them exclusively inside CSS `url()` declarations, appending `vite-imagetools` query parameters (such as `format=webp` and dimensions `w=`) to automatically optimize them.
+  - **CORRECT (CSS):**
+    ```css
+    .hero-banner {
+        background-image: url("./assets/hero.jpg?format=webp&w=1200");
+    }
+    ```
+* **JavaScript Imports for Images are Forbidden:**
+  - Do **NOT** import image assets inside `.js`, `.ts`, or `.tsx` files (e.g. do NOT write `import hero from "./hero.jpg"`).
+* **Referencing Images in TSX/React (Only via `/public`):**
+  - If you need to reference or display an image directly inside React TSX components (e.g., standard `<img>` tags or SEO metadata), **you must place the pre-optimized WebP image inside the `/public` directory** and reference it using a standard absolute URL path.
+  - **CORRECT (TSX):** `<img src="/images/logo.webp" alt="Logo" />` (with the file stored inside `/public/images/logo.webp`).

package/template/.github/workflows/deploy.yml

@@ -26,4 +26,7 @@ jobs:
           SSH_HOST: ${{ secrets.SSH_HOST }}
           SSH_USERNAME: ${{ secrets.SSH_USERNAME }}
           SSH_PASSWORD: ${{ secrets.SSH_PASSWORD }}
+          SSH_PATH: ${{ secrets.SSH_PATH }}
+          PM2_APP_NAME: ${{ secrets.PM2_APP_NAME }}
+          SERVER_URL: ${{ secrets.SERVER_URL }}
         run: npm run deploy