@plust/locus

Locus

The Full-Stack App Compiler

Transform .locus files into complete, production-ready web applications.

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

• Parse: Reads all .locus files and builds an AST (Chevrotain)
• Merge: Combines all features, entities, and design tokens into a unified AST
• 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:
  • Fork and clone the repo
  • Install dependencies: npm install
  • Run tests: npm test
  • 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.