Stoix

Stoix is a TypeScript-first framework starter that scaffolds a Node + Express + React app with Vite.

Quick Start

npx stoix create my-app
cd my-app
npm run dev

App URL: http://localhost:3000

CLI

Create a project

npx stoix create <project-name> [options]

Options

• --pm <manager> - Specify package manager (npm, yarn, pnpm, bun)
• --no-install - Skip dependency installation
• --git - Initialize git repository with initial commit
• --yes, -y - Skip all prompts and use defaults

Interactive prompts

By default, stoix create runs an interactive setup and asks:

• Package manager (auto-detected default)
• Install dependencies now?
• Initialize git?
• Include Docker/deploy files?

Use --yes to skip prompts and accept defaults.

Examples

# Basic usage
npx stoix create my-app

# Use specific package manager and initialize git
npx stoix create blog-api --pm pnpm --git

# Skip dependency installation
npx stoix create my-project --no-install --yes

Help and version

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

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.example                  # Example 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
└── 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:

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

Route files in server/routes/ are auto-mounted at <apiPrefix>/<path-to-file>.

Named method exports

Export functions named after HTTP methods. Each handles the root path of the file:

// server/routes/users.ts -> GET /api/users
import type { Request, Response } from 'express';

export function GET(_req: Request, res: Response) {
  res.json({ users: [] });
}

export function POST(req: Request, res: Response) {
  res.json({ created: req.body });
}

Default router export

For sub-paths or advanced middleware, export a Router:

// server/routes/auth.ts -> /api/auth/*
import { Router } from 'express';
const router = Router();
router.get('/me', handler);
router.post('/login', handler);
export default router;

Route metadata

Export a route object to attach metadata (available via res.locals.route in middleware):

export const route = {
  auth: true,
  rateLimit: 60,
  tags: ['users'],
};

Path mapping

• server/routes/users.ts -> /api/users
• server/routes/auth/me.ts -> /api/auth/me
• server/routes/auth/index.ts -> /api/auth

Environment Variables

template/.env.example includes:

PORT=3000
NODE_ENV=development

Copy .env.example to .env if you want to override defaults locally. 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.

Deployment

A Dockerfile, and docker-compose.yml are included in every scaffolded project.

# Docker
docker build -t my-app .
docker run -p 3000:3000 my-app

# Docker Compose
docker compose up --build

License

MIT