easy-starter 1.0.0

package/template/server/index.tsx

@@ -0,0 +1,171 @@
+import { resolve } from "path";
+import { readFile } from "fs/promises";
+import express from "express";
+import cors from "cors";
+
+// 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";
+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.
+const ORIGIN = process.env.NODE_ENV === "development"
+    ? LOCALHOST
+    : "https://your-production-url.com"; // TODO: Update to your domain
+
+const INDEX_HTML_PATH = resolve(__dirname, "..", "dist", "index.html");
+
+// The directory where easy-db-node will store its data files.
+const FILE_URL = process.env.NODE_ENV === "development"
+    ? LOCALHOST + "/files"
+    : "/files";
+
+// Initialize the database with our schema. We can destructure common operations.
+const { insert, select, selectArray, update, remove } = easyDBNode<Database>({ fileUrl: FILE_URL });
+
+const app = express();
+
+if (process.env.NODE_ENV === "development") {
+    console.log("Starting development server...");
+    app.use(cors());
+}
+
+// ---------------------------- 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);
+    } catch (e) {
+        console.error("SSR error:", e);
+        res.status(500);
+        res.json({ message: "Internal server error" });
+    }
+});
+
+// Serve static files generated by the bundler (JS, CSS)
+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)
+app.use("/files", express.static("easy-db-files"));
+
+// --------------------------------- SEO ---------------------------------------
+// Basic configuration for search engine crawlers.
+app.get("/robots.txt", (_, res) => {
+    res.type("text/plain");
+    res.send(`User-agent: *\nAllow: /\n\nSitemap: ${ORIGIN}/sitemap.xml`);
+});
+
+// Sitemap helps search engines index your site. You should dynamically generate this
+// based on your application's routes and database content.
+app.get("/sitemap.xml", async (_, res) => {
+    // TODO: add all pages
+    const sitemap = [{
+        url: ORIGIN + "/",
+        lastModified: "2024-01-01",
+        changeFrequency: "weekly",
+        priority: 1,
+    }];
+
+    res.set("Content-Type", "text/xml");
+    res.send(`<?xml version="1.0" encoding="UTF-8" ?>
+<urlset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.sitemaps.org/schemas/sitemap/0.9 http://www.sitemaps.org/schemas/sitemap/0.9/sitemap.xsd" xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">${sitemap.map(s => `<url>
+        <loc>${s.url}</loc>
+        <lastmod>${s.lastModified}</lastmod>
+        ${s.changeFrequency ? `<changefreq>${s.changeFrequency}</changefreq>` : ""}
+        <priority>${s.priority}</priority>
+    </url>`).join("\n")}</urlset>`);
+});
+
+// --------------------------- Easy analytics ----------------------------------
+// This parses incoming JSON payloads for the API and analytics.
+app.use(express.json({ limit: "1MB" }));
+
+// Endpoint to receive analytics data from the client.
+app.post("/api/easy-analytics", async (req, res) => {
+    const userAgent = req.headers['user-agent'] || "";
+    const ip = req.headers['x-forwarded-for'] || req.socket.remoteAddress || "";
+
+    try {
+        const response = await postEasyAnalytics(req.body, userAgent, ip as string);
+        res.status(200).json(response);
+    } catch (e: any) {
+        console.error("Analytics error:", e);
+        res.status(400).json({ message: e.message || "Bad request" });
+    }
+});
+
+// --- 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.
+setAPIBackend<API>(app, {
+    async getItems() {
+        return await selectArray("item");
+    },
+    async getItem({ id }) {
+        const item = await select("item", id);
+        if (!item) throw new Error("Item not found");
+        return item; // easy-db-node select returns the object
+    },
+    async addItem({ name, value }) {
+        const id = await insert("item", { name, value });
+        return id;
+    },
+    async removeItem({ id }) {
+        await remove("item", id);
+        return true;
+    },
+    // --- ADMIN START ---
+    async getEasyAnalyticsData({ password, month }) {
+        const validPassword = process.env.ADMIN_PASSWORD;
+        if (!validPassword || password !== validPassword) {
+            throw new Error("Invalid password or server error");
+        }
+        return await getEasyAnalytics(month);
+    }
+    // --- ADMIN END ---
+});
+
+// --------------------------------- SSR ---------------------------------------
+
+app.get(/.*/, async (req, res) => {
+    try {
+        const indexHtml = await readFile(INDEX_HTML_PATH, "utf-8");
+        const html = await renderToHTML(ORIGIN, req.url, indexHtml, <App />);
+        res.set("Content-Type", "text/html");
+        res.send(html);
+    } catch (e) {
+        console.error("SSR error:", e);
+        res.status(500);
+        res.json({ message: "Internal server error" });
+    }
+});
+
+// Start listening for incoming requests.
+app.listen(PORT, () => {
+    console.log(`Server is running on ${LOCALHOST}`);
+});

