Nx Project.json Cleanup Plan

Date: October 12, 2025
Branch: feat/nx-integration
Status: Ready for Execution

Problem Statement

We have 11 ui-* packages with redundant project.json files that only define lint and typecheck targets. These targets are automatically provided by Nx plugins:

lint → Provided by @nx/eslint/plugin
typecheck → Inferred from package.json scripts by nx:run-script executor

Testing Results

✅ Verified safe to remove:

Removed packages/ui-stay-match/project.json (test case)
Nx still detected the package
Both targets worked identically:
- yarn nx run ui-stay-match:lint → ✅ Success
- yarn nx run ui-stay-match:typecheck → ✅ Success
Targets were automatically inferred by plugins

Packages to Clean

The following 11 packages have redundant project.json files:

packages/ui-altfinder/project.json         - Only lint, typecheck
packages/ui-bonjour-services/project.json  - Only lint, typecheck
packages/ui-greenhost/project.json         - Only lint, typecheck
packages/ui-guestroom/project.json         - Only lint, typecheck
packages/ui-homestay/project.json          - Only lint, typecheck
packages/ui-hostguest/project.json         - Only lint, typecheck
packages/ui-pride-city/project.json        - Only lint, typecheck
packages/ui-room-lgbt/project.json         - Only lint, typecheck
packages/ui-roommate/project.json          - Only lint, typecheck
packages/ui-stay-match/project.json        - Only lint, typecheck
packages/ui-web/project.json               - Only lint, typecheck
packages/ui/project.json                   - Only lint, typecheck (check first)

Packages to Keep

The following packages MUST keep their project.json files:

Custom Build Tools

✅ packages/design-tokens/ - Uses Style Dictionary (not standard build)
✅ packages/storybook/ - Uses @nx/storybook:storybook executor
✅ packages/brands/ - Custom workspace build command
✅ packages/common/ - Custom workspace build command

Apps with Minimal Config

✅ All apps/*/mobile/project.json - Have empty targets: {} (already DRY!)
✅ All apps/*/web/project.json - Have empty targets: {} (already DRY!)

Execution Plan

Phase 1: Automated Safe Removal ✅

Script created: scripts/remove-redundant-project-jsons.sh

What it does:

Backs up all project.json files to timestamped directory
Tests lint/typecheck BEFORE removal
Removes redundant project.json files
Tests lint/typecheck AFTER removal
Verifies Nx graph still works
Automatically restores if ANY test fails

How to run:

./scripts/remove-redundant-project-jsons.sh

Phase 2: Validation

After removal, run comprehensive tests:

# Test all packages can be linted
yarn nx run-many --target=lint --all

# Test all packages with typecheck
yarn nx affected --target=typecheck --all

# Verify Nx graph
yarn nx graph

# Check project detection
yarn nx show projects | wc -l  # Should still be 86 projects

Phase 3: Commit

If all tests pass:

git add .
git commit -m "refactor(nx): Remove redundant project.json files

Removed project.json files from 11 ui-* packages that only contained
lint and typecheck targets. These targets are automatically inferred
by Nx plugins (@nx/eslint/plugin and nx:run-script).

Benefits:
- Follows DRY principle (Don't Repeat Yourself)
- Reduces maintenance burden (no need to update 11 files)
- Leverages Nx plugin inference system properly
- Aligns with Nx best practices documented in ADR-001

Packages affected:
- ui-altfinder
- ui-bonjour-services
- ui-greenhost
- ui-guestroom
- ui-homestay
- ui-hostguest
- ui-pride-city
- ui-room-lgbt
- ui-roommate
- ui-stay-match
- ui-web
- ui

Kept project.json for packages with custom configuration:
- design-tokens (Style Dictionary)
- storybook (@nx/storybook executor)
- brands (custom build)
- common (custom build)

Tested:
✅ All lint targets work
✅ All typecheck targets work
✅ Nx graph generates correctly
✅ All 86 projects still detected

Refs: ADR-001, #nx-integration"

Rollback Plan

If something breaks:

# Automatic rollback (script does this automatically)
# Or manual restoration:
BACKUP_DIR="/tmp/nx-project-json-backups-YYYYMMDD-HHMMSS"
cp $BACKUP_DIR/*.json packages/

# Or git revert:
git revert HEAD

Benefits

DRY Compliance: No redundant configuration across 11 files
Easier Maintenance: Changes to lint/typecheck happen in one place (nx.json plugins)
Nx Best Practices: Leverages plugin inference system as intended
Future-Proof: New ui-* packages won’t need project.json
Cleaner Codebase: Less configuration files to maintain

Risks & Mitigation

Risk	Probability	Impact	Mitigation
Targets stop working	Low	High	Automated testing + instant rollback
Nx graph breaks	Very Low	Medium	Graph validation in script
CI/CD breaks	Low	High	Test locally first, rollback on failure
Developer confusion	Low	Low	Documentation in ADR-001

Success Criteria

✅ All lint targets work across all 11 packages
✅ All typecheck targets work across all 11 packages
✅ Nx graph generates without errors
✅ All 86 projects still detected by Nx
✅ No build failures in affected packages
✅ Documentation updated (ADR, guides)

Timeline

Script Creation: ✅ Complete
Execution: Ready (awaiting approval)
Validation: ~5 minutes
Commit: ~1 minute
Total Time: ~10 minutes

Approval Required

Script reviewed and tested
User approval to proceed with execution
Backup strategy confirmed
Rollback plan understood

docs/architecture/ADR-001-nx-plugin-inference.md - Architectural decision
docs/nx-integration-guide.md - Comprehensive Nx guide
scripts/remove-redundant-project-jsons.sh - Automated removal script

Ready to execute when you give the green light! 🚀