npm-helper

What this skill does

# NPM Package Management Assistant Skill

NPM and Node.js package management, project configuration, and dependency troubleshooting.

## Instructions

You are a Node.js and NPM ecosystem expert. When invoked:

1. **Package Management**:
   - Install and manage npm packages
   - Handle package.json configuration
   - Manage lock files (package-lock.json)
   - Use npm, yarn, or pnpm effectively
   - Configure workspaces and monorepos

2. **Project Setup**:
   - Initialize new Node.js projects
   - Configure scripts and lifecycle hooks
   - Set up project structure
   - Configure development tools
   - Manage multiple package managers

3. **Dependency Management**:
   - Handle version ranges and semver
   - Resolve dependency conflicts
   - Audit for security vulnerabilities
   - Update dependencies safely
   - Manage peer dependencies

4. **Troubleshooting**:
   - Fix module resolution errors
   - Resolve version conflicts
   - Debug installation issues
   - Clear cache and rebuild
   - Handle platform-specific issues

5. **Best Practices**: Provide guidance on package management, versioning, security, and performance optimization

## Package Manager Comparison

### npm (Default)
```bash
# Pros: Default in Node.js, widely supported
# Cons: Slower than alternatives

# Initialize project
npm init
npm init -y  # Skip prompts

# Install dependencies
npm install express
npm install --save-dev jest

# Install all dependencies
npm install

# Update dependencies
npm update
npm update express

# Remove package
npm uninstall express

# Run scripts
npm run build
npm test  # Shorthand for npm run test
npm start  # Shorthand for npm run start

# List installed packages
npm list
npm list --depth=0  # Only top-level

# Check for outdated packages
npm outdated
```

### Yarn (v1 Classic)
```bash
# Pros: Faster, better UX, workspaces
# Cons: Extra tool to install

# Install Yarn
npm install -g yarn

# Initialize project
yarn init
yarn init -y

# Install dependencies
yarn add express
yarn add --dev jest

# Install all dependencies
yarn install
yarn  # Shorthand

# Update dependencies
yarn upgrade
yarn upgrade express

# Remove package
yarn remove express

# Run scripts
yarn build
yarn test
yarn start

# List installed packages
yarn list
yarn list --depth=0

# Check for outdated packages
yarn outdated

# Interactive upgrade
yarn upgrade-interactive
```

### pnpm (Fast & Efficient)
```bash
# Pros: Fastest, disk space efficient, strict
# Cons: Less common, some compatibility issues

# Install pnpm
npm install -g pnpm

# Initialize project
pnpm init

# Install dependencies
pnpm add express
pnpm add -D jest

# Install all dependencies
pnpm install

# Update dependencies
pnpm update
pnpm update express

# Remove package
pnpm remove express

# Run scripts
pnpm build
pnpm test
pnpm start

# List installed packages
pnpm list
pnpm list --depth=0

# Check for outdated packages
pnpm outdated
```

### Yarn v3 (Berry)
```bash
# Pros: Zero-installs, Plug'n'Play, smaller size
# Cons: Different from v1, migration needed

# Enable Yarn Berry
yarn set version berry

# Install dependencies
yarn add express
yarn add -D jest

# Use Plug'n'Play (default in v3)
# No node_modules folder

# Or use node_modules
echo "nodeLinker: node-modules" >> .yarnrc.yml

# Zero-installs (commit .yarn/cache)
echo "enableGlobalCache: false" >> .yarnrc.yml
```

## Usage Examples

```
@npm-helper
@npm-helper --init-project
@npm-helper --fix-dependencies
@npm-helper --audit-security
@npm-helper --migrate-to-pnpm
@npm-helper --troubleshoot
```

## Project Initialization

### Basic Project Setup
```bash
# Initialize package.json
npm init -y

# Install common dependencies
npm install express dotenv

# Install dev dependencies
npm install --save-dev \
  nodemon \
  eslint \
  prettier \
  jest \
  @types/node \
  typescript

# Create basic structure
mkdir -p src tests
touch src/index.js tests/index.test.js

# Create .gitignore
cat > .gitignore << EOF
node_modules/
.env
.env.local
dist/
build/
coverage/
.DS_Store
*.log
EOF

# Create .nvmrc for Node version
node -v > .nvmrc
```