package/template/src/App.tsx

@@ -0,0 +1,22 @@
+// 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 Router from "./Router";
+
+// Initialize analytics. It sends data to our Express 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>
+    );
+}

package/template/src/Router.tsx

@@ -0,0 +1,35 @@
+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 ---
+
+export default function AppRouter() {
+    return <Router
+        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>}>
+                    <Admin />
+                </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.html

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

package/template/src/index.tsx

@@ -0,0 +1,29 @@
+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";
+
+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 />);
+} else {
+    // In production, the HTML is pre-rendered by the Express server.
+    // hydrateRoot attaches React event listeners to the existing HTML without recreating it,
+    // making the initial load much faster and seamless.
+    hydrateRoot(rootElement, <App />, {
+        onCaughtError: handleError,
+        onUncaughtError: handleError,
+        onRecoverableError: handleError,
+    });
+}

package/template/src/pages/Index.tsx

@@ -0,0 +1,115 @@
+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 { useHead } from "../services/common";
+
+export default function Index() {
+    useHead("Welcome to easy-starter", "The ultimate foundation for your next project.");
+
+    const [items, error, loading, reload] = useSSRHook<API["getItems"]["result"]>("/api/items");
+
+    const [selectedItem, setSelectedItem] = useState<Item | null>(null);
+    const [selectedLoading, setSelectedLoading] = useState(false);
+
+    const [newItemName, setNewItemName] = useState("");
+    const [newItemValue, setNewItemValue] = useState("");
+    const [adding, setAdding] = useState(false);
+
+    async function handleView(id: string) {
+        setSelectedLoading(true);
+        const [item, err] = await api.getItem({ id });
+        setSelectedLoading(false);
+        if (item) setSelectedItem(item);
+        if (err) handleError(err);
+    }
+
+    async function handleAdd(e: React.FormEvent) {
+        e.preventDefault();
+        setAdding(true);
+        const [id, err] = await api.addItem({ name: newItemName, value: Number(newItemValue) });
+        setAdding(false);
+        if (id) {
+            setNewItemName("");
+            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>
+                <p>The ultimate foundation for your next project.</p>
+                <Link href="/admin">
+                    → Go to Admin Dashboard
+                </Link>
+            </div>
+
+            <div className="api-test">
+                <h2>Items (SSR Hook)</h2>
+                {loading && <p>Loading from server...</p>}
+                {error && <p>Error loading items: {error.message}</p>}
+                {items && (
+                    <ul>
+                        {items.map(item => (
+                            <li key={item._id}>
+                                <span><strong>{item.name}</strong> - {item.value}</span>
+                                <div>
+                                    <button onClick={() => handleView(item._id!)}>View Details</button>
+                                    <button className="btn-danger" onClick={() => handleRemove(item._id!)} style={{ marginLeft: 8 }}>Delete</button>
+                                </div>
+                            </li>
+                        ))}
+                    </ul>
+                )}
+                {items?.length === 0 && <p>No items found. Add one below!</p>}
+
+                {selectedLoading && <p>Loading item details...</p>}
+                {selectedItem && (
+                    <div className="item-details">
+                        <h3>Selected Item:</h3>
+                        <p>ID: {selectedItem._id}</p>
+                        <p>Name: {selectedItem.name}</p>
+                        <p>Value: {selectedItem.value}</p>
+                    </div>
+                )}
+
+                <h3 style={{ marginTop: 20 }}>Add New Item</h3>
+                <form onSubmit={handleAdd}>
+                    <input
+                        type="text"
+                        placeholder="Item name"
+                        value={newItemName}
+                        onChange={e => setNewItemName(e.target.value)}
+                        required
+                    />
+                    <input
+                        type="number"
+                        placeholder="Value"
+                        value={newItemValue}
+                        onChange={e => setNewItemValue(e.target.value)}
+                        required
+                    />
+                    <button type="submit" disabled={adding}>
+                        {adding ? "Adding..." : "Add"}
+                    </button>
+                </form>
+            </div>
+        </div>
+    );
+}

package/template/src/pages/NotFound.tsx

@@ -0,0 +1,14 @@
+import { useHead } from "../services/common";
+import { Link } from "easy-page-router/react";
+
+export default function NotFound() {
+    useHead("404 Not Found", "Page you are looking for does not exist.");
+
+    return (
+        <div style={{ padding: "40px", textAlign: "center", fontFamily: "sans-serif" }}>
+            <h1>404</h1>
+            <p>Oops, page not found.</p>
+            <Link href="/">Go back home</Link>
+        </div>
+    );
+}

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

@@ -0,0 +1,166 @@
+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.");
+
+    const [password, setPassword] = useState("");
+    const [loggedIn, setLoggedIn] = useState(false);
+    const [error, setError] = useState("");
+
+    const [month, setMonth] = useState(new Date().toISOString().slice(0, 7));
+    const [records, setRecords] = useState([]);
+    const [loading, setLoading] = useState(false);
+
+    useEffect(() => {
+        const savedPwd = localStorage.getItem("admin_pwd");
+        if (savedPwd) {
+            setPassword(savedPwd);
+            fetchData(savedPwd, month);
+        }
+    }, []);
+
+    const fetchData = async (pwd: string, m: string) => {
+        setLoading(true);
+        setError("");
+        try {
+            const [data, err] = await api.getEasyAnalyticsData({ password: pwd, month: m });
+
+            if (data) {
+                setRecords(data as any);
+                setLoggedIn(true);
+                localStorage.setItem("admin_pwd", pwd);
+            } else if (err) {
+                setError(err.message || "Invalid password or server error");
+                setLoggedIn(false);
+                localStorage.removeItem("admin_pwd");
+            }
+        } catch (e) {
+            setError(String(e));
+            handleError(e as Error);
+        }
+        setLoading(false);
+    };
+
+    const handleLogin = (e: React.FormEvent) => {
+        e.preventDefault();
+        fetchData(password, month);
+    };
+
+    const handleMonthChange = (move: number) => {
+        const newMonth = new Date(month);
+        newMonth.setMonth(newMonth.getMonth() + move);
+        const nextM = newMonth.toISOString().slice(0, 7);
+        setMonth(nextM);
+        if (loggedIn) fetchData(password, nextM);
+    };
+
+    const byURL = useGroup(records, (r: any) => {
+        try {
+            return new URL(r.url).pathname;
+        } catch (e) {
+            return r.url || "Unknown";
+        }
+    });
+
+    const byReferrer = useGroup(records, (r: any) => r.referrer || "Direct", (rs: any) => getGroupedCount(rs, (row: any) => row.localId));
+
+    const byWidth = useGroup(records, (r: any) => {
+        const w = r.window?.innerWidth || 0;
+        if (w >= 1920) return ">= 1920px Full HD";
+        if (w >= 1280) return "1280px - 1920px HD";
+        if (w >= 768) return "768px - 1280px Tablet";
+        if (w > 0) return "< 768px Mobile";
+        return "Unknown";
+    });
+
+    // Simplified UA parser
+    const byBrowserLike = useGroup(records, (r: any) => {
+        const ua = (r.userAgent || "").toLowerCase();
+        if (ua.includes("firefox")) return "Firefox";
+        if (ua.includes("edg")) return "Edge";
+        if (ua.includes("chrome")) return "Chrome";
+        if (ua.includes("safari")) return "Safari";
+        return "Other/Unknown";
+    }, (rs: any) => getGroupedCount(rs, (row: any) => row.localId));
+
+    if (!loggedIn) {
+        return (
+            <div className="admin-login">
+                <h2>Analytics Login</h2>
+                <div className="back-link">
+                    <Link href="/">Back to website</Link>
+                </div>
+                <form onSubmit={handleLogin}>
+                    <input
+                        type="password"
+                        placeholder="Enter admin password"
+                        value={password}
+                        onChange={e => setPassword(e.target.value)}
+                    />
+                    <button type="submit">Login</button>
+                    {error && <p style={{ color: "#ef4444", marginTop: "10px" }}>{error}</p>}
+                </form>
+            </div>
+        );
+    }
+
+    // Daily visits counter
+    const daysInMonth = new Date(parseInt(month.slice(0, 4)), parseInt(month.slice(5, 7)), 0).getDate();
+    const dailyStats = Array.from({ length: daysInMonth }, (_, i) => {
+        const d = i + 1;
+        const dateStr = `${month}-${d.toString().padStart(2, "0")}`;
+        const count = records.filter((r: any) => r.serverDate && r.serverDate.startsWith(dateStr)).length;
+        return { date: d, count };
+    });
+    const maxVisits = Math.max(...dailyStats.map(s => s.count), 1);
+
+    return (
+        <div className="admin-container">
+            <div className="header">
+                <h2>Analytics ({records.length} events)</h2>
+                <Link href="/">Back to website</Link>
+            </div>
+
+            <div className="controls">
+                <button onClick={() => handleMonthChange(-1)}>{"< Month"}</button>
+                <strong>{month}</strong>
+                <button onClick={() => handleMonthChange(1)}>{"Month >"}</button>
+                <button onClick={() => fetchData(password, month)} disabled={loading}>
+                    {loading ? "Loading..." : "Refresh"}
+                </button>
+                <button className="btn-logout" onClick={() => {
+                    setLoggedIn(false);
+                    setPassword("");
+                    localStorage.removeItem("admin_pwd");
+                }}>Logout</button>
+            </div>
+
+            <div className="chart-container">
+                <h3>Pageviews per day</h3>
+                <div className="chart">
+                    {dailyStats.map(({ date, count }) => (
+                        <div key={date} className="bar-wrapper">
+                            <span className="count">{count > 0 ? count : ""}</span>
+                            <div className={`bar ${count > 0 ? 'active' : ''}`} style={{
+                                height: `${(count / maxVisits) * 100}%`,
+                                minHeight: count > 0 ? "4px" : "0",
+                            }}></div>
+                            <span className="date">{date}.</span>
+                        </div>
+                    ))}
+                </div>
+            </div>
+
+            <div className="grid">
+                <GroupTable title="Pageviews" data={byURL} mainColor="#6366f1" />
+                <GroupTable title="Traffic Sources (Unique)" data={byReferrer} mainColor="#34d399" />
+                <GroupTable title="Screen Resolution" data={byWidth} mainColor="#fbbf24" />
+                <GroupTable title="Browser (Unique)" data={byBrowserLike} mainColor="#c084fc" />
+            </div>
+        </div>
+    );
+}

