easy-starter 1.0.0 → 1.2.0

package/README.md

@@ -33,8 +33,74 @@ 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
+
+> **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!
+
+### 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.
+
+```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:

package/bin/index.js

@@ -71,6 +71,9 @@ async function main() {
   if (fs.existsSync(path.join(targetPath, 'env'))) {
     fs.renameSync(path.join(targetPath, 'env'), path.join(targetPath, '.env'));
   }
+  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');
@@ -98,6 +101,7 @@ async function main() {
 
     stripAdminBlocks(path.join(targetPath, 'src', 'Router.tsx'));
     stripAdminBlocks(path.join(targetPath, 'server', 'index.tsx'));
+    stripAdminBlocks(path.join(targetPath, 'src', 'styles.scss'));
   }
 
   // Update package.json from template

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "easy-starter",
-    "version": "1.0.0",
+    "version": "1.2.0",
     "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,92 @@
+# 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 });
+  ```

package/template/README.md

@@ -22,6 +22,71 @@ npm run dev
 
 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
+
+> **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!
+
+### 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.
+
+```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`:
+
 ## Scripts
 
 * `npm run dev` - Starts the development server.
@@ -33,7 +98,8 @@ This will concurrently start your Express server and the Parcel bundler. Open [h
 
 * `/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,7 +1,10 @@
-NODE_ENV=development
+NODE_ENV=development # development/production
 SERVER_PORT=1111
 ADMIN_PASSWORD=admin
 
-SSH_HOST=***
+# deploy
+SSH_HOST=[IP_ADDRESS]
 SSH_USERNAME=root
-SSH_USERNAME=***
+SSH_PASSWORD=[PASSWORD]
+SERVER_URL=https://your-production-url.com/
+PM2_APP_NAME=easy-starter-app

package/template/gitignore

@@ -0,0 +1,9 @@
+.parcel-cache/
+node_modules/
+dist/
+easy-db/
+easy-db-files/
+easy-db-backup/
+.DS_Store
+.env
+package-lock.json

package/template/package.json

@@ -19,12 +19,9 @@
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
     "ssr-hook": "^0.2.0",
-    "typed-client-server-api": "^1.0.3"
+    "typed-client-server-api": "^1.1.0"
   },
   "devDependencies": {
-    "@parcel/packager-raw-url": "^2.16.4",
-    "@parcel/transformer-sass": "^2.16.4",
-    "@parcel/transformer-webmanifest": "^2.16.4",
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.6",
     "@types/node": "^24.0.0",
@@ -32,7 +29,6 @@
     "@types/react-dom": "^19.2.3",
     "concurrently": "^9.2.1",
     "parcel": "^2.16.4",
-    "sharp": "^0.33.5",
     "tsx": "^4.21.0",
     "typescript": "^6.0.3"
   }

package/template/scripts/deploy.ts

@@ -9,16 +9,21 @@ 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 = resolve("/", "root", pm2AppName || ""); // 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
@@ -73,20 +78,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

@@ -1,7 +1,8 @@
 import { resolve } from "path";
 import { readFile } from "fs/promises";
-import express from "express";
+
 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.
@@ -19,12 +20,13 @@ import { setAPIBackend } from "typed-client-server-api";
 import { postEasyAnalytics, getEasyAnalytics } from "easy-analytics/server";
 
 import App from "../src/App";
+
 import { API, Database } from "../types";
 
 const PORT = process.env.SERVER_PORT || 1111;
 const LOCALHOST = `http://localhost:${PORT}`;
 
-// The ORIGIN is used by ssr-hook and typed-client-server-api to know where the requests are coming from.
+// 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
@@ -47,12 +49,9 @@ if (process.env.NODE_ENV === "development") {
 }
 
 // ---------------------------- SSR for index ----------------------------------
-// This route handles the initial load of our application and renders the React tree to HTML.
 app.get(["/", "/index.html"], async (req, res) => {
     try {
-        // We read the HTML template generated by our bundler (Parcel)
         const indexHtml = await readFile(INDEX_HTML_PATH, "utf-8");
-        // We render our App component into that HTML template.
         const html = await renderToHTML(ORIGIN, req.url, indexHtml, <App />);
         res.set("Content-Type", "text/html");
         res.send(html);
@@ -67,9 +66,10 @@ app.get(["/", "/index.html"], async (req, res) => {
 app.use(express.static("dist"));
 // Serve any public assets (like images, fonts)
 app.use(express.static("public"));
-// Serve the database files (e.g. uploaded images or JSON files from easy-db-node)
+// Serve the database files (e.g. uploaded images or PDF files from easy-db-node)
 app.use("/files", express.static("easy-db-files"));
 
+
 // --------------------------------- SEO ---------------------------------------
 // Basic configuration for search engine crawlers.
 app.get("/robots.txt", (_, res) => {
@@ -83,7 +83,7 @@ app.get("/sitemap.xml", async (_, res) => {
     // TODO: add all pages
     const sitemap = [{
         url: ORIGIN + "/",
-        lastModified: "2024-01-01",
+        lastModified: "2026-01-01",
         changeFrequency: "weekly",
         priority: 1,
     }];
@@ -98,10 +98,11 @@ app.get("/sitemap.xml", async (_, res) => {
     </url>`).join("\n")}</urlset>`);
 });
 
-// --------------------------- Easy analytics ----------------------------------
+
 // This parses incoming JSON payloads for the API and analytics.
 app.use(express.json({ limit: "1MB" }));
 
+// --------------------------- Easy analytics ----------------------------------
 // Endpoint to receive analytics data from the client.
 app.post("/api/easy-analytics", async (req, res) => {
     const userAgent = req.headers['user-agent'] || "";
@@ -116,12 +117,9 @@ app.post("/api/easy-analytics", async (req, res) => {
     }
 });
 
-// --- ADMIN START ---
-// --- ADMIN END ---
-
 // --------------------------------- API ---------------------------------------
 // Set up our type-safe API backend. All functions defined here map directly to the
-// API type defined in types.d.ts, and can be called from the frontend using the api() client.
+// API type defined in types.d.ts, and can be called from the frontend using by api., useApi., or useSSRApi.
 setAPIBackend<API>(app, {
     async getItems() {
         return await selectArray("item");
@@ -150,8 +148,8 @@ setAPIBackend<API>(app, {
     // --- ADMIN END ---
 });
 
-// --------------------------------- SSR ---------------------------------------
 
+// --------------------------------- SSR ---------------------------------------
 app.get(/.*/, async (req, res) => {
     try {
         const indexHtml = await readFile(INDEX_HTML_PATH, "utf-8");
@@ -165,6 +163,7 @@ app.get(/.*/, async (req, res) => {
     }
 });
 
+
 // Start listening for incoming requests.
 app.listen(PORT, () => {
     console.log(`Server is running on ${LOCALHOST}`);

package/template/src/App.tsx

@@ -1,22 +1,15 @@
-// RouterProvider manages the browser history and current route state.
-import { RouterProvider } from "easy-page-router";
-
-// init sets up the easy-analytics client to start tracking page views and custom events.
 import { init } from "easy-analytics/client";
+import { RouterProvider } from "easy-page-router";
 
 import Router from "./Router";
 
-// Initialize analytics. It sends data to our Express backend endpoint.
+// Initialize analytics. It sends data to our backend endpoint.
 init(process.env.NODE_ENV === "development"
     ? "http://localhost:1111/api/easy-analytics"
     : "/api/easy-analytics");
 
 export default function App() {
-    return (
-        // The RouterProvider must wrap your application router so that 
-        // nested components can react to URL changes.
-        <RouterProvider>
-            <Router />
-        </RouterProvider>
-    );
+    return <RouterProvider>
+        <Router />
+    </RouterProvider>;
 }

package/template/src/Router.tsx

@@ -3,6 +3,7 @@ import { Router } from "easy-page-router/react";
 import Index from "./pages/Index";
 import NotFound from "./pages/NotFound";
 // --- ADMIN START ---
+
 import { lazy, Suspense } from "react";
 const Admin = lazy(() => import("./pages/admin/Admin"));
 // --- ADMIN END ---
@@ -12,10 +13,10 @@ export default function AppRouter() {
         renderPage={({ path }) => {
             // The 'path' variable is an array of strings representing the URL segments.
             // For example, "/users/123" would be ["users", "123"].
-            
+
             // If the path is empty, we are at the root URL (/).
             if (path.length === 0) return <Index />;
-            
+
             // --- ADMIN START ---
             if (path[0] === 'admin') return (
                 <Suspense fallback={<div style={{ padding: 40, textAlign: 'center' }}>Loading admin...</div>}>
@@ -23,11 +24,11 @@ export default function AppRouter() {
                 </Suspense>
             );
             // --- ADMIN END ---
-            
+
             // You can add more routes here, for example:
             // if (path[0] === 'about') return <AboutPage />;
             // if (path[0] === 'users' && path[1]) return <UserPage id={path[1]} />;
-            
+
             // If no routes match, render a 404 Not Found component.
             return <NotFound />;
         }}

package/template/src/index.tsx

@@ -1,8 +1,6 @@
 import React from "react";
 import { createRoot, hydrateRoot } from "react-dom/client";
 
-// ssr-hook requires knowing the backend origin to fetch initial state during SSR.
-import { setSSROrigin } from "ssr-hook";
 import { handleError } from "./services/api";
 
 import App from "./App";
@@ -10,10 +8,6 @@ import App from "./App";
 const rootElement = document.getElementById("root") as HTMLElement;
 
 if (process.env.NODE_ENV === "development") {
-    // In development mode, the frontend (Parcel) and backend (Express) run on different ports.
-    // We explicitly tell ssr-hook where the API backend is located.
-    setSSROrigin("http://localhost:1111"); 
-    
     // We use createRoot because we often don't want to deal with full SSR hydration quirks 
     // during local frontend development (like Hot Module Replacement causing mismatches).
     createRoot(rootElement).render(<App />);

package/template/src/pages/Index.tsx

@@ -1,18 +1,17 @@
 import { useState } from "react";
-// useSSRHook is a specialized hook that fetches data both on the server (during SSR)
-// and on the client. It ensures the HTML generated on the server already contains the data.
-import { useSSRHook } from "ssr-hook";
-
-import { api, handleError } from "../services/api";
-import { API, Item } from "../../types";
 import { Link } from "easy-page-router/react";
 
+import { api, useSSRApi } from "../services/api";
 import { useHead } from "../services/common";
 
+import { Item } from "../../types";
+
 export default function Index() {
-    useHead("Welcome to easy-starter", "The ultimate foundation for your next project.");
+    useHead({ title: "Welcome to easy-starter", description: "The ultimate foundation for your next project." });
 
-    const [items, error, loading, reload] = useSSRHook<API["getItems"]["result"]>("/api/items");
+    // 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, loading, reload] = useSSRApi.getItems({});
 
     const [selectedItem, setSelectedItem] = useState<Item | null>(null);
     const [selectedLoading, setSelectedLoading] = useState(false);
@@ -26,7 +25,6 @@ export default function Index() {
         const [item, err] = await api.getItem({ id });
         setSelectedLoading(false);
         if (item) setSelectedItem(item);
-        if (err) handleError(err);
     }
 
     async function handleAdd(e: React.FormEvent) {
@@ -39,28 +37,26 @@ export default function Index() {
             setNewItemValue("");
             reload();
         }
-        if (err) handleError(err);
     }
 
     async function handleRemove(id: string) {
         if (!confirm("Are you sure you want to delete this item?")) return;
         const [success, err] = await api.removeItem({ id });
         if (success) reload();
-        if (err) handleError(err);
     }
 
     return (
-        <div className="container">
-            <div className="hero">
-                <div className="app-icon"></div>
-                <h1>Welcome to easy-starter! 🚀</h1>
+        <main>
+            <header>
+                <figure></figure>
+                <h1>Welcome to easy-starter!</h1>
                 <p>The ultimate foundation for your next project.</p>
                 <Link href="/admin">
                     → Go to Admin Dashboard
                 </Link>
-            </div>
+            </header>
 
-            <div className="api-test">
+            <section>
                 <h2>Items (SSR Hook)</h2>
                 {loading && <p>Loading from server...</p>}
                 {error && <p>Error loading items: {error.message}</p>}
@@ -69,10 +65,10 @@ export default function Index() {
                         {items.map(item => (
                             <li key={item._id}>
                                 <span><strong>{item.name}</strong> - {item.value}</span>
-                                <div>
+                                <nav>
                                     <button onClick={() => handleView(item._id!)}>View Details</button>
-                                    <button className="btn-danger" onClick={() => handleRemove(item._id!)} style={{ marginLeft: 8 }}>Delete</button>
-                                </div>
+                                    <button className="btn-danger" onClick={() => handleRemove(item._id!)}>Delete</button>
+                                </nav>
                             </li>
                         ))}
                     </ul>
@@ -81,15 +77,15 @@ export default function Index() {
 
                 {selectedLoading && <p>Loading item details...</p>}
                 {selectedItem && (
-                    <div className="item-details">
+                    <article>
                         <h3>Selected Item:</h3>
                         <p>ID: {selectedItem._id}</p>
                         <p>Name: {selectedItem.name}</p>
                         <p>Value: {selectedItem.value}</p>
-                    </div>
+                    </article>
                 )}
 
-                <h3 style={{ marginTop: 20 }}>Add New Item</h3>
+                <h3>Add New Item</h3>
                 <form onSubmit={handleAdd}>
                     <input
                         type="text"
@@ -109,7 +105,7 @@ export default function Index() {
                         {adding ? "Adding..." : "Add"}
                     </button>
                 </form>
-            </div>
-        </div>
+            </section>
+        </main>
     );
 }

package/template/src/pages/NotFound.tsx

@@ -1,8 +1,9 @@
-import { useHead } from "../services/common";
 import { Link } from "easy-page-router/react";
 
+import { useHead } from "../services/common";
+
 export default function NotFound() {
-    useHead("404 Not Found", "Page you are looking for does not exist.");
+    useHead({ title: "404 Not Found", description: "Page you are looking for does not exist." });
 
     return (
         <div style={{ padding: "40px", textAlign: "center", fontFamily: "sans-serif" }}>

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

@@ -1,11 +1,12 @@
 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";
 
 export default function Admin() {
-    useHead("Analytics Dashboard", "View statistics and analytics for your application.");
+    useHead({ title: "Analytics Dashboard", description: "View statistics and analytics for your application." });
 
     const [password, setPassword] = useState("");
     const [loggedIn, setLoggedIn] = useState(false);
@@ -34,7 +35,7 @@ export default function Admin() {
                 setLoggedIn(true);
                 localStorage.setItem("admin_pwd", pwd);
             } else if (err) {
-                setError(err.message || "Invalid password or server error");
+                setError(err);
                 setLoggedIn(false);
                 localStorage.removeItem("admin_pwd");
             }
@@ -77,7 +78,7 @@ export default function Admin() {
         return "Unknown";
     });
 
-    // Simplified UA parser
+    // Simplified UA parser - for production consider using a library like 'ua-parser-js'
     const byBrowserLike = useGroup(records, (r: any) => {
         const ua = (r.userAgent || "").toLowerCase();
         if (ua.includes("firefox")) return "Firefox";

package/template/src/services/api.ts

@@ -1,10 +1,25 @@
 import { useEffect } from "react";
 import { sendError } from "easy-analytics/client";
 import { setServerUrl, getUseAPIFrontend, getAPIFrontend, setHeaders } from "typed-client-server-api/hooks";
+import { useSSRHook } from "ssr-hook/client";
+import { setSSROrigin } from "ssr-hook";
 
 import { API } from "../../types";
 
-setServerUrl(process.env.NODE_ENV === "development" ? "http://localhost:1111" : "");
+export type UseSSRAPIType = {
+    [I in keyof API]: (params: API[I]["params"]) =>
+        | [response: null, error: null, isLoading: boolean, reload: () => void]
+        | [response: API[I]["result"], error: null, isLoading: boolean, reload: () => void]
+        | [response: null, error: Error, isLoading: boolean, reload: () => void];
+};
+
+
+if (process.env.NODE_ENV === "development") {
+    // In development mode, the frontend (Parcel) and backend (Express) run on different ports.
+    // We explicitly tell ssr-hook where the API backend is located.
+    setSSROrigin("http://localhost:1111");
+    setServerUrl("http://localhost:1111");
+}
 
 let authorization = "";
 
@@ -19,12 +34,20 @@ export function setAuthorizationHeader(newAuthorization: string) {
 
 export const api = getAPIFrontend<API>();
 export const useApi = getUseAPIFrontend<API>();
+export const useSSRApi = new Proxy({}, {
+    get(target, prop: string) {
+        return (params: any) => {
+            const url = api[prop as keyof typeof api].getUrl(params);
+            return useSSRHook(url);
+        };
+    }
+}) as UseSSRAPIType;
 
-export function handleError(error?: null | string | Error, errorInfo?: any) {
+export function handleError(error?: unknown, errorInfo?: any) {
     if (!error) return;
     if (typeof error === "string") error = new Error(error);
 
-    if (errorInfo && typeof errorInfo === "object" && typeof errorInfo.componentStack === "string") {
+    if (error instanceof Error && errorInfo && typeof errorInfo === "object" && typeof errorInfo.componentStack === "string") {
         error.stack = errorInfo.componentStack;
     }
 

package/template/src/services/common.ts

@@ -1,12 +1,21 @@
 import { useHeaders } from "ssr-hook";
 import { useTitle } from "easy-page-router/react";
 
-export function useHead(title: string, description: string) {
+type UseHeadProps = {
+    title: string;
+    description: string;
+    image?: string;
+    canonical?: string;
+    lang?: string;
+};
+
+export function useHead({ title, description, image, canonical, lang }: UseHeadProps) {
     useHeaders({
         title,
         description,
-        image: `/images/icon.png`, // Zde je možné zapojit dynamické generování jako v titimeme
-        canonical: typeof window !== "undefined" ? window.location.origin + window.location.pathname : "",
+        image: image || `/images/icon.png`, // Images must be placed in the public directory to be accessible
+        canonical: canonical || (typeof window !== "undefined" ? window.location.origin + window.location.pathname : ""),
+        lang,
     });
     useTitle(title);
 }

package/template/src/site.webmanifest

@@ -3,34 +3,45 @@
     "short_name": "__NAME__",
     "description": "Welcome to __NAME__ application.",
     "start_url": "/",
+    "display": "standalone",
+    "theme_color": "#6366f1",
+    "background_color": "#09090b",
     "icons": [
         {
             "src": "./images/icon.png?width=16&height=16",
             "sizes": "16x16",
-            "type": "image/png"
+            "type": "image/png",
+            "purpose": "maskable"
         },
         {
             "src": "./images/icon.png?width=32&height=32",
             "sizes": "32x32",
-            "type": "image/png"
+            "type": "image/png",
+            "purpose": "maskable"
+        },
+        {
+            "src": "./images/icon.png?width=180&height=180",
+            "sizes": "180x180",
+            "type": "image/png",
+            "purpose": "maskable"
         },
         {
             "src": "./images/icon.png?as=webp&width=192&height=192",
             "sizes": "192x192",
-            "type": "image/webp"
+            "type": "image/webp",
+            "purpose": "maskable"
         },
         {
             "src": "./images/icon.png?width=192&height=192",
             "sizes": "192x192",
-            "type": "image/png"
+            "type": "image/png",
+            "purpose": "maskable"
         },
         {
-            "src": "./images/icon.png?width=180&height=180",
-            "sizes": "180x180",
-            "type": "image/png"
+            "src": "./images/icon.png?as=webp&width=512&height=512",
+            "sizes": "512x512",
+            "type": "image/webp",
+            "purpose": "maskable"
         }
-    ],
-    "theme_color": "#2563eb",
-    "background_color": "#ffffff",
-    "display": "standalone"
-}
+    ]
+}

package/template/src/styles.scss

@@ -27,7 +27,7 @@ a {
     }
 }
 
-.container {
+main {
     max-width: 800px;
     margin: 50px auto;
     padding: 40px;
@@ -35,50 +35,38 @@ a {
     border-radius: 16px;
     box-shadow: 0 10px 40px rgba(0, 0, 0, 0.5);
     border: 1px solid $border;
+}
 
-    .hero {
-        text-align: center;
-        margin-bottom: 40px;
+header {
+    text-align: center;
+    margin-bottom: 40px;
 
-        h1 {
-            margin: 0 0 10px;
-            color: $text;
-            font-size: 2.5rem;
-            background: linear-gradient(90deg, #818cf8, #c084fc);
-            -webkit-background-clip: text;
-            -webkit-text-fill-color: transparent;
-        }
-        
-        p {
-            color: $text-muted;
-            font-size: 1.1rem;
-        }
+    h1 {
+        color: $primary;
+    }
 
-        .app-icon {
-            width: 140px;
-            height: 140px;
-            margin: 0 auto 20px;
-            background-image: url("./images/icon.png?as=webp");
-            background-size: contain;
-            background-repeat: no-repeat;
-            background-position: center;
-        }
+    p {
+        color: $text-muted;
+    }
+
+    figure {
+        width: 140px;
+        height: 140px;
+        margin: 0 auto 20px;
+        background-image: url("./images/icon.png?as=webp");
+        background-size: contain;
+        background-repeat: no-repeat;
+        background-position: center;
     }
 }
 
-.api-test {
+section {
     margin-top: 40px;
     padding: 30px;
     background: rgba(255, 255, 255, 0.02);
     border-radius: 12px;
     border: 1px solid $border;
 
-    h2,
-    h3 {
-        margin-top: 0;
-        color: #fff;
-    }
-
     ul {
         list-style: none;
         padding: 0;
@@ -98,20 +86,23 @@ a {
                 transform: translateY(-2px);
                 border-color: $primary;
             }
+
+            nav {
+                display: flex;
+                gap: 8px;
+            }
         }
     }
 
-    .item-details {
-        padding: 20px;
+    article {
+        padding: 0px 20px 10px;
         background: $bg;
-        margin-top: 20px;
         border-radius: 8px;
         border: 1px solid $primary;
         box-shadow: 0 0 15px rgba(99, 102, 241, 0.15);
 
         h3 {
             color: $primary;
-            margin-bottom: 10px;
         }
 
         p {
@@ -123,7 +114,6 @@ a {
     form {
         display: flex;
         gap: 12px;
-        margin-top: 20px;
         flex-wrap: wrap;
     }
 }
@@ -160,23 +150,16 @@ button {
         transform: scale(1.02);
     }
 
-    &:active:not(:disabled) {
-        transform: scale(0.98);
-    }
-
-    &:disabled {
-        opacity: 0.5;
-        cursor: not-allowed;
-    }
-    
     &.btn-danger {
         background: #ef4444;
+
         &:hover:not(:disabled) {
             background: #dc2626;
         }
     }
 }
 
+// --- ADMIN START ---
 // --- ADMIN DASHBOARD ---
 .admin-login {
     padding: 40px;
@@ -184,12 +167,14 @@ button {
     margin: 0 auto;
     text-align: center;
 
-    h2 { color: $text; }
-    
+    h2 {
+        color: $text;
+    }
+
     .back-link {
         margin-bottom: 20px;
     }
-    
+
     form {
         display: flex;
         flex-direction: column;
@@ -197,7 +182,6 @@ button {
         margin-top: 20px;
     }
 
-    input { width: 100%; box-sizing: border-box; }
 }
 
 .admin-container {
@@ -211,8 +195,16 @@ button {
         align-items: center;
         margin-bottom: 30px;
 
-        h2 { margin: 0; color: $text; }
-        a { color: $primary; text-decoration: none; font-weight: bold; }
+        h2 {
+            margin: 0;
+            color: $text;
+        }
+
+        a {
+            color: $primary;
+            text-decoration: none;
+            font-weight: bold;
+        }
     }
 
     .controls {
@@ -222,12 +214,18 @@ button {
         margin-bottom: 30px;
         flex-wrap: wrap;
 
-        strong { font-size: 1.1rem; color: $text; }
+        strong {
+            font-size: 1.1rem;
+            color: $text;
+        }
 
         .btn-logout {
             margin-left: auto;
             background: #ef4444;
-            &:hover { background: #dc2626; }
+
+            &:hover {
+                background: #dc2626;
+            }
         }
     }
 
@@ -258,16 +256,26 @@ button {
                 justify-content: flex-end;
                 height: 100%;
 
-                .count { font-size: 11px; color: $text; margin-bottom: 4px; font-weight: bold; }
-                .date { font-size: 10px; margin-top: 8px; color: $text-muted; }
-                
+                .count {
+                    font-size: 11px;
+                    color: $text;
+                    margin-bottom: 4px;
+                    font-weight: bold;
+                }
+
+                .date {
+                    font-size: 10px;
+                    margin-top: 8px;
+                    color: $text-muted;
+                }
+
                 .bar {
                     width: 100%;
                     max-width: 24px;
                     border-radius: 4px 4px 0 0;
                     transition: height 0.3s ease;
                 }
-                
+
                 .bar.active {
                     background: $primary;
                 }
@@ -280,4 +288,5 @@ button {
         grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
         gap: 20px;
     }
-}
+}
+// --- ADMIN END ---

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;
 };