Shell Integration & Transparent Aliases

Overview

FNPM’s transparent alias system is a game-changer that allows you to use your favorite package manager commands while FNPM handles everything behind the scenes. No more switching between tools or learning new commands!

Quick Setup

The fastest way to get started with transparent aliases:

# 1. Setup FNPM with your preferred package manager
fnpm setup pnpm

# 2. Add to your shell profile
echo 'eval "$(fnpm source)"' >> ~/.zshrc

# 3. Reload your shell
source ~/.zshrc

# 4. Use your package manager as usual!
pnpm install

Detailed Configuration

Step 1: Initialize FNPM Hooks

With Package Manager

# Setup with specific package manager
fnpm setup npm     # For npm users
fnpm setup yarn    # For yarn users
fnpm setup pnpm    # For pnpm users
fnpm setup bun     # For bun users

Interactive Setup

# Interactive setup - choose your package manager
fnpm setup

Without Hooks

# Setup without creating hooks (manual FNPM usage)
fnpm setup --no-hooks

Step 2: Shell Profile Configuration

Choose your shell and follow the appropriate configuration:

Zsh (macOS default)

# Add to ~/.zshrc
echo 'eval "$(fnpm source)"' >> ~/.zshrc

# Reload configuration
source ~/.zshrc

# Or restart your terminal
exec zsh

Bash

# Add to ~/.bashrc (Linux) or ~/.bash_profile (macOS)
echo 'eval "$(fnpm source)"' >> ~/.bashrc

# Reload configuration
source ~/.bashrc

# Or restart your terminal
exec bash

Fish

# Fish shell support
fnpm source --fish >> ~/.config/fish/config.fish

# Reload configuration
source ~/.config/fish/config.fish

Step 3: Verification

Test that everything is working correctly:

# Check FNPM status
fnpm hooks status

# Test transparent aliases
pnpm --help    # Should show FNPM interception message
npm install    # Should be handled by FNPM
yarn add lodash # Should be redirected to FNPM

How Transparent Aliases Work

Command Interception

When you type a package manager command, FNPM:

1. Detects if you’re in an FNPM-managed project (looks for .fnpm/ directory)
2. Intercepts the command before it reaches the original package manager
3. Maps the command to equivalent FNPM operations
4. Executes using FNPM’s optimized workflow
5. Provides familiar output and behavior

Command Mapping

Original Command	FNPM Equivalent	Description
npm install	fnpm install	Install all dependencies
yarn add pkg	fnpm add pkg	Add a new package
pnpm remove pkg	fnpm remove pkg	Remove a package
npm run script	fnpm run script	Run a package.json script
yarn upgrade	fnpm update	Update packages

Bypass Mechanisms

Sometimes you need to use the original package manager. Here’s how:

# Use full path to bypass FNPM
$(which pnpm) install

# Temporarily disable FNPM hooks
FNPM_DISABLE=1 pnpm install

# Use original command in non-FNPM projects
# (hooks only work in directories with .fnpm/ folder)

Advanced Configuration

Project-Specific Setup

You can have different configurations per project:

# Project A - uses npm aliases
cd ~/project-a
fnpm setup npm

# Project B - uses pnpm aliases
cd ~/project-b
fnpm setup pnpm

Global vs Local Hooks

Hook Scope

FNPM hooks only activate in directories that contain a .fnpm/ folder. This means you can safely have FNPM installed globally while only specific projects use the transparent aliases.

Managing Multiple Package Managers

# Check which hooks are active
fnpm hooks status

# Create hooks for multiple package managers
fnpm hooks create npm yarn pnpm

# Remove specific hooks
fnpm hooks remove yarn

# Remove all hooks
fnpm hooks remove --all

Troubleshooting

Common Issues

Hooks not working after setup:

# Make sure you've sourced your shell profile
source ~/.zshrc  # or ~/.bashrc

# Check if FNPM is in your PATH
which fnpm

# Verify hooks exist
ls -la .fnpm/

Commands still using original package manager:

# Check if you're in an FNPM project
fnpm status

# Verify shell integration
echo $FNPM_HOOKS_ENABLED

# Re-source the setup
source .fnpm/setup.sh

Shell errors on startup:

# Check for syntax errors in your shell profile
zsh -n ~/.zshrc  # for zsh
bash -n ~/.bashrc  # for bash

# Remove and re-add FNPM integration
# Remove the line: eval "$(fnpm source)"
# Then add it back: echo 'eval "$(fnpm source)"' >> ~/.zshrc

Performance Considerations

The transparent alias system is designed to be lightweight:

• Minimal overhead: Hook detection adds ~1ms to command execution
• Smart caching: FNPM caches project detection for faster subsequent runs
• Lazy loading: Hooks only activate when needed

Debugging

Enable debug mode to see what’s happening:

# Enable debug output
export FNPM_DEBUG=1

# Run a command to see the interception process
pnpm install

# Disable debug output
unset FNPM_DEBUG

Best Practices

Team Adoption

1. Document the setup: Share this guide with your team
2. Add to onboarding: Include FNPM setup in new developer documentation
3. Use in CI/CD: FNPM works great in automated environments
4. Be patient: Give team members time to adjust to the new workflow

Shell Profile Management

# Keep your shell profile organized
# Add this section to ~/.zshrc or ~/.bashrc:

# === FNPM Configuration ===
eval "$(fnpm source)"
# === End FNPM Configuration ===

Project Documentation

Add this to your project’s README:

## Package Management

This project uses FNPM for unified package management. After cloning:

1. Install FNPM: `curl -fsSL https://raw.githubusercontent.com/ideascoldigital/fnpm/main/install.sh | bash`
2. Setup project: `fnpm setup`
3. Configure shell: `echo 'eval "$(fnpm source)"' >> ~/.zshrc && source ~/.zshrc`
4. Use your preferred package manager: `npm install`, `yarn add pkg`, etc.

Next Steps

• Advanced Usage - Learn about FNPM’s advanced features
• Team Integration - Best practices for team workflows
• CI/CD Setup - Setting up FNPM in automated environments