package/template/src/services/api.ts

@@ -0,0 +1,39 @@
+import { useEffect } from "react";
+import { sendError } from "easy-analytics/client";
+import { setServerUrl, getUseAPIFrontend, getAPIFrontend, setHeaders } from "typed-client-server-api/hooks";
+
+import { API } from "../../types";
+
+setServerUrl(process.env.NODE_ENV === "development" ? "http://localhost:1111" : "");
+
+let authorization = "";
+
+setHeaders(() => ({
+    "Content-Type": "application/json",
+    "Authorization": authorization,
+}));
+
+export function setAuthorizationHeader(newAuthorization: string) {
+    authorization = newAuthorization;
+}
+
+export const api = getAPIFrontend<API>();
+export const useApi = getUseAPIFrontend<API>();
+
+export function handleError(error?: null | string | Error, errorInfo?: any) {
+    if (!error) return;
+    if (typeof error === "string") error = new Error(error);
+
+    if (errorInfo && typeof errorInfo === "object" && typeof errorInfo.componentStack === "string") {
+        error.stack = errorInfo.componentStack;
+    }
+
+    console.error(error);
+    sendError(error);
+}
+
+export function useHandleError(error?: null | string | Error) {
+    useEffect(() => {
+        handleError(error);
+    }, [error]);
+}

