[Proposal] Evolving Workspace Guidance: Transitioning from "Nest-Only" Monorepos to Industry-Standard Workspaces in proper monorepo managers (Nx, Turborepo, Rush)

[smolinari]

The NestJS CLI "monorepo mode" was designed in an era when framework-specific CLI orchestration was the norm. However, the industry has shifted toward unified workspaces. Today, NestJS is almost exclusively used as an API layer alongside frontend frameworks (React, Vue, Angular) or auxiliary services in other languages.

The current built-in monorepo mode creates a significant architectural dead end for teams. This proposal suggests deprecating the "Monorepo Mode" documentation in favor of comprehensive recipes for specialized workspace managers that support the full modern stack.

The "Dead Ends" of the Current CLI Mode:

The "Walled Garden" Problem (Primary Issue): The Nest CLI is designed to manage Nest projects. In a real-world scenario, a monorepo must house the frontend, shared UI libraries, and potentially non-Node services. Forcing developers to maintain a "Nest monorepo" alongside other separate repos defeats the entire purpose of a monorepo (atomic commits, shared types, and unified DX).

Incompatibility with Modern Package Managers: Tools like pnpm and Yarn/Bun Workspaces have native ways of handling dependency hoisting and linking. The Nest CLI’s internal workspace logic often conflicts with these standards, leading to "phantom dependency" issues and complex nest-cli.json configurations that don't scale.

Lack of Task Orchestration: Beyond simple builds, the Nest CLI cannot handle the complex dependency graphing required to run "affected" tests or builds. In a 20+ project workspace, rebuilding everything because one library changed is a non-starter for CI/CD efficiency.

Developer Experience (DX) Fragmentation: When teams grow, they need a "single source of truth" for the entire repository's pipeline. Having one orchestration logic for the Nest apps and a completely different one for the rest of the stack creates unnecessary cognitive load and maintenance overhead.

Proposed Action Plan:

New Industry-Standard Recipes: I offer to author and maintain high-quality "Recipe" guides for the documentation covering:

Nx: The gold standard for NestJS integration, providing full polyglot support and remote caching.

Turborepo: For teams wanting a lightweight, "zero-config" orchestration layer that works with the existing Nest CLI.

Rush/pnpm: For enterprise-scale isolation and strict dependency management.

Documentation Restructuring: * Move the current "Monorepos" section to an "Internal Workspaces (Legacy)" category.

Update the primary "Workspaces" landing page to recommend the specialized tools as the "Industry Standard" path for new projects.

CLI UX Updates:

Add a (deprecated) or (legacy) tag to workspace-related commands in nest --help.

Introduce a soft warning when initializing a Nest workspace, pointing users toward the new documentation recipes for a more future-proof setup.

Commitment:

I am prepared to submit the PRs for the @nestjs/docs restructuring and the authoring of all three recipes, as well as the necessary updates to the @nestjs/cli help messages.

Scott