easy-starter

easy-starter

A lightweight CLI tool to bootstrap modern fullstack React web projects with Vite v8, TypeScript 7.0, and optional authentication.

npx easy-starter [your-project-name]

Keywords: React, Server-Side Rendering (SSR), Vite, Database (DB), Analytics, Type-Safe API, User Authentication, Fullstack, Minimalist

Tired of rigid frameworks forcing you into complex folder structures and steep learning curves? easy-starter is built on the philosophy of maximum freedom and modularity. It provides a solid foundation by combining a set of carefully curated, simple, and powerful tools without locking you into a monolithic architecture like Next.js or Remix.

---

What's New in v2.0.0?

• Vite v8 Bundler: Switched from Parcel to Vite v8, offering lightning-fast HMR and seamless dev proxying.
• TypeScript 7.0: Fully upgraded dependencies and compiler options to support TypeScript 7.
• Interactive Installer: Run npx easy-starter and configure exactly what you need. Zero bloat — files, comments, and package dependencies are completely omitted if a feature is disabled.
• User Authentication: Out-of-the-box integration with easy-user-auth including secure cookie rotation, user registration/login modals, role checking, and custom password recovery emails.
• Dynamic Social Previews: Generate dynamic og:image screenshots of your pages automatically using headless browser rendering (puppeteer) and cached locally in easy-db-node.
• Flexible Viewport Tuning: Optional script injection to scale mobile layouts to a standard viewport width (min-width: 600px).

---

What's included in the box?

The generated boilerplate can be configured to contain:

• Frontend/Backend: React 19, TypeScript 7.0, and Express.
• Bundler: Vite v8 - lightning-fast client bundles with native dev proxying.
• User Authentication: easy-user-auth - Highly secure password-recovery, registration, and cookie rotation framework.
• Server-Side Rendering (SSR): 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 - An RPC-like interface giving you full TypeScript autocomplete and safety between your Express server and React client.
• Database: 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 - A lightweight, programmatic routing solution.
• Analytics: 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.

---

Interactive Configuration Prompts

When you run npx easy-starter, the CLI will prompt you with the following configuration questions:

1. Project name: Choose the name of the folder and the app.
2. User Authentication: Do you want to add user login/registration widgets? (Installs easy-user-auth and nodemailer, generates JWT secrets in .env).
3. Viewport Width Fix: Do you want to fix iOS mobile viewport issues by ensuring a minimum width of 600px? (Adds JS viewport resizing listener and sets CSS min-width).
4. Admin Dashboard: Do you want to include /admin page? (If Auth is enabled, protects it using user roles. If Auth is disabled, protects it using a static password).
5. Analytics: Do you want local visitor analytics? (Installs easy-analytics, adds dashboard visualization).
6. SSR Rendering: Do you want Server-Side Rendering? (Installs ssr-hook, configures hydration).
7. og:image Generation: Do you want dynamic og:image generation? (Installs puppeteer to automatically screenshot URLs for social cards, cached via easy-db).
8. Deployment Script: Do you want to deploy to your VPS using GitHub Actions? (Installs node-ssh, adds SSH deploy script).

---

Getting Started

Bootstrapping a new project is as simple as running:

npx easy-starter [your-project-name]

Running your project

Once created, navigate to your new project folder and start the development server:

cd your-project-name
npm run dev

This command starts both the Express backend on port 1111 and the Vite dev server on port 5173. Your app will be live at http://localhost:5173!

---

Available Scripts

Inside your newly generated project, you can use the following scripts:

• npm run dev: Starts the development server with hot-reloading. Open http://localhost:5173.
• npm run build: Builds the project for production.
• npm start: Starts the production server (make sure to build first).
• npm run deploy: (Optional) Executes the scripts/deploy.ts script to deploy your built project via SSH and PM2.

License

MIT