easy-starter 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Filip Paulů
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# easy-starter 🚀
+
+A lightweight CLI tool to bootstrap modern fullstack React web projects.
+
+```bash
+npx easy-starter [your-project-name]
+```
+
+**Keywords:** React, Server-Side Rendering (SSR), Database (DB), Analytics, Type-Safe API, 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. 
+
+**easy-starter solves this by giving you back control.**
+
+* **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:
+
+* **Frontend/Backend:** React 19, TypeScript, and Express.
+* **Bundler:** Parcel - zero-configuration, lightning-fast builds.
+* **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.
+* **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.
+* **Deployment:** Integrated Github Actions workflow and PM2 deployment script for seamless, automated deployment straight to your own VPS.
+
+## Getting Started
+
+Bootstrapping a new project is as simple as running one command:
+
+```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:
+
+```bash
+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`!
+
+## 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 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.
+
+## License
+
+MIT

package/bin/index.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const { execSync } = require('child_process');
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout
+});
+
+const askQuestion = (query) => new Promise(resolve => rl.question(query, resolve));
+
+async function main() {
+  console.log('🚀 Welcome to easy-starter!');
+
+  let projectName = process.argv[2];
+  if (!projectName) {
+    projectName = await askQuestion('Enter the project name (e.g., my-awesome-app): ');
+  }
+
+  if (!projectName) {
+    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🚢 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';
+
+  rl.close();
+
+  const targetPath = path.join(process.cwd(), projectName);
+
+  if (fs.existsSync(targetPath)) {
+    console.error(`Folder ${projectName} already exists!`);
+    process.exit(1);
+  }
+
+  console.log(`\n📁 Creating project in folder ${targetPath}...`);
+  fs.mkdirSync(targetPath, { recursive: true });
+
+  const templatePath = path.join(__dirname, '..', 'template');
+
+  function copyFolderSync(from, to, ignoreFiles = []) {
+    fs.mkdirSync(to, { recursive: true });
+    fs.readdirSync(from).forEach(element => {
+      if (ignoreFiles.includes(element)) return;
+      const stat = fs.lstatSync(path.join(from, element));
+      if (stat.isFile()) {
+        fs.copyFileSync(path.join(from, element), path.join(to, element));
+      } else if (stat.isSymbolicLink()) {
+        fs.symlinkSync(fs.readlinkSync(path.join(from, element)), path.join(to, element));
+      } else if (stat.isDirectory()) {
+        copyFolderSync(path.join(from, element), path.join(to, element), ignoreFiles);
+      }
+    });
+  }
+
+  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'));
+  }
+
+  // Update site.webmanifest
+  const manifestPath = path.join(targetPath, 'src', '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 });
+    }
+
+    // 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);
+      }
+    };
+
+    stripAdminBlocks(path.join(targetPath, 'src', 'Router.tsx'));
+    stripAdminBlocks(path.join(targetPath, 'server', 'index.tsx'));
+  }
+
+  // Update package.json from template
+  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 || {};
+      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;
+    }
+
+    fs.writeFileSync(packageJsonPath, JSON.stringify(pkg, null, 2));
+  }
+
+  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.log(`\n🎉 Project ${projectName} has been successfully created!`);
+  console.log('\nGetting started:');
+  console.log(`  cd ${projectName}`);
+  console.log('  npm run dev -> http://localhost:1234');
+  if (includeDeploy) {
+    console.log('  npm run deploy');
+  }
+}
+
+main().catch(err => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,29 @@
+{
+    "name": "easy-starter",
+    "version": "1.0.0",
+    "description": "A lightweight CLI tool to bootstrap modern fullstack React web projects.",
+    "bin": {
+        "easy-starter": "./bin/index.js"
+    },
+    "keywords": [
+        "cli",
+        "bootstrap",
+        "starter",
+        "react",
+        "easy",
+        "ssr",
+        "typescript",
+        "fullstack",
+        "easy-db",
+        "parcel"
+    ],
+    "author": "Filip Paulů <ing.fenix@seznam.cz>",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/ingSlonik/easy-starter.git"
+    },
+    "bugs": {
+        "url": "https://github.com/ingSlonik/easy-starter/issues"
+    }
+}

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

@@ -0,0 +1,29 @@
+name: Deploy to VPS
+
+on:
+  push:
+    branches:
+      - master
+      - main
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 24
+
+      - name: Install Dependencies
+        run: npm install tsx node-ssh
+
+      - name: Run Deploy Script
+        env:
+          SSH_HOST: ${{ secrets.SSH_HOST }}
+          SSH_USERNAME: ${{ secrets.SSH_USERNAME }}
+          SSH_PASSWORD: ${{ secrets.SSH_PASSWORD }}
+        run: npm run deploy

package/template/.parcelrc

@@ -0,0 +1,6 @@
+{
+    "extends": "@parcel/config-default",
+    "optimizers": {
+        "*.html": []
+    }
+}

package/template/README.md

@@ -0,0 +1,40 @@
+# Welcome to your new project! 🚀
+
+This project was bootstrapped with `easy-starter`, giving you maximum freedom with a minimalist, yet powerful setup.
+
+## Features Included
+
+* **React 19 & TypeScript**: For a robust frontend experience.
+* **Express Backend**: A simple Node.js server.
+* **Parcel Bundler**: Lightning-fast builds with zero configuration.
+* **SSR Ready**: Powered by [`ssr-hook`](https://www.npmjs.com/package/ssr-hook).
+* **Type-Safe API**: Connected via [`typed-client-server-api`](https://www.npmjs.com/package/typed-client-server-api).
+* **Local Database**: Ready to use with [`easy-db-node`](https://www.npmjs.com/package/easy-db-node).
+* **Routing**: Managed by [`easy-page-router`](https://www.npmjs.com/package/easy-page-router).
+
+## Getting Started
+
+To start developing, run:
+
+```bash
+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.
+
+## Scripts
+
+* `npm run dev` - Starts the development server.
+* `npm run build` - Builds the application for production.
+* `npm start` - Starts the production server (run build first).
+* `npm run deploy` - (If included) Deploys your app to a remote server via SSH.
+
+## Project Structure
+
+* `/src` - Your React frontend code.
+* `/server` - Your Express backend code.
+* `/types.d.ts` - Shared TypeScript definitions for your API and Database.
+* `/public` - Static assets (images, fonts, etc.).
+* `/easy-db` - Where your local database JSON files are stored.
+
+Enjoy building with freedom!

