Locus is a source-to-source compiler and toolchain for building full-stack web applications with maximum velocity and clarity. Write simple, declarative .locus files and generate:

• Backend API: Express.js server with RESTful routes
• Database: Prisma schema and migrations
• Frontend UI: React components and Next.js pages
• Design System: Theming and styling via design tokens

🚀 Key Features

• Declarative Syntax: Define your entire app—data, logic, and UI—in one place
• Full-Stack Generation: Prisma, Express, React/Next.js, and CSS from a single source
• Incremental Builds: Fast dev mode with hot reload and smart rebuilds
• Helpful Diagnostics: Clear errors with file, line, and column info
• Extensible: Plugin system for custom features and integrations
• Performance-Focused: Lightweight parser and efficient codegen

📦 How It Works

1. Parse: Reads all .locus files and builds an AST (Chevrotain)
2. Merge: Combines all features, entities, and design tokens into a unified AST
3. Generate: Produces deterministic code for database, API, UI, and theme

🏁 Quickstart

Prerequisites

• Node.js (v18 or higher)

1. Install the CLI

npm install -g @plust/locus

2. Create a New Project

locus new my-app
cd my-app

3. Start the Development Server

locus dev

🗂️ Generated Project Structure

./generated/
├── prisma/
│   └── schema.prisma       # Database schema
├── routes/
│   └── *.ts                # Express routers per entity
├── react/
│   ├── pages/
│   │   └── *.tsx           # React pages
│   └── components/
│       └── *.tsx           # React components
├── theme.css               # Design tokens as CSS variables
└── server.ts               # Express app bootstrap

🛠️ Command-Line Interface (CLI)

| Command | Description | | ------------------------ | ------------------------------------------------------------------------ | | locus new <name> | Scaffold a new project with config and sample files | | locus build | Full, deterministic build of the project | | locus dev | Dev server with hot reload and incremental rebuilds | | locus db migrate | Run Prisma migrations | | locus db studio | Launch Prisma Studio for data management | | locus deploy | Build and deploy to Vercel, Railway, etc. | | locus add <package> | Add npm packages to frontend or backend |

Common Flags:

• --src <dir>: Source directory for .locus files
• --out <dir>: Output directory for generated code
• --debug: Detailed timing logs

⚙️ Configuration

• Project settings: Locus.toml
• Design tokens: design_system { ... } blocks in .locus files

🧑‍💻 Development & Contributing

• Tech Stack: TypeScript, Jest, Chevrotain, Commander.js
• How to Contribute:
  1. Fork and clone the repo
  2. Install dependencies: npm install
  3. Run tests: npm test
  4. Add features with tests and docs

📚 Documentation

• Introduction & Philosophy
• Getting Started
• Language Reference
• Application Logic
• UI Syntax
• Design System
• Toolchain & CLI
• Development Workflow
• Deployment
• Plugins & Extensibility
• Architecture

📝 License

MIT. See the LICENSE file for details.