package/template/src/services/common.ts

@@ -0,0 +1,12 @@
+import { useHeaders } from "ssr-hook";
+import { useTitle } from "easy-page-router/react";
+
+export function useHead(title: string, description: string) {
+    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 : "",
+    });
+    useTitle(title);
+}

package/template/src/site.webmanifest

@@ -0,0 +1,36 @@
+{
+    "name": "__NAME__",
+    "short_name": "__NAME__",
+    "description": "Welcome to __NAME__ application.",
+    "start_url": "/",
+    "icons": [
+        {
+            "src": "./images/icon.png?width=16&height=16",
+            "sizes": "16x16",
+            "type": "image/png"
+        },
+        {
+            "src": "./images/icon.png?width=32&height=32",
+            "sizes": "32x32",
+            "type": "image/png"
+        },
+        {
+            "src": "./images/icon.png?as=webp&width=192&height=192",
+            "sizes": "192x192",
+            "type": "image/webp"
+        },
+        {
+            "src": "./images/icon.png?width=192&height=192",
+            "sizes": "192x192",
+            "type": "image/png"
+        },
+        {
+            "src": "./images/icon.png?width=180&height=180",
+            "sizes": "180x180",
+            "type": "image/png"
+        }
+    ],
+    "theme_color": "#2563eb",
+    "background_color": "#ffffff",
+    "display": "standalone"
+}