First npm Package

Practical guide to create, test, and publish your first npm package with safe defaults.

Published on 2/26/2026

Initialize Package

Create package metadata correctly before writing code.

Anchor	Content	Source
npm init	Generate package.json interactively in the package root.
npm init --scope=@your-scope	Initialize a scoped package name like @your-scope/my-package.
name + version are mandatory for publish	Set unique lowercase package name and semver version in package.json.
start at version 1.0.0	Use semantic versioning; npm docs recommend starting public modules at 1.0.0.
license field	Use an SPDX identifier (for example, MIT) so users know reuse terms.

Make sure consumers can import your package predictably.

Anchor	Content	Details	Source
"main": "./index.js"	Classic entry point used by require() and older toolchains.	-
"exports": "./index.js"	Modern entry point map; preferred for new packages and controls public surface.
"type": "module"	Treat .js files as ESM; use when your package uses import/export syntax.	-
CommonJS starter file	Use module.exports in index.js if you want require('your-package') compatibility by default.		-
ESM starter file	Use named/default exports in index.js when type is module.		-

Verify exactly what will ship and that install/import works.

Anchor	Content	Details
npm pack --dry-run	Preview files included in the tarball before publishing.	-
"files" in package.json	Whitelist only distributable files (for example, dist and README) to avoid publishing junk.	-
.npmignore vs .gitignore	If .npmignore exists, npm uses it; otherwise npm falls back to .gitignore rules.	-
Test from a separate folder	Create a new directory, install your package there, and run a tiny test script.
README and LICENSE are always included	Even with files rules, key metadata files are auto-included by npm pack/publish.	-

Publish safely and avoid common first-release mistakes.

Anchor	Content	Source
npm login + npm whoami	Authenticate and confirm the account that will publish the package.
2FA or granular access token required	Publishing requires account 2FA enabled or a granular token with bypass-2FA publishing rights.
npm publish	Publish current package directory to npm registry.
npm publish --access public	Required for first publish of a scoped package you want to be public.
name@version is immutable	After publish, you cannot reuse the same package name and version, even if unpublished later.
npm version patch && npm publish	For fixes after first release, bump version before republishing.