easy-starter 1.1.0 → 1.2.1

package/README.md

@@ -33,6 +33,7 @@ The generated boilerplate comes pre-configured with a stack designed for develop
 * **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.
 * **Routing:** [`easy-page-router`](https://www.npmjs.com/package/easy-page-router) - A lightweight, programmatic routing solution.
 * **Analytics:** [`easy-analytics`](https://www.npmjs.com/package/easy-analytics) - Privacy-friendly, local analytics tracking.
+* **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
@@ -96,6 +97,10 @@ export default function Index() {
 }
 ```
 
+### 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:

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "easy-starter",
-    "version": "1.1.0",
+    "version": "1.2.1",
     "description": "A lightweight CLI tool to bootstrap modern fullstack React web projects.",
     "bin": {
         "easy-starter": "./bin/index.js"
@@ -15,7 +15,10 @@
         "typescript",
         "fullstack",
         "easy-db",
-        "parcel"
+        "parcel",
+        "ai",
+        "cursorrules",
+        "ai-friendly"
     ],
     "author": "Filip Paulů <ing.fenix@seznam.cz>",
     "license": "MIT",

package/template/.cursorrules

@@ -0,0 +1,108 @@
+# AI Coding Assistant Guidelines & Project Rules
+
+You are an expert AI software engineer pair-programming in a fullstack React application bootstrapped with `easy-starter`.
+Follow these strict rules, project structures, and conventions at all times.
+
+---
+
+## 1. API Architecture & Type Safety (`typed-client-server-api`)
+
+All React-to-Express communication must use the RPC contract defined in `types.ts` via the `API` type (`APIDefinition`).
+
+### Naming Conventions for Endpoints
+EVERY endpoint name in `API` **MUST** start with exactly one of the following prefixes:
+* `add...` (Create/Insert operations. Example: `addItem`, `addRecord`)
+* `get...` (Read/Query operations. Example: `getItems`, `getItem`, `getAnalytics`)
+* `update...` (Update/Edit operations. Example: `updateItem`, `updateUser`)
+* `remove...` (Delete/Remove operations. Example: `removeItem`, `removePost`)
+
+**CRITICAL**: Do NOT use other prefixes (e.g., `create`, `delete`, `post`, `fetch`, `save`).
+
+### Frontend API Invocation Methods
+You have exactly three (3) methods to trigger API endpoints on the frontend. Use them strictly according to these boundaries:
+
+| Method | Import | Use Case | Pattern / Example |
+| :--- | :--- | :--- | :--- |
+| **`useSSRApi`** | `import { useSSRApi } from "../services/api";` | **ONLY** inside React components during initial SSR render. Enables server-side rendering and hydration without flash-of-loading or spinners. | `const [items, error, isLoading, reload] = useSSRApi.getItems({});` |
+| **`useApi`** | `import { useApi } from "../services/api";` | **ONLY** inside React components for client-side-only reactive data fetching (e.g., late loaded components). | `const [items, error, isLoading, reload] = useApi.getItems({});` |
+| **`api`** | `import { api } from "../services/api";` | **ONLY** inside event handlers (e.g., `onClick`, `onSubmit`), utility/non-React functions, or async triggers. Returns a Promise resolving to `[data, error]`. | `const [newId, err] = await api.addItem({ name: "Foo" });` |
+
+**NEVER** use standard `fetch`, `axios`, or any other fetcher libraries for internal API calls.
+
+---
+
+## 2. Routing & Navigation (`easy-page-router`)
+
+This project uses `easy-page-router`, a lightweight, universal routing library.
+
+### Route Configurations
+* Router paths are defined in `src/Router.tsx` within the `renderPage({ path })` callback of the `Router` component.
+* The `path` parameter is a string array (`string[]`) of URL segments:
+  * `/` -> `path.length === 0`
+  * `/admin` -> `path[0] === "admin"`
+  * `/users/123` -> `path[0] === "users" && path[1]` (where `path[1]` is the user ID segment).
+
+### Navigation
+1. **Declarative Navigation**: Use `<Link href="/path">Text</Link>` imported from `"easy-page-router/react"`.
+2. **Programmatic Navigation**: Destructure `push` from the `useRouter()` hook imported from `"easy-page-router/react"`.
+
+```tsx
+import { Link, useRouter } from "easy-page-router/react";
+
+// Declarative:
+<Link href="/admin">Go to Admin</Link>
+
+// Programmatic:
+const { push } = useRouter();
+const onSubmit = async () => {
+    await saveSomething();
+    push("/dashboard");
+};
+```
+
+---
+
+## 3. Database Operations (`easy-db-node`)
+
+The local database stores records as JSON files.
+
+### Schema Definition
+* The database collections/tables must be structured and typed in `types.ts` inside the exported `Database` type.
+```typescript
+export type Database = {
+    item: Item;
+    user: User;
+};
+```
+
+### Writing to Database
+* **Auto-generated ID (Standard Insertion)**:
+  * Use `insert(table, data)`.
+  * **Rule**: Do **NOT** pass `_id` in the input data. `easy-db-node` ignores any `_id` property passed to `insert()` and automatically generates and returns the unique string ID.
+  ```typescript
+  // CORRECT:
+  const newId = await insert("item", { name: "Hello", value: 10 });
+  ```
+
+* **Custom / Specific ID (Explicit Key)**:
+  * To insert or overwrite a record with a **specific/predefined ID**, you **MUST** use `update(table, id, data)` instead of `insert`.
+  ```typescript
+  // CORRECT (custom ID):
+  await update("item", "explicit-custom-id", { name: "Custom ID Item", value: 99 });
+  ```
+
+---
+
+## 4. Styling & Image Manipulation Guidelines
+
+### CSS / SCSS Implementation
+* **Centralized & Generic**: Implement as many styles as possible in `src/styles.scss` using generic, reusable selectors.
+* **Minimize Inline Styles**: Avoid inline styles (e.g., `style={{ ... }}`) in React components. Keep style declarations in the central SCSS file to maintain design consistency and code quality.
+
+### Image Asset Handling
+* **STRONG PREFERENCE**: It is highly preferred to insert images as `background-image` declarations inside `src/styles.scss` rather than using `<img>` tags in React components wherever possible.
+* **CRITICAL FOR SCSS**: When referencing images inside `src/styles.scss` (e.g., as background-image), always append the `?as=webp` query parameter to convert them to modern WebP format during build, unless the source file is already an `.svg`. Do specify width or height query parameters.
+  * **CORRECT**: `background-image: url("./images/icon.png?as=webp&height=128");`
+* **CRITICAL FOR CODE (React / HTML / JavaScript)**: If you must reference an image path directly within the code (e.g., in `<img src="..." />` or JS variables), you **MUST** only refer to images located inside the `public` directory (and nowhere else).
+  * **CORRECT**: `<img src="/logo.png" />` (when referencing `/public/logo.png`)
+  * **INCORRECT**: `<img src="../src/images/logo.png" />` or importing images directly into React files.

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

package/template/README.md

@@ -83,6 +83,10 @@ export default function Index() {
 }
 ```
 
+### 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`:
+
 ## Scripts
 
 * `npm run dev` - Starts the development server.
@@ -94,7 +98,8 @@ export default function Index() {
 
 * `/src` - Your React frontend code.
 * `/server` - Your Express backend code.
-* `/types.d.ts` - Shared TypeScript definitions for your API and Database.
+* `/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.
 

package/template/env

@@ -1,8 +1,12 @@
-NODE_ENV=development
+NODE_ENV=development # development/production
 SERVER_PORT=1111
 ADMIN_PASSWORD=admin
 
+SERVER_URL=https://your-production-url.com/
+
 # deploy
-SSH_HOST=***
-SSH_USERNAME=***
-SSH_USERNAME=***
+SSH_HOST=[IP_ADDRESS]
+SSH_USERNAME=root
+SSH_PASSWORD=[PASSWORD]
+SSH_PATH=/root/easy-starter-app
+PM2_APP_NAME=easy-starter-app

package/template/scripts/deploy.ts

@@ -9,22 +9,28 @@ const username = process.env.SSH_USERNAME;
 const password = process.env.SSH_PASSWORD;
 
 // Configuration for your target server
-const server = "https://your-production-url.com/";
-const pm2AppName = "easy-starter-app"; // The name of the process in PM2
-const sshPath = resolve("/", "root", "your-production-url.com"); // Path on the remote VPS
+const server = process.env.SERVER_URL;
+const pm2AppName = process.env.PM2_APP_NAME;
+const sshPath = process.env.SSH_PATH; // Path on the remote VPS
 
 const path = resolve(process.cwd()); // Local project path
 const ignoreFiles = [
     ".git",
+    ".github",
+    ".parcel-cache",
     "node_modules",
     "scripts",
-    ".github"
+    "easy-db",
+    "easy-db-files",
+    "easy-db-backup",
+    ".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();
 
@@ -73,20 +79,28 @@ async function deploy() {
     console.log(`✔ Build project.\n`);
 
     // PM2
-    try {
-        await sshExec(ssh, `pm2 reload ${pm2AppName}`);
-    } catch (e) {
-        console.log(`✘ ${pm2AppName} is not running in PM2!`);
-        await sshExec(ssh, `pm2 start npm --name "${pm2AppName}" -- start`, `${pm2AppName} could not be registered in PM2!`);
+    if (pm2AppName) {
+        try {
+            await sshExec(ssh, `pm2 reload ${pm2AppName}`);
+        } catch (e) {
+            console.log(`✘ ${pm2AppName} is not running in PM2!`);
+            await sshExec(ssh, `pm2 start npm --name "${pm2AppName}" -- start`, `${pm2AppName} could not be registered in PM2!`);
+        }
+        await sshExec(ssh, `pm2 list`);
+    } else {
+        console.log(`i PM2 step is skipped because PM2_APP_NAME is not defined.\n`);
     }
-    await sshExec(ssh, `pm2 list`);
 
     ssh.dispose();
     console.log(`✔ SSH connection is closed.\n`);
 
-    if (!await serverCheck(server))
-        throw new Error(`Server ${server} is not available!`);
-    console.log(`✔ Server ${server} is running.\n`);
+    if (server) {
+        if (!await serverCheck(server))
+            throw new Error(`Server ${server} is not available!`);
+        console.log(`✔ Server ${server} is running.\n`);
+    } else {
+        console.log(`i Server check is skipped because SERVER_URL is not defined.\n`);
+    }
 
     console.log(`i Server was ${(new Date().getTime() - timeServerOff) / 1000}s off!\n`);
 

package/template/server/index.tsx

@@ -4,19 +4,10 @@ import { readFile } from "fs/promises";
 import cors from "cors";
 import express from "express";
 
-// easy-db-node provides a simple local database storing data in JSON files.
-// It's ideal for small to medium projects where setting up a full SQL/NoSQL DB is overkill.
 import easyDBNode from "easy-db-node";
-
-// ssr-hook allows for simple Server-Side Rendering of React components, 
-// ensuring SEO friendliness and faster initial page loads.
 import { renderToHTML } from "ssr-hook/server";
-
-// typed-client-server-api establishes a type-safe RPC-like API between your React frontend
-// and this Express backend, preventing mismatch errors and providing autocomplete.
 import { setAPIBackend } from "typed-client-server-api";
 
-// easy-analytics handles privacy-friendly local analytics collection.
 import { postEasyAnalytics, getEasyAnalytics } from "easy-analytics/server";
 
 import App from "../src/App";
@@ -29,7 +20,7 @@ const LOCALHOST = `http://localhost:${PORT}`;
 // The ORIGIN is used for SEO and by ssr-hook to know where the requests are coming from.
 const ORIGIN = process.env.NODE_ENV === "development"
     ? LOCALHOST
-    : "https://your-production-url.com"; // TODO: Update to your domain
+    : process.env.SERVER_URL;
 
 const INDEX_HTML_PATH = resolve(__dirname, "..", "dist", "index.html");
 

package/template/src/pages/admin/Admin.tsx

@@ -1,6 +1,7 @@
 import React, { useEffect, useState } from "react";
 import { useGroup, GroupTable, getGroupedCount } from "easy-analytics/react";
 import { Link } from "easy-page-router/react";
+
 import { useHead } from "../../services/common";
 import { api, handleError } from "../../services/api";
 

package/template/tsconfig.json

@@ -18,6 +18,6 @@
   "include": [
     "src/**/*",
     "server/**/*",
-    "types.d.ts"
+    "types.ts"
   ]
 }

package/template/{types.d.ts → types.ts}

@@ -22,5 +22,5 @@ export type Item = {
 // The Database type defines the structure of your JSON files managed by easy-db-node.
 // Each property represents a 'table' (or a separate JSON file).
 export type Database = {
-    item: Omit<Item, "_id">;
+    item: Item;
 };