monorepo

A modern TypeScript monorepo with Nx, featuring automated releases, comprehensive code quality tools, and strict type safety.

🚀 Quick Start

Dev Container (Recommended)

1. Install Docker Desktop and the Dev Containers extension
2. Open the repo in VS Code and click Reopen in Container when prompted
3. All tools and dependencies are installed automatically

Local Setup (macOS)

# Automated setup (installs tools & dependencies via Homebrew)
./scripts/local/setup.sh

Development

# Run development server
nx run lexico:develop
nx run caelundas:develop

# Run tests
nx run-many --target=test --all

# Run all quality checks
nx run-many --target=code-analysis --all

📦 Projects

• affirmations - Python LangChain + Ollama affirmation generator (LangGraph ReAct agent, SearxNG)
• caelundas - CLI ephemeris calendar generator with astronomical calculations
• lexico - TanStack Start + Supabase dictionary web application
• lexico-components - Shared React component library using shadcn/ui
• JimmyPaolini - Personal website

📚 Documentation

• Contributing Guide - Development workflow, code standards, and release process
• Commit Messages - Conventional Commits format and examples
• Release Process - Automated versioning and changelog generation
• GitHub Actions - CI/CD workflows, composite actions, and pipeline architecture

🛠️ Development

Running Tasks

# Use Nx to run tasks (handles caching and dependencies)
nx run <project>:<target>

# Examples
nx run caelundas:test
nx run lexico:build
nx run lexico-components:lint

# Run for all projects
nx run-many --target=test --all

# Run for affected projects only
nx affected --target=test

Code Quality Tools

All projects use strict TypeScript configuration and comprehensive linting:

• ESLint - Code linting with strict rules
• Oxfmt - Primary code formatter
• Prettier - Supplementary code formatting
• Biome - Supplementary format checking and linting
• TypeScript - Strict type checking
• Knip - Unused code detection
• cspell - Spell checking
• markdownlint - Markdown linting
• Vitest - Unit and integration testing

Knip - Unused Code Detection

Knip finds and removes unused files, dependencies, and exports across the monorepo.

Check for unused code:

# Check entire monorepo
nx run monorepo:knip

# Check specific project
nx run caelundas:knip
nx run lexico:knip
nx run lexico-components:knip
nx run code-generator:knip

# Check only affected projects
nx affected --target=knip

# Explicitly use check configuration
nx run monorepo:knip:check

Auto-fix unused code:

# Fix entire monorepo (use with caution)
nx run monorepo:knip:write

# Fix specific project
nx run caelundas:knip:write
nx run lexico:knip:write

Note: Review knip findings carefully before running knip:write. The write configuration automatically removes unused files, dependencies, and exports.

Integration:

• Pre-commit hooks: Runs automatically on staged files via lint-staged
• CI/CD: Runs on all PRs via GitHub Actions workflow

🚢 Release Process

Releases are fully automated using semantic-release:

1. Merge PR to main branch
2. Commits are analyzed (Conventional Commits)
3. Version is determined automatically
4. CHANGELOG.md is generated/updated
5. GitHub release is created

Version Bumps:

• feat: commits → minor version (1.0.0 → 1.1.0)
• fix: commits → patch version (1.0.0 → 1.0.1)
• BREAKING CHANGE: → major version (1.0.0 → 2.0.0)

See release.config.cjs for complete configuration and guide.

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

• Development workflow
• Code standards and conventions
• Commit message format
• Pull request process
• Release guidelines

All commits must follow Conventional Commits format.

📄 Code Ownership

All files are owned by @JimmyPaolini. See .github/CODEOWNERS.

📖 Additional Resources

• Nx Documentation
• Conventional Commits
• TanStack Start
• shadcn/ui
• Vitest

📝 License

MIT License. Copyright (c) Jimmy Paolini.