basalt

README

Basalt

Basalt is a high-performance, open-source CLI tool built in Go for generating production-ready backends from a simple DSL.

Why Basalt?

The typical AI-assisted backend workflow looks like this:

"Build me a REST API for users with JWT and Supabase" → AI generates 200 lines of code → you fix the mess

The AI is generating the implementation. That's the wrong layer.

Basalt flips this. Instead of asking an AI to write TypeScript, you ask it to write a .bs file — a small, constrained description of what your backend should do. Basalt handles the rest.

You describe → AI writes main.bs → Basalt generates the backend

This has three concrete advantages:

Token efficiency. 10 lines of DSL vs 200 lines of TypeScript. Your AI calls get up to 20x cheaper.

Consistency. Every project generated by Basalt follows the same structure, the same conventions, the same patterns. No more "why did it do it this way this time?".

Reliability. The AI can't hallucinate an import or invent an architecture. The DSL is closed and constrained — if it's valid .bs, the output is valid code.

Basalt is to backend generation what Terraform is to infrastructure — a language that separates intent from implementation.

Features

• Beautiful TUI — Interactive project initialization and progress tracking built with Bubble Tea.
• Fast Generation — Hand-written recursive descent parser for maximum speed.
• Production Ready — Generates clean TypeScript with Express/Fastify/Hono and Supabase integration.
• Live Reload — Watch mode with basalt dev for instant regeneration on save.
• AI-First — Any AI that reads the spec can generate valid .bs files from natural language.

Install

go install github.com/DiegoDev2/basalt/cmd/basalt@latest

Quick Start

1. Ask an AI to write your main.bs

Give any AI (Claude, ChatGPT, Gemini) the Basalt spec and describe your backend:

Read the Basalt DSL spec at https://github.com/DiegoDev2/basalt/blob/main/spec/SPEC.md
and generate a main.bs file for a blog API with users, posts and comments.

OR

2. Initialize the project if you already have a main.bs file, you can skip this step:

basalt init

3. Generate your backend

basalt generate

4. Run your API

cd generated && pnpm install && pnpm dev

DSL Reference

config {
  db:        supabase
  auth:      jwt
  framework: express
  lang:      typescript
}

table "users" {
  id:         uuid      @primary
  email:      string    @unique
  name:       string
  created_at: timestamp @default(now)
}

resource "users" {
  table: users
  endpoints {
    GET    /users
    POST   /users
    GET    /users/:id
  }
}

Full DSL specification → spec/SPEC.md

Current State & Roadmap

Basalt is in active early development. Right now, all generated projects share the same template structure — Express + TypeScript + Supabase. This is intentional for v1: we wanted a solid, working foundation before expanding.

Here's what's coming:

• More templates — Fastify, Hono, PostgreSQL, MySQL support
• Custom templates — bring your own code generation templates
• AI-native generation — a basalt ai command that takes a natural language description and generates the .bs file for you
• Codegen without templates — longer term, a mode where the generator reasons about your schema and produces code dynamically instead of filling in templates

If you want to contribute a template or framework adapter, read CONTRIBUTING.md.

Contributing

Basalt is open source and welcomes contributions. See CONTRIBUTING.md for how to add new framework adapters, templates, or DSL features.

License

MIT