package/template/env

@@ -0,0 +1,7 @@
+NODE_ENV=development
+SERVER_PORT=1111
+ADMIN_PASSWORD=admin
+
+SSH_HOST=***
+SSH_USERNAME=root
+SSH_USERNAME=***

package/template/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "template",
+  "version": "1.0.0",
+  "description": "",
+  "scripts": {
+    "start": "tsx --env-file=.env server/index.tsx",
+    "dev": "concurrently --kill-others \"npm run server:dev\" \"npm run fe:dev\"",
+    "server:dev": "tsx --env-file=.env --watch server/index.tsx",
+    "fe:dev": "parcel src/index.html --no-cache",
+    "build": "parcel build src/index.html",
+    "deploy": "tsx scripts/deploy.ts"
+  },
+  "dependencies": {
+    "cors": "^2.8.6",
+    "easy-analytics": "^1.0.1",
+    "easy-db-node": "^3.0.1",
+    "easy-page-router": "^0.2.1",
+    "express": "^5.2.1",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "ssr-hook": "^0.2.0",
+    "typed-client-server-api": "^1.0.3"
+  },
+  "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",
+    "@types/react": "^19.2.14",
+    "@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

@@ -0,0 +1,148 @@
+import { NodeSSH, SSHExecCommandResponse } from 'node-ssh';
+
+import { lstat, readdir } from 'fs/promises';
+import { relative, resolve } from 'path';
+
+// Fill in your credentials here, or load them from .env or process.env (e.g. GitHub Secrets).
+const host = process.env.SSH_HOST;
+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 path = resolve(process.cwd()); // Local project path
+const ignoreFiles = [
+    ".git",
+    "node_modules",
+    "scripts",
+    ".github"
+];
+
+// Ensure credentials 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.");
+
+deploy();
+
+// --------------------------------- functions ---------------------------------
+async function deploy() {
+    const ssh = new NodeSSH();
+
+    console.log(`Connecting to ${host}...`);
+    await ssh.connect({ host, username, password });
+    console.log(`✔ Connected to SSH server.\n`);
+
+    const files = (await getFiles(path)).map(file => {
+        const relativePath = relative(path, file);
+        const pathTo = resolve(sshPath, relativePath);
+        return { file, pathTo, relativePath };
+    });
+    console.log(`✔ Found ${files.length} files to copy from ${path} to ${sshPath}.`);
+
+    if (files.length < 50) {
+        // Copy file by file
+        for (const [i, { file, pathTo, relativePath }] of Object.entries(files)) {
+            console.log(`    ${parseInt(i) + 1} / ${files.length} Copying ${relativePath}`);
+            await ssh.putFile(file, pathTo);
+        }
+    } else {
+        // Copy all files at once
+        files.forEach((file) => console.log(`        ${file.relativePath}`));
+        console.log(`    Copying ${files.length} files at once...`)
+        await ssh.putFiles(files.map(f => ({ local: f.file, remote: f.pathTo })));
+    }
+    console.log(`✔ All files are copied.\n`);
+
+    console.log(`Installing dependencies...`);
+    await sshExec(ssh, "npm install", "Failed to install dependencies.");
+    console.log(`✔ Dependencies are installed.\n`);
+
+    const timeServerOff = new Date().getTime();
+
+    console.log(`Removing old build...`);
+    await sshExec(ssh, "rm -rf .parcel-cache", "Failed to remove .parcel-cache folder.");
+    await sshExec(ssh, "rm -rf dist", "Failed to remove dist folder.");
+    console.log(`✔ Old build removed.\n`);
+
+    console.log(`Building project...`);
+    await sshExec(ssh, "npm run build", "Failed to build project.");
+    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!`);
+    }
+    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`);
+
+    console.log(`i Server was ${(new Date().getTime() - timeServerOff) / 1000}s off!\n`);
+
+    console.log(`------------------------\n✔ Successfully deployed.`);
+}
+
+async function serverCheck(server: string, tries = 3, delay = 1000) {
+    console.log(`Checking ${server} ...`);
+    const res = await fetch(server).catch(() => ({ status: 500 }));
+
+    if (res.status === 200) {
+        console.log(`i Response status: ${res.status}`);
+        return true;
+    }
+
+    console.log(`✘ Response status: ${res.status}.`);
+
+    if (tries < 1) return false;
+
+    console.log(`i I'm giving it ${tries} more tries to recover, the next try will be in ${delay / 1000} second...`);
+    await timeout(delay);
+    return await serverCheck(server, tries - 1, delay);
+}
+
+async function sshExec(ssh: NodeSSH, command: string, error?: string): Promise<SSHExecCommandResponse> {
+    console.log(`$ ${command}`);
+    const response = await ssh.execCommand(command, { cwd: sshPath });
+    if (response.code !== 0) {
+        console.log(`Code: ${response.code}\n${response.stderr.split("\n").join("\n    | ")}`);
+        throw new Error(error);
+    }
+
+    console.log(response.stdout.split("\n").join("\n    | "));
+    return response;
+}
+
+async function getFiles(path: string) {
+    const paths: string[] = [];
+    const files = await readdir(path);
+
+    for (const file of files) {
+        if (ignoreFiles.find(f => file.includes(f)))
+            continue;
+
+        const filePath = resolve(path, file);
+        const stat = await lstat(filePath);
+
+        if (stat.isDirectory()) {
+            paths.push(...await getFiles(filePath));
+        } else {
+            paths.push(filePath)
+        }
+    }
+    return paths;
+}
+
+async function timeout(ms: number) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}