Getting Started with FNPM

Installation

First things first, let’s get FNPM installed on your system. It’s as easy as pie (and less messy)!

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/ideascoldigital/fnpm/refs/heads/main/install.sh)"

Project Setup

Once FNPM is installed, you can set it up in your project. This is where the magic begins! 🪄

Basic Setup

fnpm setup

This command will prompt you to choose your preferred package manager (npm, yarn, or pnpm). Don’t worry - your choice won’t affect your teammates. That’s the whole point!

Transparent Alias System (New!)

FNPM now includes a revolutionary transparent alias system that lets you use your favorite package manager commands while FNPM does the heavy lifting behind the scenes.

fnpm setup pnpm

This creates hooks that intercept pnpm commands and redirect them to FNPM. You can specify any supported package manager: npm, yarn, pnpm, or bun.

Shell Integration Setup

After running fnpm setup, you need to configure your shell to enable the transparent alias system:

Automatic Setup (Recommended)

# Add FNPM to your shell profile automatically
echo 'eval "$(fnpm source)"' >> ~/.zshrc    # For zsh users
echo 'eval "$(fnpm source)"' >> ~/.bashrc   # For bash users

# Reload your shell
source ~/.zshrc    # or ~/.bashrc

Manual Setup

# 1. Source the setup script in your current session
source .fnpm/setup.sh

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

# 3. Reload your shell
exec $SHELL

One-time Session

# For testing or one-time use
source .fnpm/setup.sh

Verify Installation

Once configured, test that the transparent aliases are working:

# These commands will now be intercepted by FNPM
pnpm --help
npm install
yarn add lodash

# You should see a message like:
# 🔄 This pnpm command is intercepted by FNPM

Basic Commands

Installing Dependencies

To install all project dependencies:

fnpm install

To install a specific package:

fnpm install lodash
# or
fnpm add lodash

Running Scripts

To view all available scripts in your package.json:

fnpm run

To execute a specific script:

fnpm run <script-name>
# Example: fnpm run dev

Adding Dependencies

Add packages as dependencies with these commands:

Regular Dependencies

fnpm add lodash express axios

Dev Dependencies

fnpm add -D jest typescript @types/node

Global Packages

fnpm add -g typescript-language-server

Removing Dependencies

To remove packages:

fnpm remove lodash

How It Works

FNPM creates a unified workflow by:

1. Local Configuration: Creates a .fnpm directory in your project to store user-specific settings
2. Lock File Management: Maintains consistent lock files regardless of which package manager is used
3. Transparent Hook System: Intercepts package manager commands and redirects them to FNPM
4. Shell Integration: Sets up aliases that make the transition seamless and invisible

The Magic Behind Transparent Aliases

When you run fnpm setup <package-manager>, FNPM creates:

• Hook scripts in .fnpm/ directory that intercept commands
• Shell functions that override the original package manager commands
• Automatic detection of when you’re in an FNPM-managed project
• Fallback mechanisms to use original commands when needed

This means you can type pnpm install and FNPM will:

1. Detect the command
2. Map it to the appropriate FNPM operation
3. Execute with FNPM’s optimized workflow
4. Maintain your familiar CLI experience

Best Practices

For Teams

1. Exclude .fnpm from Version Control: Add .fnpm to your .gitignore as it contains user-specific preferences
2. Commit Lock Files: Always commit the generated lock files to maintain dependency consistency
3. Use CI/CD Integration: FNPM works seamlessly with CI/CD pipelines

For Developers

1. Use Your Preferred Tool: Feel free to use your favorite package manager - FNPM handles the rest
2. Trust the Process: Let FNPM manage lock files and dependency states
3. Keep It Updated: Regularly update FNPM to get the latest features and improvements

Common Questions

Why does FNPM exist?

Because life’s too short for package manager drama! FNPM lets developers use their preferred tools while maintaining project consistency.

Will it affect my existing projects?

Nope! FNPM works alongside your existing package manager setup. It just makes everything play nice together.

What about my CI/CD pipeline?

FNPM works great with CI/CD! It ensures consistent builds regardless of which package manager is used in the pipeline.

Next Steps

Now that you’re up and running with FNPM, check out these resources:

• Shell Integration - Complete guide to transparent aliases and shell configuration
• Transparent Aliases Announcement - Learn about the latest features and improvements
• Advanced Usage - Learn about advanced features and configurations
• Team Integration - Best practices for team workflows
• CI/CD Setup - Setting up FNPM in your CI/CD pipeline

Welcome to the peaceful world of package management! 🕊️