stoix 0.1.0

package/README.md

@@ -0,0 +1,147 @@
+# Stoix
+
+Stoix is a TypeScript-first framework starter that scaffolds a Node + Express + React app with Vite.
+
+## Quick Start
+
+```bash
+npx stoix create my-app
+cd my-app
+npm run dev
+```
+
+App URL: `http://localhost:3000`
+
+## CLI
+
+### Create a project
+
+```bash
+npx stoix create <project-name>
+```
+
+### Help and version
+
+```bash
+npx stoix --help
+npx stoix --version
+```
+
+Project names must start with a letter and may contain letters, numbers, `.`, `_`, and `-`.
+
+## What Stoix Generates
+
+- Express server with auto-loaded API route modules
+- React 18 client with Vite HMR in development
+- Shared TypeScript setup across server, client, and config
+- Production build pipeline for client and server output
+
+## Generated Project Structure
+
+```text
+my-app/
+├── package.json                  # Dependencies and scripts
+├── stoix.config.ts               # Stoix framework configuration
+├── tsconfig.json                 # TypeScript config (shared)
+├── tsconfig.server.json          # TypeScript config (server)
+├── vite.config.ts                # Vite build configuration
+├── vite-env.d.ts                 # Vite environment types
+├── index.html                    # HTML entry point
+├── .env                          # Environment variables
+├── server/                       # Express server
+│   ├── server.ts                 # Server entry point
+│   └── routes/                   # Auto-loaded API routes
+│       └── example.ts            # Example API route
+├── src/                          # React client source
+│   ├── App.tsx                   # Root React component
+│   ├── main.tsx                  # Client entry point
+│   └── styles.css                # Global styles
+├── pages/                        # SSR pages (if enabled)
+│   └── index.tsx                 # Home page
+└── public/                       # Static assets
+    └── favicon.svg               # Favicon
+```
+
+## Generated Scripts
+
+| Script | Description |
+| --- | --- |
+| `npm run dev` | Runs the Express server with Vite middleware in development (`tsx server/server.ts`). |
+| `npm run build` | Runs TS checks, builds client assets with Vite, then compiles server output. |
+| `npm start` | Starts the production server from compiled files. |
+| `npm run typecheck` | Runs TypeScript checks without emit. |
+
+## Configuration
+
+Edit `stoix.config.ts`:
+
+```ts
+export interface StoixConfig {
+  port: number;
+  framework: 'react';
+  server: {
+    apiPrefix: string;
+    cors: string | string[] | false;
+  };
+}
+```
+
+Default values:
+
+- `port`: `3000`
+- `server.apiPrefix`: `"/api"`
+- `server.cors`: `false`
+
+## API Routes
+
+Any file in `server/routes/` that default-exports an Express router is auto-mounted at:
+
+`<apiPrefix>/<path-to-file>`
+
+Examples:
+
+- `server/routes/users.ts` -> `/api/users`
+- `server/routes/auth/me.ts` -> `/api/auth/me`
+- `server/routes/user/profile.ts` -> `/api/user/profile`
+- `server/routes/try/get.ts` -> `/api/try/get`
+- `server/routes/auth/index.ts` -> `/api/auth`
+
+## Environment Variables
+
+`template/.env` includes:
+
+```env
+PORT=3000
+NODE_ENV=development
+```
+
+`PORT` overrides the port in `stoix.config.ts`.
+
+## Development and Production Flow
+
+- Development: Express runs first, then mounts Vite as middleware for client HMR.
+- Production: Express serves static files from `dist/client` and handles SPA fallback to `index.html`.
+
+## Framework Development (this repo)
+
+From this repository:
+
+```bash
+npm run build
+```
+
+`prepack` runs:
+
+```bash
+npm run clean && npm run build
+```
+
+This removes template build artifacts (`template/node_modules`, `template/dist`, `template/.vite`) before packaging.
+
+## Current Limitations
+
+- Route modules are expected to `export default` an Express router.
+
+## License
+
+MIT

