easy-starter 🚀

A lightweight CLI tool to bootstrap modern fullstack React web projects.

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 - 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.

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.

// 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:

// 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.

// 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:

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:

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