Essential package.json Fields
Beyond the basics, package.json supports many fields that help configure your project. Let's explore the most useful ones.
Project Information Fields
homepage
Link to your project's homepage:
{
"homepage": "https://my-project.com"
}
repository
Where your code lives:
{
"repository": {
"type": "git",
"url": "https://github.com/username/my-project.git"
}
}
Shorthand for GitHub:
{
"repository": "github:username/my-project"
}
bugs
Where to report issues:
{
"bugs": {
"url": "https://github.com/username/my-project/issues",
"email": "bugs@my-project.com"
}
}
funding
How to support the project:
{
"funding": {
"type": "patreon",
"url": "https://www.patreon.com/username"
}
}
Configuration Fields
type
Specify module system:
{
"type": "module"
}
| Value | Import Style |
|---|---|
"commonjs" (default) | require() |
"module" | import/export |
engines
Specify required Node.js version:
{
"engines": {
"node": ">=18.0.0",
"npm": ">=9.0.0"
}
}
This helps prevent compatibility issues.
private
Prevent accidental publishing:
{
"private": true
}
Essential for apps, internal tools, and monorepos.
workspaces
For monorepo projects:
{
"workspaces": [
"packages/*",
"apps/*"
]
}
Entry Point Fields
main
The primary entry point (CommonJS):
{
"main": "dist/index.js"
}
module
Entry point for ES modules (used by bundlers):
{
"module": "dist/index.mjs"
}
exports
Modern, flexible exports (Node.js 12+):
{
"exports": {
".": {
"import": "./dist/index.mjs",
"require": "./dist/index.cjs"
},
"./utils": {
"import": "./dist/utils.mjs",
"require": "./dist/utils.cjs"
}
}
}
bin
For CLI tools:
{
"bin": {
"my-cli": "./bin/cli.js"
}
}
Or for a single command:
{
"bin": "./bin/cli.js"
}
File Control Fields
files
Which files to include when publishing:
{
"files": [
"dist",
"src",
"README.md"
]
}
By default, npm includes most files. Use .npmignore to exclude files.
directories
Describe your project structure:
{
"directories": {
"lib": "src",
"test": "tests",
"doc": "docs"
}
}
Dependency Fields
peerDependencies
Packages that must be installed by the user:
{
"peerDependencies": {
"react": ">=17.0.0"
}
}
Common for plugins and libraries.
peerDependenciesMeta
Make peer dependencies optional:
{
"peerDependencies": {
"react": ">=17.0.0",
"vue": ">=3.0.0"
},
"peerDependenciesMeta": {
"vue": {
"optional": true
}
}
}
optionalDependencies
Dependencies that aren't required:
{
"optionalDependencies": {
"fsevents": "^2.3.2"
}
}
Your app should handle these being missing.
bundleDependencies
Dependencies to bundle when publishing:
{
"bundleDependencies": [
"my-private-package"
]
}
overrides
Override nested dependency versions:
{
"overrides": {
"lodash": "4.17.21"
}
}
Practice: Complete package.json
Here's a more complete package.json. Study the fields and try modifying them:
Field Categories Summary
| Category | Fields |
|---|---|
| Identity | name, version, description |
| People | author, contributors |
| Links | homepage, repository, bugs |
| Entry Points | main, module, exports, bin |
| Files | files, directories |
| Dependencies | dependencies, devDependencies, peerDependencies |
| Config | type, engines, private, workspaces |
Key Takeaways
- type: "module" enables ES modules
- engines specifies Node.js version requirements
- private: true prevents accidental publishing
- exports provides modern, flexible entry points
- peerDependencies for libraries that need host packages
What's Next?
Now that you understand package.json, let's learn how to install and manage packages.
التالي · الدرس 6 من 14
Installing Packages
قراءة 3 دقيقة
أنهيت 5 من 14 درسًا

اسأل Byte عن هذا الدرس
محادثة خاصة حول هذا الدرس. قرأ Byte الدرس كاملًا، ويجيب خلال ثوانٍ، ويُظهر القسم الذي تأتي منه كل إجابة. يمكنك السؤال بأي لغة.
الأسئلة والأجوبة
أسئلة عامة حول هذا الدرس. يجيب AI Tutor فورًا بلغتك، ويراجع فريق FreeAcademy الإجابات، ويمكن لكل المتعلمين قراءتها.