package/dist/bin/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/index.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+import { execSync } from 'node:child_process';
+import fs from 'fs-extra';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import chalk from 'chalk';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const STOIX_VERSION = fs.readJsonSync(path.resolve(__dirname, '..', '..', 'package.json')).version || '0.1.0';
+const args = process.argv.slice(2);
+const command = args[0];
+const projectName = args[1];
+function printBanner() {
+    console.log(chalk.cyan(`
+  ===================================
+           Stoix v${STOIX_VERSION}
+      Node + Express + React + Vite
+  ===================================
+`));
+}
+function printUsage() {
+    printBanner();
+    console.log(`${chalk.bold('Usage:')}
+  npx stoix create <project-name>
+
+${chalk.bold('Commands:')}
+  create <name>    Scaffold a new Stoix project
+
+${chalk.bold('Examples:')}
+  npx stoix create my-app
+  npx stoix create blog-api
+`);
+}
+function validateProjectName(name) {
+    const validPattern = /^[a-zA-Z][a-zA-Z0-9._-]*$/;
+    return validPattern.test(name);
+}
+async function createProject(name) {
+    const targetDir = path.resolve(process.cwd(), name);
+    if (fs.existsSync(targetDir)) {
+        console.error(chalk.red(`\n  Error: Directory "${name}" already exists.\n`));
+        process.exit(1);
+    }
+    printBanner();
+    console.log(chalk.cyan(`  Creating Stoix project: ${chalk.bold(name)}\n`));
+    // Resolve template directory (relative to compiled dist/bin/index.js -> ../../template)
+    const templateDir = path.resolve(__dirname, '..', '..', 'template');
+    if (!fs.existsSync(templateDir)) {
+        console.error(chalk.red('  Error: Template directory not found.'));
+        console.error(chalk.dim(`  Expected at: ${templateDir}`));
+        process.exit(1);
+    }
+    fs.copySync(templateDir, targetDir, { overwrite: false });
+    console.log(chalk.green('  + Project files created'));
+    const gitignoreSrc = path.join(targetDir, 'gitignore');
+    const gitignoreDest = path.join(targetDir, '.gitignore');
+    if (fs.existsSync(gitignoreSrc)) {
+        fs.renameSync(gitignoreSrc, gitignoreDest);
+    }
+    const pkgPath = path.join(targetDir, 'package.json');
+    const pkg = fs.readJsonSync(pkgPath);
+    pkg.name = name;
+    fs.writeJsonSync(pkgPath, pkg, { spaces: 2 });
+    console.log(chalk.green('  + package.json configured'));
+    console.log(chalk.cyan('\n  Installing dependencies...\n'));
+    let dependenciesInstalled = true;
+    try {
+        execSync('npm install', {
+            cwd: targetDir,
+            stdio: 'inherit',
+        });
+    }
+    catch {
+        dependenciesInstalled = false;
+        console.error(chalk.yellow('\n  Warning: npm install failed. Run it manually.'));
+    }
+    const statusLine = dependenciesInstalled
+        ? chalk.green.bold('  + Stoix project is ready!')
+        : chalk.yellow.bold('  ! Stoix project files are ready (dependencies not installed)');
+    const installStep = dependenciesInstalled ? '' : `    ${chalk.cyan('npm install')}\n`;
+    console.log(`
+${statusLine}
+
+${chalk.bold('  Next steps:')}
+    ${chalk.cyan(`cd ${name}`)}
+${installStep}    ${chalk.cyan('npm run dev')}
+
+${chalk.dim('  Stoix app will run at http://localhost:3000')}
+`);
+}
+async function main() {
+    if (!command || command === '--help' || command === '-h') {
+        printUsage();
+        process.exit(0);
+    }
+    if (command === '--version' || command === '-v') {
+        console.log(`stoix v${STOIX_VERSION}`);
+        process.exit(0);
+    }
+    if (command !== 'create') {
+        console.error(chalk.red(`\n  Unknown command: "${command}"\n`));
+        printUsage();
+        process.exit(1);
+    }
+    if (!projectName) {
+        console.error(chalk.red('\n  Error: Please provide a project name.\n'));
+        console.log(chalk.dim('    npx stoix create <project-name>\n'));
+        process.exit(1);
+    }
+    if (!validateProjectName(projectName)) {
+        console.error(chalk.red('\n  Error: Project name must start with a letter and contain only letters, numbers, hyphens, dots, or underscores.\n'));
+        process.exit(1);
+    }
+    await createProject(projectName);
+}
+main().catch((err) => {
+    console.error(chalk.red('\n  Error:'), err.message);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "stoix",
+  "version": "0.1.0",
+  "description": "Stoix — A Node + Express + React framework with Vite, fully written in TypeScript",
+  "type": "module",
+  "bin": {
+    "stoix": "dist/bin/index.js"
+  },
+  "scripts": {
+    "clean": "node -e \"const fs=require('fs');['template/node_modules','template/dist','template/.vite'].forEach(d=>{if(fs.existsSync(d)){fs.rmSync(d,{recursive:true,force:true});console.log('removed',d)}})\"",
+    "build": "tsc",
+    "prepack": "npm run clean && npm run build"
+  },
+  "files": [
+    "dist",
+    "template",
+    "!template/node_modules",
+    "!template/dist",
+    "!template/.vite"
+  ],
+  "keywords": [
+    "stoix",
+    "react",
+    "express",
+    "vite",
+    "typescript",
+    "framework",
+    "cli",
+    "scaffolding"
+  ],
+  "author": "Patrick",
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "fs-extra": "^11.2.0"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^20.11.0",
+    "typescript": "^5.3.3"
+  }
+}

package/template/.env

@@ -0,0 +1,2 @@
+PORT=3000
+NODE_ENV=development

package/template/.env.example

@@ -0,0 +1,2 @@
+PORT=3000
+NODE_ENV=development

package/template/gitignore

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+*.tsbuildinfo
+.DS_Store
+.env
+.env.local

package/template/index.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Stoix App</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>