Nx TypeScript Repository

✨ A repository showcasing key Nx features for TypeScript monorepos ✨

📦 Project Overview

This repository demonstrates a production-ready TypeScript monorepo with:

• 3 Publishable Packages - Ready for NPM publishing

  • @org/strings - String manipulation utilities
  • @org/async - Async utility functions with retry logic
  • @org/colors - Color conversion and manipulation utilities

• 1 Internal Library

  • @org/utils - Shared utilities (private, not published)

🚀 Quick Start

# Clone the repository
git clone <your-fork-url>
cd typescript-template

# Install dependencies
npm install

# Build all packages
npx nx run-many -t build

# Run tests
npx nx run-many -t test

# Lint all projects
npx nx run-many -t lint

# Run everything in parallel
npx nx run-many -t lint test build --parallel=3

# Visualize the project graph
npx nx graph

⭐ Featured Nx Capabilities

This repository showcases several powerful Nx features:

1. 🔒 Module Boundaries

Enforces architectural constraints using tags. Each package has specific dependencies it can use:

• scope:shared (utils) - Can be used by all packages
• scope:strings - Can only depend on shared utilities
• scope:async - Can only depend on shared utilities
• scope:colors - Can only depend on shared utilities

Try it out:

# See the current project graph and boundaries
npx nx graph

# View a specific project's details
npx nx show project strings --web

Learn more about module boundaries →

2. 🛠️ Custom Run Commands

Packages can define custom commands beyond standard build/test/lint:

# Run the custom build-base command for strings package
npx nx run strings:build-base

# See all available targets for a project
npx nx show project strings

Learn more about custom run commands →

3. 🔧 Self-Healing CI

The CI pipeline includes nx fix-ci which automatically identifies and suggests fixes for common issues. To test it, you can make a change to async-retry.spec.ts so that it fails, and create a PR.

# Run tests and see the failure
npx nx test async

# In CI, this command provides automated fixes
npx nx fix-ci

Learn more about self-healing CI →

4. 📦 Package Publishing

Manage releases and publishing with Nx Release:

# Dry run to see what would be published
npx nx release --dry-run

# Version and release packages
npx nx release

# Publish only specific packages
npx nx release publish --projects=strings,colors

Learn more about Nx Release →

📁 Project Structure

├── packages/
│   ├── strings/     [scope:strings] - String utilities (publishable)
│   ├── async/       [scope:async]   - Async utilities (publishable)
│   ├── colors/      [scope:colors]  - Color utilities (publishable)
│   └── utils/       [scope:shared]  - Shared utilities (private)
├── nx.json          - Nx configuration
├── tsconfig.json    - TypeScript configuration
└── eslint.config.mjs - ESLint with module boundary rules

🏷️ Understanding Tags

This repository uses tags to enforce module boundaries:

Package	Tag	Can Import From
@org/utils	scope:shared	Nothing (base library)
@org/strings	scope:strings	scope:shared
@org/async	scope:async	scope:shared
@org/colors	scope:colors	scope:shared

The ESLint configuration enforces these boundaries, preventing circular dependencies and maintaining clean architecture.

🧪 Testing Module Boundaries

To see module boundary enforcement in action:

1. Try importing @org/colors into @org/strings
2. Run npx nx lint strings
3. You'll see an error about violating module boundaries

📚 Useful Commands

# Project exploration
npx nx graph                                    # Interactive dependency graph
npx nx list                                     # List installed plugins
npx nx show project strings --web              # View project details

# Development
npx nx build strings                           # Build a specific package
npx nx test async                              # Test a specific package
npx nx lint colors                             # Lint a specific package

# Running multiple tasks
npx nx run-many -t build                       # Build all projects
npx nx run-many -t test --parallel=3          # Test in parallel
npx nx run-many -t lint test build            # Run multiple targets

# Affected commands (great for CI)
npx nx affected -t build                       # Build only affected projects
npx nx affected -t test                        # Test only affected projects

# Release management
npx nx release --dry-run                       # Preview release changes
npx nx release                                 # Create a new release

Nx Cloud

Nx Cloud ensures a fast and scalable CI pipeline. It includes features such as:

• Remote caching
• Task distribution across multiple machines
• Automated e2e test splitting
• Task flakiness detection and rerunning

🔗 Learn More

• Nx Documentation
• Module Boundaries
• Custom Commands
• Self-Healing CI
• Releasing Packages
• Nx Cloud

💬 Community

Join the Nx community:

• Discord
• X (Twitter)
• LinkedIn
• YouTube
• Blog