Package.json Generator

Package.json: The Manifest Every Node Project Reads

Every Node.js project starts with package.json. It declares the project's name, version, dependencies, scripts, and dozens of optional fields that tools across the ecosystem consume. Get it right and your project integrates cleanly with npm/yarn/pnpm/bun, IDE tooling, CI/CD, bundlers, and consumers of your published code. Get it wrong and you'll get cryptic errors at install time, broken imports at runtime, and angry GitHub issues from users who can't figure out which entry point to import.

This generator scaffolds a clean starting point. After that, you'll likely add more fields as the project grows.

The Required and Near-Required Fields

name. Lowercase, URL-safe (a-z 0-9 - _ . / @). Scoped packages use @scope/name format. Avoid trademarked names. Avoid names too close to popular packages (typosquats look like attacks). Max 214 characters.

version. Semver: MAJOR.MINOR.PATCH (optionally plus pre-release like 1.0.0-beta.1). Start at 0.1.0 for pre-1.0 packages (some prefer 0.0.1); bump to 1.0.0 when you commit to a stable API. Every published version must be unique, npm forbids overwriting.

description. One sentence. Shown in npm search results, on the package's npmjs.com page, and in IDE tooltips. The most-read text in your package.

main (legacy) or exports (modern). What gets imported when consumers do require('your-pkg') or import 'your-pkg'.

license. SPDX identifier: MIT, Apache-2.0, BSD-3-Clause, etc. Use UNLICENSED for proprietary (npm interprets this specially to forbid publishing).

The Recommended Fields

author. Person or org. Format: "Name <email> (url)" or an object { name, email, url }.

repository. Where the source lives. { "type": "git", "url": "https://github.com/user/repo.git" }. npm uses this for the "view source" link on the package page; GitHub uses it to detect packages associated with the repo.

keywords. Array of strings for search discoverability on npm. Pick 5-10 relevant tags. ["react", "hook", "auth"].

homepage. Optional URL to the project's docs/landing page.

bugs. Where users should file issues. { "url": "https://github.com/user/repo/issues" }.

engines. Supported runtime versions. { "node": ">=18.0.0" }.

The exports Field (Modern Entry Points)

exports is the modern way to declare entry points. Supports conditional exports for different consumers:

This says:

• Importing your-pkg resolves based on consumer's environment (ESM vs CJS) and gets the right type definitions.
• Importing your-pkg/utils works as a subpath.
• The package.json itself is exported (some tools need to read it).
• Anything NOT listed in exports is not importable, exports effectively turns on strict encapsulation.

Strict encapsulation is a major change from the pre-exports era when consumers could reach into your package's internals. With exports, you control your public API.

Scripts: The Project's Verbs

Scripts are npm-runnable commands. npm run <name> executes them.

Convention-driven scripts get special treatment:

• start: npm start works without run.
• test: npm test works without run.
• prepublishOnly: runs before npm publish.
• postinstall: runs after dependencies install (use sparingly, security-sensitive).
• pre<script> / post<script>: lifecycle hooks before/after any other script.

Anti-patterns to avoid:

• postinstall scripts that compile native code. Slow installs, fragile across platforms.
• Scripts that depend on globally-installed CLIs. Use devDependencies and npx instead.
• Scripts that call other scripts via npm run. Adds overhead; use direct command composition.
• Scripts that depend on bash features. Windows users will hate you. Use cross-env for env vars, rimraf for delete, mkdirp for mkdir.

Dependency Fields

dependencies, runtime deps. Installed when consumers install your package.
devDependencies, build-time deps (TypeScript, test framework, bundler). NOT installed for consumers.
peerDependencies, deps your consumer must provide. Classic example: a React plugin depends on React but doesn't bundle it; consumers bring their own. npm 7+ auto-installs peers; older versions warn.
optionalDependencies, non-fatal deps. Install failures don't abort the install. Used for platform-specific natives.
bundledDependencies, deps to include in the published tarball directly. Almost never needed in modern packages.

Version ranges (the right side of "react": "^18.0.0"):

• ^1.2.3, compatible with 1.x.x where x.x >= 2.3 (caret).
• ~1.2.3, compatible with 1.2.x where x >= 3 (tilde).
• 1.2.3, exact.
• >=1.2.3, anything higher.
• *, any.

For libraries: caret on peers (you're flexible). For applications: exact via lockfile (you control upgrades).

Files: What Gets Published

files is an allowlist of paths to include when publishing. Without it, npm includes everything in the directory (minus a default block-list: .git, node_modules, etc.). With it, you publish only what consumers need:

This excludes source TypeScript, test files, configs, and other build artifacts. Smaller published tarball, less surface for consumers to depend on internals.

Always set files. Or use .npmignore (works like .gitignore but for npm). Or rely on files-equivalent fields in newer package configs. Just don't ship your whole repo.

Common Mistakes

• "version": "1.0.0" on day one. This commits you to semver from the start, meaning every API change is a major bump. Use 0.1.0 until the API is stable.
• "main" but no "exports" and no "types". Consumers using TypeScript get no types; tooling falls back to any.
• "type": "module" without configuring tests, build, scripts to handle ESM. Surprises everywhere.
• Including all dev deps in dependencies. Bloats every consumer's install.
• No "license". npm treats missing license as "ISC" by default, but this is often wrong. Be explicit.
• "private": true forgotten on internal repos. npm publishes anyway and your code is now public. Always set "private": true on non-publishable repos.

Privacy

JSON construction is pure string templating in your browser. The output is the only thing leaving via copy-paste, your inputs (project name, author info) stay in the tab. Open DevTools Network during use: zero outbound requests.