sb-dev/openquant / .agents/skills/node
node
VerifiedProvides domain-specific best practices for Node.js development with TypeScript, covering type stripping, async patterns, error handling, streams, modules, testing, performance, caching, logging, and more. Use when setting up Node.js projects with native TypeScript support, configuring type stripping (--experimental-strip-types), writing Node 22+ TypeScript without a build step, or when the user mentions 'native TypeScript in Node', 'strip types', 'Node 22 TypeScript', '.ts files without compilation', 'ts-node alternative', or needs guidance on error handling, graceful shutdown, flaky tests, profiling, or environment configuration in Node.js. Helps configure tsconfig.json for type stripping, set up package.json scripts, handle module resolution and import extensions, and apply robust patterns across the full Node.js stack.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.3 KB |
| rules/assets/graceful-server.test.ts | script | 2.6 KB |
| rules/assets/graceful-server.ts | script | 2.2 KB |
| rules/async-patterns.md | markdown | 3.1 KB |
| rules/caching.md | markdown | 4.8 KB |
| rules/environment.md | markdown | 6.0 KB |
| rules/error-handling.md | markdown | 3.8 KB |
| rules/flaky-tests.md | markdown | 10.4 KB |
| rules/graceful-shutdown.md | markdown | 4.6 KB |
| rules/logging.md | markdown | 4.4 KB |
| rules/modules.md | markdown | 2.0 KB |
| rules/node-modules-exploration.md | markdown | 3.6 KB |
| rules/performance.md | markdown | 2.8 KB |
| rules/profiling.md | markdown | 3.9 KB |
| rules/streams.md | markdown | 5.1 KB |
| rules/stuck-processes-and-tests.md | markdown | 3.9 KB |
| rules/testing.md | markdown | 4.4 KB |
| rules/typescript.md | markdown | 5.5 KB |
| tile.json | config | 1017 B |
rules/node-modules-exploration.md
View on GitHub---
name: node-modules-exploration
description: Navigating and analyzing node_modules directories
metadata:
tags: node, nodejs, npm, yarn, pnpm, dependencies, packages
---
# Exploring node_modules
## When to Explore node_modules
Explore node_modules when you need to:
- Find specific packages and their versions
- Analyze dependencies and dependency trees
- Examine package contents
- Investigate dependency conflicts
- Understand how a package works internally
## Core Techniques
### Finding Package Versions
```bash
# Check actual installed version
cat node_modules/fastify/package.json | grep '"version"'
# For scoped packages
cat node_modules/@fastify/cors/package.json | grep '"version"'
# List all versions with npm
npm ls fastify
```
### Navigating Directory Structure
```bash
# List package contents
ls node_modules/fastify/
# Find TypeScript definitions
ls node_modules/fastify/*.d.ts
ls node_modules/@types/node/
# Check main entry point
cat node_modules/fastify/package.json | grep '"main"\|"exports"'
```
### Understanding Package Manager Differences
**npm/yarn (node_modules hoisting):**
```
node_modules/
fastify/
pino/ # hoisted from fastify's dependencies
@fastify/cors/
```
**pnpm (content-addressable storage):**
```
node_modules/
.pnpm/
fastify@4.0.0/
node_modules/
fastify/
pino/ # symlinked, not hoisted
fastify -> .pnpm/fastify@4.0.0/node_modules/fastify
```
## Finding Package READMEs
**CRITICAL: Never use `find`, `grep`, or `rg` for locating READMEs. Follow this sequence:**
1. **Direct Read attempts (try in order):**
```
node_modules/[package-name]/README.md
node_modules/[package-name]/readme.md
node_modules/[package-name]/README
```
For scoped packages: `node_modules/@scope/package-name/README.md`
2. **If not found, list directory contents:**
```bash
ls node_modules/[package-name]/
```
Look for README files in output, then read the exact filename.
3. **Alternative locations:**
```
node_modules/[package-name]/docs/README.md
```
Or check `readme` field in `package.json`.
## Analyzing Dependency Trees
```bash
# See why a package is installed
npm why lodash
# Full dependency tree
npm ls --all
# Only production dependencies
npm ls --prod
# Find duplicates
npm ls --all 2>&1 | grep -E "^\s+.*@[0-9]" | sort | uniq -d
```
## Investigating Conflicts
### Peer Dependency Issues
```bash
# Check peer dependencies
cat node_modules/some-plugin/package.json | grep -A 10 '"peerDependencies"'
# See what's actually installed vs. what's expected
npm ls react
```
### Duplicate Packages
When the same package appears multiple times:
```bash
# Find all instances of a package
find node_modules -name "package.json" -path "*/lodash/*" 2>/dev/null
# Check for version mismatches
npm ls lodash
```
## Examining Package Internals
### Entry Points
```bash
# Check exports field (modern)
node -e "console.log(JSON.stringify(require('./node_modules/fastify/package.json').exports, null, 2))"
# Check main field (legacy)
cat node_modules/fastify/package.json | grep '"main"'
```
### TypeScript Definitions
```bash
# Find type definitions
ls node_modules/fastify/*.d.ts
cat node_modules/fastify/package.json | grep '"types"\|"typings"'
# For DefinitelyTyped packages
ls node_modules/@types/
```
### Source Files
```bash
# Examine source structure
ls node_modules/fastify/lib/
head -50 node_modules/fastify/lib/server.js
```
## Debugging Module Resolution
```bash
# See how Node.js resolves a module
node -e "console.log(require.resolve('fastify'))"
# With full resolution paths
node --print "require.resolve.paths('fastify')"
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |