npmglobalize

Transform file: dependencies to npm versions for publishing.

Overview

npmglobalize automates the workflow of publishing npm packages that use local file: references during development. It converts those references to proper npm versions, publishes everything in dependency order, and optionally restores the local references afterward.

Installation

npm install -g @bobfrankston/npmglobalize

Basic Usage

cd your-package
npmglobalize              # Transform + publish (patch version)
npmglobalize --minor      # Bump minor version
npmglobalize --major      # Bump major version

# Or run from anywhere with a path
npmglobalize y:\path\to\your-package

Key Features

🔗 Automatic Dependency Publishing (Default)

By default, npmglobalize ensures all file: dependencies are published before converting them:

npmglobalize              # Auto-publishes file: deps in correct order

If you have:

lxtest
├── file:../lxlan-node
│   └── file:../lxland
└── file:../lxland

It automatically:

1. Publishes lxland (root dependency)
2. Publishes lxlan-node (depends on lxlan)
3. Converts and publishes lxtest

Settings Propagation (Default Behavior): When publishing file: dependencies, these settings are automatically inherited:

• --update-deps / --update-major (update dependencies)
• --fix (run npm audit fix)
• --conform (fix .gitignore/.npmignore/.gitattributes and git config)
• --verbose / --quiet
• --force / --files

⚠️ Visibility Settings (Smart Inheritance):

• --npmVisibility is only inherited by NEW repositories (never published to npm before)
• Existing repositories keep their current npm visibility (public/private) unchanged
• --gitVisibility is inherited by all dependencies

This ensures you can safely set --npmVisibility private as a default for new packages without accidentally changing the visibility of your existing published packages.

Why This Matters: Once a package is published to npm (public or private), changing its visibility later requires careful consideration. This smart inheritance protects your existing packages while making new ones default to safe settings.

Example - safely publish with new packages private by default:

npmglobalize --npmVisibility private
# ✓ Existing npm packages: keep their current visibility
# ✓ New packages (never published): default to private (safe!)
# ✓ Regular npm dependencies (express, etc.): unchanged

Example with configuration file (recommended):

# In main package: create .globalize.json5 with "npmVisibility": "private"
npmglobalize
# ✓ Existing repos: publish with their current npm visibility
# ✓ Brand new repos: inherit private setting

Skip auto-publishing (use with caution):

npmglobalize -npd         # --no-publish-deps

Force republish all file: dependencies even if versions exist:

npmglobalize --force-publish

📦 Dependency Updates

Safe updates (minor/patch only, respects semver):

npmglobalize --update-deps

• express ^4.18.0 → ^4.21.0 ✓
• lodash ^4.17.0 → ^4.17.21 ✓
• Won't update to express ^5.0.0 (breaking change)

Include major updates (breaking changes):

npmglobalize --update-major

• Updates to latest including major versions
• Shows "(MAJOR)" indicator for breaking changes

Note: The --update-deps flag propagates to all file: dependencies, so one command updates your entire dependency tree.

🔒 Security Auditing

Check vulnerabilities:

npmglobalize              # Shows audit at end

Auto-fix vulnerabilities:

npmglobalize --fix        # Runs npm audit fix

Disable audit:

npmglobalize --no-fix

🔄 File Reference Management

Default behavior (restore file: references after publish):

npmglobalize              # Converts file: → npm, publishes, then restores file:

Keep npm references permanently:

npmglobalize --nofiles    # Don't restore file: references

Just transform without publishing:

npmglobalize -np          # --nopublish (formerly --apply)

Restore from backup:

npmglobalize --cleanup    # Restore original file: references

🔧 Git Integration & Error Recovery

Automatic tag conflict resolution:

npmglobalize --fix-tags   # Auto-fix version/tag mismatches

When a previous publish fails, git tags may conflict with package.json version. The --fix-tags option (or automatic detection) will clean up these conflicts.

Automatic rebase when local is behind remote:

npmglobalize --rebase     # Auto-rebase if behind remote

For single-developer projects, this safely pulls remote changes before publishing.

Note: This tool is designed for single-developer, single-branch workflows where automatic rebase and tag cleanup are safe operations.

📂 Git Repository Setup

When initializing a new repository with --init, npmglobalize automatically sets up:

File structure (per programming.md standards):

• .gitignore - Node.js best practices (node_modules, secrets, certificates, etc.)
• .npmignore - Publishing filters (excludes .git, tests, source files, etc.)
• .gitattributes - Forces LF line endings for all text files

Git configuration (ensures cross-platform compatibility):

git config core.autocrlf false  # Disable CRLF conversion
git config core.eol lf          # Force LF line endings

This ensures consistent line endings across Windows, macOS, and Linux, preventing "modified file" issues caused by line ending differences.

🔍 Understanding "Detached HEAD" Error

What is Detached HEAD? Your git repository is not currently on a branch (like master or main). This happens when you:

• Check out a specific commit: git checkout abc123
• Check out a tag: git checkout v1.0.0
• Have some git operations leave you in this state

Why does it matter? Publishing requires being on a branch so commits and tags can be properly tracked in your repository history.

Common scenarios:

1. Just fixing files with --conform:

   npmglobalize --conform   # ✓ Files get fixed, then exits with helpful message

   The files are already updated! You don't need to run it again.

2. Want to publish (have commits to keep):

   git checkout -B master   # Moves master branch to current commit (merges)
   npmglobalize            # Now works normally

   The -B flag moves your branch pointer to include the detached commits.

3. Want to publish (no commits made, safe to discard):

   git checkout master      # Just switch back to branch
   npmglobalize            # Now works normally

4. Force publish anyway (not recommended):

   npmglobalize --force    # Proceeds despite detached HEAD

   Warning: Commits may be hard to track later.

Command Reference

Release Options

--patch         Bump patch version (default: 1.0.0 → 1.0.1)
--minor         Bump minor version (1.0.0 → 1.1.0)
--major         Bump major version (1.0.0 → 2.0.0)
--nopublish, -np  Just transform, don't publish
--cleanup       Restore file: dependencies from backup

Dependency Options

--update-deps      Update package.json to latest versions (safe: minor/patch)
--update-major     Allow major version updates (breaking changes)
--no-publish-deps, -npd  Skip auto-publishing file: dependencies
--force-publish    Republish dependencies even if version exists
--fix              Run npm audit fix after transformation
--no-fix           Don't run npm audit

Install Options

--install, -i   Install globally after publish (Windows)
--wsl           Also install in WSL

Mode Options

--files         Keep file: paths after publish (default)
--nofiles       Keep npm versions permanently

Git/npm Visibility

--git private   Make git repo private (default)
--git public    Make git repo public
--npm private   Mark package private (skip publish) (default)
--npm public    Publish to npm

Other Options

--init          Initialize git/npm if needed (creates .gitignore, .npmignore, 
                .gitattributes, and configures git for LF line endings)
--force         Continue despite git errors
--dry-run       Preview what would happen
--quiet         Suppress npm warnings (default)
--verbose       Show detailed output
--conform       Update .gitignore/.npmignore/.gitattributes to best practices
                and configure git for LF line endings (fixes existing repos)
--asis          Skip ignore file checks
--fix-tags      Automatically fix version/tag mismatches
--rebase        Automatically rebase if local is behind remote
--help, -h      Show help
--version, -v   Show version

Configuration File

Settings can be saved in .globalize.json5:

{
  // npmglobalize configuration (JSON5 format)
  "bump": "patch",           // Version bump type
  "install": true,           // Auto-install globally
  "wsl": false,              // Also install in WSL
  "fix": true,               // Auto-run npm audit fix
  "verbose": false,          // Show detailed output
  "gitVisibility": "private",
  "npmVisibility": "public"
}

Configuration persists across runs. CLI flags override config file.

Common Workflows

Standard Release

npmglobalize --install    # Publish + install globally

Release with Dependency Chain

cd my-app                  # Has file: deps
npmglobalize              # Publishes all deps automatically

Safe Dependency Updates

npmglobalize --update-deps  # Update to latest safe versions

Security Fixes

npmglobalize --fix         # Fix vulnerabilities + release

Force Update Everything

npmglobalize --force-publish --update-major

Preview Changes

npmglobalize --dry-run     # See what would happen

How It Works

1. Validates package.json and git status
2. Updates dependencies (if --update-deps)
3. Publishes file: dependencies (if needed)
4. Backs up original file: references to .dependencies
5. Converts file: → npm version references
6. Commits changes
7. Bumps version (using npm version)
8. Publishes to npm
9. Pushes to git
10. Installs globally (if --install)
11. Restores file: references (if --files, default)
12. Runs audit (shows security status)

Version Checking

When publishing file: dependencies, checks if each version exists on npm:

• ✅ Exists → Skip, use existing version
• ❌ Missing → Publish it first
• 🔄 Force → Use --force-publish to republish

Examples

# Basic release
npmglobalize

# Run on a different project
npmglobalize y:\dev\myproject

# Auto-fix tag conflicts and rebase
npmglobalize --fix-tags --rebase

# Release with updates and security fixes
npmglobalize --update-deps --fix

# Just update package.json, don't publish
npmglobalize -np --update-deps

# Force republish all dependencies
npmglobalize --force-publish --update-major

# Release + install on Windows and WSL
npmglobalize --install --wsl

# Restore original file: references
npmglobalize --cleanup

# Preview what would happen
npmglobalize --dry-run --verbose

Authentication

Requires npm authentication:

npm login

Check authentication:

npm whoami

Development

Build Check

npmglobalize includes automatic build verification to ensure TypeScript files are compiled before execution. This prevents runtime errors from outdated JavaScript files.

How it works:

• When you run npmglobalize, it automatically checks if .js files are newer than their .ts sources
• If .js files are missing or outdated, execution stops with an error
• The check is skipped if noEmit: true is set in tsconfig.json

Building the project:

npm run build     # Compile TypeScript files
npm run watch     # Watch mode for development
npm run check     # Manually verify build status

Bypassing the check:

npmglobalize --force    # Skip build check (not recommended)

Error example:

❌ Error: TypeScript files not compiled
cli.js is older than cli.ts

Please run: npm run build
Or use --force to skip this check

This ensures you never accidentally run outdated code when the TypeScript source has changed.

License

MIT