### TypeScript Project Setup
```bash
# Initialize project
npm init -y

# Install TypeScript and types
npm install --save-dev \
  typescript \
  @types/node \
  @types/express \
  ts-node \
  nodemon

# Initialize TypeScript
npx tsc --init

# Configure tsconfig.json
cat > tsconfig.json << EOF
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "moduleResolution": "node",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
EOF

# Update package.json scripts
npm pkg set scripts.build="tsc"
npm pkg set scripts.dev="nodemon src/index.ts"
npm pkg set scripts.start="node dist/index.js"
```

### Modern ESM Project Setup
```json
{
  "name": "my-esm-project",
  "version": "1.0.0",
  "type": "module",
  "main": "dist/index.js",
  "scripts": {
    "dev": "node --watch src/index.js",
    "build": "tsc",
    "start": "node dist/index.js",
    "test": "node --test"
  },
  "dependencies": {
    "express": "^4.18.2"
  },
  "devDependencies": {
    "@types/node": "^20.10.0",
    "typescript": "^5.3.0"
  }
}
```

## package.json Configuration

### Essential Fields
```json
{
  "name": "my-package",
  "version": "1.0.0",
  "description": "A helpful package",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "type": "module",
  "engines": {
    "node": ">=18.0.0",
    "npm": ">=9.0.0"
  },
  "scripts": {
    "dev": "nodemon src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js",
    "test": "jest",
    "test:watch": "jest --watch",
    "test:coverage": "jest --coverage",
    "lint": "eslint src/**/*.ts",
    "lint:fix": "eslint src/**/*.ts --fix",
    "format": "prettier --write \"src/**/*.ts\"",
    "typecheck": "tsc --noEmit",
    "prepare": "husky install",
    "prepublishOnly": "npm run build && npm test"
  },
  "keywords": ["node", "javascript", "helper"],
  "author": "Your Name <[email protected]>",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/user/repo.git"
  },
  "bugs": {
    "url": "https://github.com/user/repo/issues"
  },
  "homepage": "https://github.com/user/repo#readme"
}
```

### Dependency Types
```json
{
  "dependencies": {
    "express": "^4.18.2",
    "dotenv": "^16.3.1"
  },
  "devDependencies": {
    "typescript": "^5.3.0",
    "jest": "^29.7.0",
    "eslint": "^8.55.0",
    "prettier": "^3.1.0"
  },
  "peerDependencies": {
    "react": ">=16.8.0"
  },
  "peerDependenciesMeta": {
    "react": {
      "optional": true
    }
  },
  "optionalDependencies": {
    "fsevents": "^2.3.3"
  },
  "bundledDependencies": [
    "internal-package"
  ]
}
```

### Scripts Best Practices
```json
{
  "scripts": {
    "// Development": "",
    "dev": "nodemon src/index.ts",
    "dev:debug": "nodemon --inspect src/index.ts",

    "// Building": "",
    "build": "npm run clean && tsc",
    "clean": "rm -rf dist",
    "prebuild": "npm run lint",
    "postbuild": "echo 'Build complete!'",

    "// Testing": "",
    "test": "jest",
    "test:unit": "jest --testPathPattern=unit",
    "test:integration": "jest --testPathPattern=integration",
    "test:e2e": "jest --testPathPattern=e2e",
    "test:watch": "jest --watch",
    "test:coverage": "jest --coverage",

    "// Linting & Formatting": "",
    "lint": "eslint . --ext .ts,.js",
    "lint:fix": "eslint . --ext .ts,.js --fix",
    "format": "prettier --write \"src/**/*.{ts,js,json}\"",
    "format:check": "prettier --check \"src/**/*.{ts,js,json}\"",

    "// Type Checking": "",
    "typecheck": "tsc --noEmit",
    "typecheck:watch": "tsc --noEmit --watch",

    "// Combined": "",
    "validate": "npm run lint &&