| name | ns-replace-package |
| description | Finds and evaluates alternatives to an npm package. Use when the user wants to replace, drop, or swap a dependency, migrate away from a deprecated/abandoned/risky package, or asks "what can I use instead of X?" Compares candidates with NCM data and provides migration/API-diff guidance. Use ns-upgrade-package for staying on the same package. |
1. Identify the Package to Replace
- Extract the package name from the user's request.
- Read
package.json to confirm whether it is installed and note the current version and whether it is a direct or dev dependency.
- Detect package manager by lockfile (
pnpm-lock.yaml → pnpm, yarn.lock → yarn, package-lock.json → npm; default npm).
2. Fetch NCM Data for the Target Package
- Call
getPackageQuality for the package being replaced.
- Document: vulnerabilities (severity + title), license, module risks flagged by NCM (e.g. install scripts, obfuscation, author risk, malware), quality scores.
- Use these findings as the objective reasons why replacement is warranted.
3. Propose Alternatives
- Based on the package's domain and the user's context, identify 2–3 realistic alternative packages.
- For each proposed alternative, call
getPackageQuality to retrieve its own vulnerability, license, and quality data before recommending it.
- Discard any alternative that has critical/high vulnerabilities or critical module risks unless the user explicitly asks to include it.
- Do not invent unpublished packages or packages you are not confident exist.
4. Compare and Recommend
Present a comparison table or ranked list with these columns:
- Package name
- NCM vulnerability status
- License
- NCM module risks
- Maintenance signal (latest version age, if available from NCM)
- Why it is or isn't recommended
Lead with the strongest recommendation and explain the tradeoff clearly.
5. Migration Plan
For the top recommended alternative, provide:
- Why replace — reference the NCM-reported issues with the original package.
- Install command — exact command for the detected package manager.
- Uninstall command — exact command to remove the original package.
- API differences — key differences between the two APIs with before/after code examples. Focus on the most commonly used features.
- Configuration changes — any config files, environment variables, or build-tool settings that need updating.
- Test checklist — what to verify after migration.
Tools
getPackageQuality — call once for the target package and once for each proposed alternative. Do not recommend an alternative without querying NCM for it first.
Guardrails
- Do not invent unpublished or fictional alternatives. Only recommend packages that genuinely exist and are relevant to the use case.
- Ground the "why replace" section in NCM-reported data, not general opinion.
- Validate every proposed alternative via
getPackageQuality before including it in the comparison.
- If NCM data is unavailable for the target, state that clearly and proceed with general guidance only, flagging the absence of grounded data.
