NPM Ignore File Format

What is an .npmignore file?

An .npmignore file is a configuration file used by the Node Package Manager (npm) to specify which files and directories should be excluded when publishing a package to the npm registry. It works similarly to a .gitignore file but specifically controls what gets included in the published npm package.

File Extensions

• .npmignore

MIME Type

• text/plain

History and Development

The .npmignore file was introduced early in npm's development as package authors needed a way to control which files were included in their published packages. This became essential as projects grew larger and contained many development files that weren't needed in the final distributed package.

Evolution

• 2010: Early npm versions introduced basic ignore functionality
• 2012: Standardized .npmignore format established
• 2014: Enhanced pattern matching and glob support
• Present: Continued refinement with modern JavaScript development practices

Purpose and Function

Primary Goals

• Reduce Package Size: Exclude unnecessary files from published packages
• Security: Prevent accidentally publishing sensitive files
• Clean Distribution: Ensure only relevant files reach end users
• Performance: Faster installation with smaller package sizes

Default Behavior

If no .npmignore file exists, npm falls back to using .gitignore. If neither exists, npm includes all files except those in its built-in ignore list.

Syntax and Patterns

Basic Syntax

The .npmignore file uses the same syntax as .gitignore:

# Comments start with #

# Ignore specific files
config.json
secret.key

# Ignore directories
node_modules/
build/
dist/

# Ignore file types
*.log
*.tmp
*.cache

# Ignore files in subdirectories
src/**/*.test.js
docs/**/*.md

# Negation patterns (include files that would otherwise be ignored)
!important.log
!dist/production/

Pattern Matching

• Wildcards: * matches any characters except /
• Double wildcards: ** matches any number of directories
• Question mark: ? matches any single character
• Brackets: [abc] matches any character in the set
• Negation: ! includes files that would otherwise be ignored

Common Patterns

# Development dependencies
node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# Build artifacts
build/
dist/
out/
*.tgz

# Testing
coverage/
.nyc_output/
test/
tests/
__tests__/
*.test.js
*.spec.js

# Documentation
docs/
*.md
!README.md

# IDE and editor files
.vscode/
.idea/
*.swp
*.swo
*~

# OS generated files
.DS_Store
.DS_Store?
._*
.Spotlight-V100
.Trashes
ehthumbs.db
Thumbs.db

# Environment files
.env
.env.local
.env.development.local
.env.test.local
.env.production.local

# Source maps
*.map

# TypeScript
*.tsbuildinfo
tsconfig.json

Built-in Npm Exclusions

Always Ignored

npm automatically ignores certain files regardless of .npmignore:

• .git/ directory
• CVS/ directory
• .svn/ directory
• .hg/ directory
• .lock-wscript
• .wafpickle-N
• *.orig
• .npmrc

Never Ignored

Some files are always included:

• package.json
• README (and variants)
• CHANGELOG (and variants)
• LICENSE (and variants)
• Main file specified in package.json

Package.json Integration

Files Field

An alternative to .npmignore is the files field in package.json:

{
  "name": "my-package",
  "version": "1.0.0",
  "files": [
    "lib/",
    "bin/",
    "README.md",
    "LICENSE"
  ]
}

Precedence

When both .npmignore and the files field exist:

1. files field takes precedence
2. .npmignore is ignored if files is present
3. Use one or the other, not both

Best Practices

Development vs. Production

Structure your .npmignore to exclude development-only files:

# Development tools
.babelrc
.eslintrc*
.prettierrc*
webpack.config.js
rollup.config.js

# Source files (if you publish built files)
src/
!lib/

# Development dependencies would be excluded by default
# (they're in devDependencies, not dependencies)

# Test files
test/
tests/
__tests__/
**/*.test.js
**/*.spec.js
coverage/

# Documentation (except README)
docs/
*.md
!README.md

# Configuration files
.env*
.travis.yml
.github/

Security Considerations

Ensure sensitive files are excluded:

# Secrets and keys
*.key
*.pem
*.p12
.env
.env.*
secrets.json
config/secrets.js

# Private configuration
private/
internal/
.secrets/

# Database files
*.db
*.sqlite
*.sqlite3

# Log files that might contain sensitive data
*.log
logs/

Common Scenarios

Library Development

For a JavaScript library:

# Source files (publish only built version)
src/
!lib/

# Build tools
webpack.config.js
rollup.config.js
.babelrc
tsconfig.json

# Development
test/
examples/
demo/
docs/

# Build artifacts to exclude
*.map
.tsbuildinfo

CLI Tool Package

For command-line tools:

# Development
test/
examples/
docs/
*.md
!README.md

# Source files if you build/transpile
src/
!bin/
!lib/

# Development configuration
.eslintrc*
.prettierrc*
nodemon.json

TypeScript Package

For TypeScript packages:

# Source TypeScript files (publish only compiled JS)
src/
*.ts
!*.d.ts
!lib/**/*.js
!lib/**/*.d.ts

# TypeScript configuration
tsconfig.json
tslint.json

# Build info
.tsbuildinfo

Tools and Validation

NPM Commands

# Preview what would be published
npm pack --dry-run

# See what files would be included
npm publish --dry-run

# Pack locally to inspect
npm pack
tar -tf package-name-1.0.0.tgz

# List files that would be published
npm ls --production --parseable

Third-party Tools

• npm-packlist: Preview files that would be included
• bundlesize: Check bundle size after packaging
• package-size: Analyze package size impact

Automation

#!/bin/bash
# Script to check package contents before publishing

echo "Files that will be published:"
npm pack --dry-run

echo -e "\nPackage size:"
npm pack
tar -tf *.tgz | wc -l
ls -lh *.tgz
rm *.tgz

echo -e "\nReady to publish? (y/n)"
read confirm
if [ "$confirm" = "y" ]; then
    npm publish
fi

Troubleshooting

Common Issues

1. Unintentionally including large files: Check for missing patterns
2. Excluding required files: Test with npm pack
3. Case sensitivity: Patterns may behave differently on different OS
4. Globbing issues: Test patterns with actual file structure

Debugging

# Create a test package to examine contents
npm pack
mkdir test-package
cd test-package
tar -xf ../package-name-1.0.0.tgz
ls -la package/

# Clean up
cd ..
rm -rf test-package
rm package-name-1.0.0.tgz

Performance Impact

Bundle Size Optimization

# Exclude source maps in production
*.map

# Exclude unminified versions if you provide minified
*.js
!*.min.js

# Exclude multiple language files if not needed
locales/
!locales/en.json

# Exclude large documentation
docs/
examples/
demo/

Installation Speed

Smaller packages install faster:

• Exclude unnecessary files
• Consider what consumers actually need
• Balance between package size and functionality

Integration with CI/CD

GitHub Actions Example

name: Publish Package
on:
  release:
    types: [created]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: '16'
          registry-url: 'https://registry.npmjs.org'
      
      - run: npm ci
      - run: npm test
      
      # Check what will be published
      - run: npm pack --dry-run
      
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

The .npmignore file is a crucial tool for maintaining clean, secure, and efficient npm packages. Proper configuration ensures that published packages contain only what's necessary, improving installation performance and reducing security risks.