refactor(deps): isolate documentation dependencies into an npm workspace

Closed
  • Is something wrong?
#531 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

A pull request for this has already been merged.

  • #549 by @Kuldeep2822k — merged

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
48/100
Issue type
Refactor
Clarity
Mostly clear
Activity status
Active
Tech stack
node.js, typescript
Domain
build-system, cli, documentation

Research direction

Start by reading the root package.json and .github/workflows/deploy-docs.yml, then trace the existing documentation scripts and install commands. Move the listed documentation dependencies and overrides into a docs workspace, keep the named CLI tools at the root, and update the scripts and workflow to use that workspace. Done when documentation builds and deploys through the workspace while the root retains only the listed CLI development tools.

Written by the indexing model from the issue text.

Description

build dependencies documentation refactor
Problem Statement

The root package.json currently includes both core CLI development dependencies and the documentation site toolchain:

  • vitepress (^1.6.4)
  • vitepress-plugin-mermaid (^2.0.17)
  • mermaid (^11.16.1)
  • markdown-it-mathjax3 (^4.3.2)

These doc-generation tools account for ~85% of total packages in node_modules (~400 of 462 packages) and form deep transitive dependency chains (up to 12 levels deep via Vue/Babel/PostCSS, plus nested CVE surfaces such as DOMPurify and KaTeX).

Core CLI tasks (compiling TypeScript, linting, executing unit/invariant tests via tsx, and computing coverage with c8) do not need any of these packages.

Proposed Solution

Isolate the documentation toolchain into its own npm workspace (e.g., docs/package.json or via workspaces: ["docs"]).

  1. Move Docs Dependencies: Transfer vitepress, mermaid, vitepress-plugin-mermaid, markdown-it-mathjax3, and their related overrides (katex, dompurify) to docs/package.json.
  2. Keep Root Lean: Retain only core CLI development tools (typescript, eslint, tsx, c8, diff-cover) in root devDependencies.
  3. Update Workflows: Update doc build/dev scripts and .github/workflows/deploy-docs.yml to operate against the docs workspace.
Benefits
  • Zero Supply-Chain Bloat in CLI Toolchain: Eliminates deep transitive dependency trees and reduces noise from third-party audit advisories affecting only doc rendering.
  • Faster CI/Dev Installs: CI jobs running tests/linting don't need to resolve or unpack hundreds of docs-only packages.
  • Decoupled Tooling: Documentation site dependencies can be updated independently without affecting CLI release gates.
Dominant language
TypeScript
Stars
1
Forks
0
Avg merge
17h 14m
Merged PRs (30d)
170

Getting set up

  • No Dockerfile or Docker Compose file
  • Has a pull request template
  • No contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from Kuldeep2822k/cli

All issues in Kuldeep2822k/cli

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.