@pamfilico/javascript-utils

JavaScript utilities for component analysis and dead code management in React/Next.js projects.

Features

• Component Usage Analyzer: Automatically scans your codebase to find where React/Next.js components are imported and used
• Dead Component Mover: Identifies unused components (Usage Count: 0) and moves them to a dead/ folder for cleanup
• Automatic Script Injection: Adds npm scripts to your project's package.json on installation

Installation

npm install @pamfilico/javascript-utils

Setup Scripts

The package attempts to automatically add npm scripts during installation. If the automatic setup doesn't work (common with --legacy-peer-deps), run the init command:

npx javascript-utils-init

This will add two scripts to your package.json:

{
  "scripts": {
    "component-usage": "component-usage-analyzer",
    "move-dead-components": "move-dead-components"
  }
}

Recommended installation command:

npm install @pamfilico/javascript-utils && npx javascript-utils-init

Usage

Component Usage Analyzer

Analyzes all components in src/components/ (root level only) and adds usage comments to the top of each file:

npm run component-usage

What it does:

• Scans all .tsx and .ts files in src/components/ (excluding subdirectories)
• Searches for imports across your entire src/ directory
• Adds a comment block at the top of each component with usage information
• Detects both production usage and Storybook stories
• Uses exact identifier matching (no false positives from substring matches)

Example output in component file:

// START: COMPONENT USAGE TOOL
// Usage Count: 3
//
// Used in:
// - app/[locale]/dashboard/page.tsx:15
// - components/TimelineComponent.tsx:42
//
// Storybook stories:
// - components/MyComponent.stories.tsx:10
// END: COMPONENT USAGE TOOL

import React from 'react';
// ... rest of component

Move Dead Components

Moves components with Usage Count: 0 to src/components/dead/ folder:

npm run move-dead-components

What it does:

• Reads the usage comment added by component-usage-analyzer
• Identifies components with Usage Count: 0
• Moves them to src/components/dead/ folder
• Skips files that already exist in the dead folder
• Provides a summary of moved components

Workflow:

# Step 1: Analyze component usage
npm run component-usage

# Step 2: Review the unused components list in the terminal

# Step 3: Move unused components to dead folder
npm run move-dead-components

How It Works

Component Detection

The analyzer:

1. Only scans root-level components in src/components/ (ignores subdirectories like aade/, locale/, etc.)
2. Searches all files in src/ for imports
3. Matches imports by:
   • Exact path matching (@/components/ComponentName)
   • Relative path resolution (./ComponentName, ../../components/ComponentName)
   • Exact identifier matching in named imports (no substring matching)

Import Matching Examples

✅ Detected:

import MyComponent from "@/components/MyComponent";
import { MyComponent } from "@/components/MyComponent";
import MyComponent from "./MyComponent";  // same folder
import MyComponent from "../../../../components/MyComponent";  // relative path

❌ Not detected (different component):

import MyComponentVariant1 from "@/components/MyComponentVariant1";
// Won't match "MyComponent" because exact matching is used

Why Only Root-Level Components?

Subdirectories in components/ often contain organized feature modules (like aade/, locale/) where components import each other locally. These internal imports shouldn't be moved to the dead folder, so we only manage root-level components.

Project Structure Requirements

Your project must have:

your-project/
├── src/
│   ├── components/  (this is what gets scanned)
│   │   ├── Component1.tsx
│   │   ├── Component2.tsx
│   │   ├── dead/  (created automatically if needed)
│   │   └── aade/  (subdirectories are ignored)
│   └── app/  (or pages/, or other directories - all searched for imports)
└── package.json

Configuration

Currently, the tools use these defaults:

• Components directory: src/components/
• Source directory: src/
• Dead folder: src/components/dead/

These are hardcoded but can be made configurable in future versions.

Tips & Best Practices

1. Run component-usage frequently to keep usage comments up to date
2. Review unused components before moving them - some might be new features in development
3. Keep the dead folder in version control as a backup before permanent deletion
4. Re-run component-usage after major refactoring to catch newly unused components

Troubleshooting

"Components directory not found"

Make sure you're running the scripts from your project root and you have a src/components/ directory.

Scripts not added to package.json

The postinstall script may not run automatically when using --legacy-peer-deps or --force flags.

Solution 1: Run the init command

npx javascript-utils-init

Solution 2: Manually run postinstall

node node_modules/@pamfilico/javascript-utils/scripts/postinstall.js

Solution 3: Manually add scripts to package.json

{
  "scripts": {
    "component-usage": "component-usage-analyzer",
    "move-dead-components": "move-dead-components"
  }
}

False positives in usage detection

If you see components marked as used when they're not, or vice versa, please check:

• The component name matches the filename exactly
• Imports use exact identifier names (we fixed substring matching issues)
• Relative imports resolve correctly

Development

Package Structure

@pamfilico/javascript-utils/
├── package.json
├── README.md
├── bin/
│   ├── component-usage-analyzer.js
│   └── move-dead-components.js
└── scripts/
    └── postinstall.js

Local Testing

To test locally before publishing:

# In the package directory
npm link

# In your project directory
npm link @pamfilico/javascript-utils

# Run the scripts
npm run component-usage
npm run move-dead-components

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

MIT

Author

Pamfilico

Repository

https://github.com/pamfilico/javascript-utils

Note: This package modifies your package.json during installation to add npm scripts. If you're using this in a CI environment, set the CI=true environment variable to skip script injection.

Publishing (for maintainers)

This package is published to the public npm registry.

Prerequisites

1. You must be logged in to npm: npm login
2. You must have publish access to the @pamfilico scope

Manual Publishing

# Make your changes and commit them
git add .
git commit -m "feat: your changes"

# Run the release script (bumps version, commits, tags, pushes, and publishes)
./deploy.sh

# Or with a custom message
./deploy.sh -m "feat: added new feature %s"

The deploy.sh script will:

1. Bump the patch version in package.json
2. Create a git commit with the version
3. Create a git tag (e.g., v1.0.1)
4. Push commits and tags to GitHub
5. Publish the package to npm

First-Time Setup

If you haven't published the package yet:

# Login to npm
npm login

# Publish for the first time
npm publish --access public