LeiCraftMC Style Guides

The single source of truth for how code is written, designed, and structured across the LeiCraftMC ecosystem — git.leicraftmc.de/LeiCraftMC & github.com/LeiCraftMC — and all of its subprojects: LeiOS, Delivr, NowIP, NetIgnite, Vault, MindCode, the LeiCraftMC sites, and everything that comes after.

This repo is for two audiences:

• Humans — read docs/ in order to learn the house style before contributing.
• AI coding tools — read AGENTS.md (or CLAUDE.md for Claude Code) first, then the relevant docs/ pages. Copy from shared/ and scaffold from templates/ instead of inventing patterns.

Everything here is derived from how the ecosystem already writes code (14 reference repos were audited), then makes opinionated calls to close the gaps where practice diverged.

Tech stack at a glance

Layer	Choice
Runtime & package manager	Bun (also the test runner; server Nuxt apps build with the Nitro bun preset)
Language	TypeScript, ESM, "private": true, strict
Formatter & linter	Biome (org standard — see docs/02-tooling.md)
Backend	Hono + Zod + hono-openapi (Scalar UI) + Drizzle (SQLite)
Frontend	Nuxt 4 (app/ dir) + NuxtUI v4 + Tailwind v4 (CSS-first)
CLI tooling	@cleverjs/cli + bun build --compile
API contract	OpenAPI generated at runtime → @hey-api/openapi-ts typed client
Response shape	{ success, code, message, data } envelope, end-to-end
CI	GitLab CI (oven/bun) in the templates; GitHub Actions workflows are opt-in from shared/config/github-actions/; Renovate everywhere
License	AGPL-3.0 (every template ships a LICENSE)
Commits	Conventional Commits

Repo layout

Style-Guides/
├── README.md            ← you are here
├── AGENTS.md            ← read this first if you are an AI coding agent
├── CLAUDE.md            ← Claude-Code-specific layer on top of AGENTS.md
├── docs/                ← the spec, one focused page per topic (00 → 17)
├── shared/              ← the templates' core files (logger, config, APIResponse, auth, useAPI, stores, CI, …), same paths
├── assets/              ← brand logos, icons, and design-system guidance
└── templates/           ← ready-to-use scaffolds — the source of truth (see below)

Templates

Template	What it is	Default port
backend-service	Hono API service, compiled to one binary, Docker image	12500
nuxt-app	Nuxt frontend for a separate backend-service (landing, auth, dashboard, admin)	12510
fullstack-nuxt-app	nuxt-app + backend-service in one codebase (API under /api)	12520
static-site	Static Nuxt site (nuxt generate, rsync deploy)	12530
static-site-with-docs	static-site + @nuxt/content docs section	12531
cli-tool	@cleverjs/cli tool, released as binaries on v* tags	—

The templates are deliberately rich (cron jobs, background tasks, email, admin area, onboarding, …): delete what your project doesn't need.

How to use this

Starting a new project — copy a template from templates/, then follow its README.md: replace <ProjectName>, the APPPREFIX env prefix / appprefix token prefix, the <PREFIX> session-cookie name (Nuxt), and give the app its own port (the defaults above, never 3000; see docs/02 — Ports). In an existing project, pull the core files from shared/ — they sit at the same paths as in the templates — rather than re-implementing them.

Contributing to an existing project — read the relevant docs/ pages first. When in doubt, the existing codebase + this guide are the authority; generic internet advice is not.

As an AI agent — start at AGENTS.md.

The spec — docs/

Read top to bottom on first pass; jump to a page on demand.

1. 00 — Overview — purpose, audience, the guiding principle
2. 01 — Project structure — repo layout per project type
3. 02 — Tooling — Bun, TypeScript, Biome, scripts, Renovate, MCP
4. 03 — Naming & TypeScript style
5. 04 — Backend (Hono) — app lifecycle, routes, OpenAPI, the envelope
6. 05 — API contract — OpenAPI as the bridge, generated client
7. 06 — Frontend (Nuxt) — Nuxt 4, NuxtUI v4, Tailwind v4
8. 07 — State & data — useAPI, AbstractStore, cookies
9. 08 — Database — Drizzle, the DB class, migrations
10. 09 — Config & logging — ConfigSchema, Logger
11. 10 — Auth — opaque tokens, AuthContext, middleware
12. 11 — CLI & infra — @cleverjs/cli, compile, graceful shutdown
13. 12 — Testing — bun:test, the preload harness, integration tests
14. 13 — Git & CI — Conventional Commits, GitLab/GitHub pipelines
15. 14 — Deployment — compiled-binary Docker, Nuxt .output on Bun, static rsync
16. 15 — Design system — dark-first, palette, fonts, logos, status semantics
17. 16 — AI tooling — CLAUDE.md/AGENTS.md, .claude/settings.json commands, MCP
18. 17 — Decisions & divergences — the opinionated calls and why

Locked decisions

Four foundational standards were set for the org (rationale in docs/17-decisions.md):

• Biome for formatting + linting (the ecosystem had no enforced formatter before).
• AGPL-3.0 as the default license for templates and services.
• Copy-paste snippets now, published @leicraftmc/* package later for shared utilities.
• Conventional Commits (feat: / fix: / chore: …).

Contributing

This guide is itself a LeiCraftMC project: it is formatted with Biome and type-checked with tsc. Before committing, run bun install && bun run check:ci && bun run typecheck. The root Biome config excludes templates/ and shared/config/: when you change a template, run its own bun run check:ci, bun run typecheck and bun test inside it, and keep shared/ in sync with it. A change that would break code copied from an earlier version keeps the old API as @deprecated instead of removing it; only security fixes and bugs every project must fix anyway may break directly (see docs/17-decisions.md #26). The /verify, /typecheck, /format, and /test helper slash commands are defined in .claude/settings.json (see docs/16).

License

AGPL-3.0. The shared utilities and templates inherit it by default; permissive licensing for standalone libraries/tools is a case-by-case decision (see docs/17-decisions.md).