Southpaw

A behavior-driven Next.js framework.

Southpaw is a superset of Next.js that enforces a strict separation between UI (Blocks), Logic (Behaviors), and Pages. It comes with a visual editor, AI-powered code generation, and a built-in component library.

Quick Start

Create a new Southpaw project:

npx southpaw

You'll be prompted to choose a project name and template. Then:

cd your-project
npm install
npm run dev

CLI Commands

| Command | Description | | --- | --- | | npx southpaw | Create a new project from a template | | npx southpaw generate-block | AI-powered block (component) generation | | npx southpaw generate-behavior | Scaffold a new behavior | | npx southpaw generate-page | Scaffold a new page | | npx southpaw test | Run route-level tests with Puppeteer |

Core Concepts

Behaviors

Manage global or shared state with create_behaviors. Define state, actions, when (action labels), then (state labels), and given (test scenarios).

Blocks

Reusable UI components built with create_component. Define propsDef for visual editor integration, local state, computed values, methods, and lifecycle hooks.

Pages

Connect blocks and behaviors using create_page. Access behaviors via this.do and this.get, and translations via this.trans.

Requirements

• Node.js >= 18
• Next.js >= 15.2.4

License

MIT