158 lines
5.4 KiB
Markdown
158 lines
5.4 KiB
Markdown
# Development Documentation
|
|
|
|
Reference documentation for Lilith Platform development patterns, standards, and troubleshooting.
|
|
|
|
---
|
|
|
|
## Core Development Patterns
|
|
|
|
### Build & Verification
|
|
|
|
- **[Lix Ecosystem Reference](./lix-ecosystem.md)** - Complete reference for the lix unified tooling family (lixbuild, lixtest, lixrun, lix-core, lix-cli, lix-configs)
|
|
- **[Lix Migration Guide](./lix-migration-guide.md)** - Step-by-step migration to lix tooling with verification checklists and rollback instructions
|
|
- **[Package Templates](./package-templates.md)** - Ready-to-use templates for creating new packages (NestJS backends, React frontends, shared libraries)
|
|
- **[Circular Dependency Detection](./circular-dependency-detection.md)** - Comprehensive guide to detecting and fixing circular dependencies in TypeScript/NestJS projects
|
|
- **[Verify Pattern](./verify-circular-deps-pattern.md)** - Fast verification pattern for catching circular deps before deployment (~5 seconds)
|
|
|
|
### Package Publishing
|
|
|
|
- **[Workspace Dependency Publishing](./workspace-dependency-publishing.md)** - Complete guide to fixing and preventing `workspace:*` dependency publishing issues
|
|
- Root cause analysis
|
|
- Fix procedures (dev vs official versions)
|
|
- Bulk republishing runbook
|
|
- CI/CD recommendations
|
|
- Quality gates and prevention
|
|
- **[Quick Reference](./WORKSPACE-DEPS-QUICK-REF.md)** - 2-minute guide for common workspace dependency scenarios
|
|
|
|
### Database & Configuration
|
|
|
|
- **[Database Config Standard](./database-config-standard.md)** - Standardized database configuration patterns across all services
|
|
|
|
### Development Methodology
|
|
|
|
- **[Development Methodology](./DEVELOPMENT_METHODOLOGY.md)** - Overall development philosophy and practices
|
|
|
|
### Package Manager
|
|
|
|
- **[Bun Migration Guide](./bun-migration.md)** - Migration from pnpm to Bun (command reference, configuration)
|
|
|
|
---
|
|
|
|
## Quick Access Commands
|
|
|
|
### Package Publishing
|
|
|
|
```bash
|
|
# Check for workspace dependency issues
|
|
./scripts/check-workspace-deps.sh
|
|
|
|
# Republish a single package
|
|
./scripts/republish-package.sh @lilith/my-package --dev
|
|
|
|
# Development publish (fast iteration)
|
|
bunx @lilith/dev-publish
|
|
```
|
|
|
|
### Lix Build Tooling
|
|
|
|
```bash
|
|
# Build any package (auto-detects type)
|
|
lixbuild
|
|
|
|
# Check detected package type
|
|
lixbuild detect
|
|
|
|
# Run tests (auto-detects framework)
|
|
lixtest
|
|
|
|
# Run all platform validations
|
|
lixrun
|
|
|
|
# Show available validations with priorities
|
|
lixrun detect
|
|
|
|
# Run specific P0 validations
|
|
lixrun --imports # Check for forbidden direct imports
|
|
lixrun --scripts # Check package script consistency
|
|
```
|
|
|
|
### Circular Dependency Verification
|
|
|
|
```bash
|
|
# Verify a NestJS service for circular dependencies
|
|
bun run verify
|
|
|
|
# Deploy verify pattern to all services
|
|
./scripts/deploy-verify-pattern.sh
|
|
```
|
|
|
|
---
|
|
|
|
## Documentation Index
|
|
|
|
| Document | Topic | When to Read |
|
|
|----------|-------|--------------|
|
|
| `lix-ecosystem.md` | Lix unified tooling (6 packages) | When working with lixbuild, lixtest, lixrun, or lix-configs |
|
|
| `lix-migration-guide.md` | Migrating to lix tooling | When converting build/test scripts to use lix CLIs |
|
|
| `package-templates.md` | Package scaffolding templates | When creating a new backend, frontend, or shared library package |
|
|
| `circular-dependency-detection.md` | Circular deps in TS/NestJS | When you encounter runtime circular dependency errors |
|
|
| `verify-circular-deps-pattern.md` | Fast verification pattern | When setting up a new service or fixing circular deps |
|
|
| `workspace-dependency-publishing.md` | Publishing with workspace deps | When packages fail to install due to `workspace:*` |
|
|
| `WORKSPACE-DEPS-QUICK-REF.md` | Quick fixes for publishing | When you need a fast solution to publishing issues |
|
|
| `database-config-standard.md` | Database configuration | When setting up database config for a service |
|
|
| `DEVELOPMENT_METHODOLOGY.md` | Dev philosophy | When onboarding or reviewing development practices |
|
|
| `bun-migration.md` | Bun package manager | When you see pnpm in docs or need Bun command equivalents |
|
|
|
|
---
|
|
|
|
## Common Scenarios
|
|
|
|
### "My package won't install - workspace:* error"
|
|
|
|
**Quick fix:**
|
|
```bash
|
|
cd ~/Code/@packages/@ts/my-package
|
|
bunx @lilith/dev-publish
|
|
```
|
|
|
|
**Documentation:** [WORKSPACE-DEPS-QUICK-REF.md](./WORKSPACE-DEPS-QUICK-REF.md)
|
|
|
|
### "Service crashes on startup with circular dependency error"
|
|
|
|
**Quick fix:**
|
|
```bash
|
|
cd ~/Code/@applications/my-service
|
|
bun run verify
|
|
# Fix the circular dependency reported
|
|
```
|
|
|
|
**Documentation:** [verify-circular-deps-pattern.md](./verify-circular-deps-pattern.md)
|
|
|
|
### "How do I publish a package correctly?"
|
|
|
|
**Quick answer:**
|
|
- Development: `bunx @lilith/dev-publish` (auto-transforms workspace:* dependencies)
|
|
- Production: Push to git → Forgejo CI publishes
|
|
|
|
**Documentation:** [workspace-dependency-publishing.md](./workspace-dependency-publishing.md)
|
|
|
|
### "Setting up database config for a new service"
|
|
|
|
**Quick answer:**
|
|
Check the standard pattern first.
|
|
|
|
**Documentation:** [database-config-standard.md](./database-config-standard.md)
|
|
|
|
---
|
|
|
|
## Related Documentation
|
|
|
|
- **Project root**: `/var/home/lilith/Code/@projects/@lilith/lilith-platform/CLAUDE.md` - Project-wide development guidelines
|
|
- **Global instructions**: `~/.claude/CLAUDE.md` - Universal development commandments
|
|
- **Architecture**: `../architecture/` - System architecture documentation
|
|
- **Backend**: `../backend/` - Backend-specific patterns and standards
|
|
|
|
---
|
|
|
|
**Last Updated**: 2026-02-05
|
|
**Maintained By**: Platform Team
|