How to fix npm ERR! code ETOOLARGE npm ERR! Package size exceeds maximum allowed size in npm

npmINTERMEDIATELOW

The ETOOLARGE error occurs when publishing an npm package that exceeds size limits. This usually happens when node_modules, test files, or large assets are accidentally included in the published package.

What this error means

This error indicates your npm package is too large for the registry to accept. Different registries have different limits: - npmjs.com: No explicit documented limit, but practical issues arise above 50MB - AWS CodeArtifact: 2 GB maximum - Azure Artifacts: 500 MB per package file - Private Verdaccio: Often defaults to 2 MB The most common cause is accidentally including files that shouldn't be published, like node_modules, test directories, or large assets.

How to fix "npm ERR! code ETOOLARGE npm ERR! Package size exceeds maximum allowed size"

1Diagnose what's being published

Check exactly what files will be included:

bash

# Preview files without publishing
npm pack --dry-run

# Create tarball locally to inspect
npm pack

# List tarball contents
tar -tzf my-package-1.0.0.tgz | head -50

# Check tarball size
ls -lh *.tgz

Look for node_modules/, test/, coverage/, or large files that shouldn't be included.

2Use the files field in package.json (recommended)

Whitelist only the files you want to publish:

json

{
  "name": "my-package",
  "version": "1.0.0",
  "files": [
    "dist/",
    "lib/",
    "index.js"
  ]
}

This is the safest approach—only explicitly listed files are published.

Automatically included (no need to list):
- package.json
- README (any case)
- LICENSE/LICENCE
- CHANGELOG

3Create .npmignore file (alternative approach)

Create .npmignore to exclude files:

bash

# .npmignore

# Version control
.git
.gitignore

# Dependencies (auto-ignored but explicit)
node_modules/

# Testing
test/
__tests__/
*.test.js
coverage/

# Development
.env
.vscode/
tsconfig.json
webpack.config.js

# Source maps
*.map

# CI/CD
.github/
.travis.yml

Important: When .npmignore exists, .gitignore is completely ignored for publishing.

4Verify package contents

After configuring, verify the package is now smaller:

bash

# Create tarball
npm pack

# Check file count
tar -tzf *.tgz | wc -l

# Check size
ls -lh *.tgz

# Extract and inspect
tar -xzf *.tgz
ls -la package/

A typical library should be under 1MB packed.

5Exclude source maps if building

If your package includes compiled/minified code, exclude source maps:

json

{
  "files": [
    "dist/index.js",
    "dist/index.d.ts"
  ]
}

Or in .npmignore:

bash

*.map

Source maps can be larger than the actual code.

6Use prepublishOnly to verify size

Add a script to check package size before every publish:

json

{
  "scripts": {
    "prepublishOnly": "npm pack --dry-run && npm run build"
  }
}

For automated size monitoring, use size-limit:

bash

npm install --save-dev size-limit @size-limit/file

json

{
  "size-limit": [
    {
      "path": "dist/index.js",
      "limit": "100 KB"
    }
  ]
}

How to fix npm ERR! code ETOOLARGE npm ERR! Package size exceeds maximum allowed size in npm

What this error means

Typical symptoms

Common causes

How to fix "npm ERR! code ETOOLARGE npm ERR! Package size exceeds maximum allowed size"

Advanced notes

Related errors

Official resources & further reading