{"id":10050,"date":"2025-11-04T04:54:08","date_gmt":"2025-11-04T04:54:08","guid":{"rendered":"https:\/\/hellonitish.com\/blog\/?p=10050"},"modified":"2025-11-04T18:40:15","modified_gmt":"2025-11-04T18:40:15","slug":"understanding-the-basics-of-a-package-json-file-as-a-beginner","status":"publish","type":"post","link":"https:\/\/hellonitish.com\/blog\/understanding-the-basics-of-a-package-json-file-as-a-beginner\/","title":{"rendered":"Understanding package.json: A Beginner’s Guide"},"content":{"rendered":"\n

When I first started learning web development, the package.json<\/code> file honestly intimidated me.
I could read what it said, but it never made much sense. Words like dependencies<\/em> and scripts<\/em> just floated around in my head with no real meaning.<\/p>\n\n\n\n

I didn\u2019t have the right resources or anyone to explain what was actually going on.<\/p>\n\n\n\n

After working on a bunch of projects and breaking a few along the way, I finally started to understand what this file really does.<\/p>\n\n\n\n

Here\u2019s everything I know about it now.<\/p>\n\n\n\n

What is package.json<\/code>?<\/h2>\n\n\n\n

It\u2019s like your project\u2019s identity card. It lives in the main folder and tells Node.js what your project is, what it needs, and how to run it.<\/p>\n\n\n\n

Every serious JavaScript or Node project has one, even if you never touch it directly.<\/p>\n\n\n\n

A Practical Example<\/h2>\n\n\n\n

Let’s start with a real-life package.json file form my Colorful library.<\/p>\n\n\n\n

{\n  \"name\": \"colorful\",\n  \"version\": \"1.6.1\",\n  \"description\": \"I wanted a single library that could convert, manipulate, and generate colors easily from RGB to HEX, from bright to dull, from one color to a full palette. When I couldn\u2019t find one that did everything, I built this.\",\n  \"main\": \"src\/colorful.js\",\n  \"directories\": {\n    \"doc\": \"docs\"\n  },\n  \"scripts\": {\n    \"test\": \"mocha tests\/*.js\",\n    \"build\": \"rollup --config\"\n  },\n  \"type\": \"module\",\n  \"keywords\": [\n    \"color manipulation\",\n    \"javascript\"\n  ],\n  \"author\": \"Nitish Kumar\",\n  \"license\": \"MIT\",\n  \"dependencies\": {},\n  \"devDependencies\": {\n    \"@rollup\/plugin-commonjs\": \"^28.0.2\",\n    \"@rollup\/plugin-node-resolve\": \"^16.0.0\",\n    \"@rollup\/plugin-replace\": \"^6.0.2\",\n    \"@rollup\/plugin-terser\": \"^0.4.4\",\n    \"chai\": \"^5.1.2\",\n    \"mocha\": \"^10.8.2\",\n    \"rollup\": \"^4.29.1\"\n  }\n}<\/code><\/pre>\n\n\n\n
The name, and description provide basic information about your project. The license lets people know how they can use your code.<\/p>\n\n\n\n
Now it is time to dive deeper into other keywords to get a better understanding of the whole thing.<\/p>\n\n\n\n
version<\/h3>\n\n\n\n
This shows which version your own project<\/em> is currently on.<\/p>\n\n\n\n
Developers usually follow something called semantic versioning<\/strong>, which looks like this:<\/p>\n\n\n\n
1.0.0<\/code> \u2192 major.minor.patch<\/strong><\/p>\n\n\n\n
    \n
  • major<\/strong> \u2013 for big breaking changes<\/li>\n\n\n\n
  • minor<\/strong> \u2013 for new features that don\u2019t break old ones<\/li>\n\n\n\n
  • patch<\/strong> \u2013 for small bug fixes<\/li>\n<\/ul>\n\n\n\n
    It\u2019s not mandatory to follow this, but it helps if you share your code or release updates later.<\/p>\n\n\n\n
    main<\/h3>\n\n\n\n
    This tells Node.js which file to run first when someone imports or runs your project as a package.
    For example, if your main file is index.js<\/code>, then this line means:<\/p>\n\n\n\n
    \n
    \u201cStart reading my project from here.\u201d<\/p>\n<\/blockquote>\n\n\n\n
    If you\u2019re building a small app for yourself, this doesn\u2019t matter much.<\/p>\n\n\n\n
    But if you publish an npm package, main<\/code> tells users which file to load when they require()<\/code> or import<\/code> it.<\/p>\n\n\n\n
    scripts<\/h3>\n\n\n\n
    This section is basically a list of custom commands<\/strong> you can run through npm.<\/p>\n\n\n\n
    Each entry is a shortcut. For example:<\/p>\n\n\n\n
    \"scripts\": {\n    \"test\": \"mocha tests\/*.js\",\n    \"build\": \"rollup --config\"\n}<\/code><\/pre>\n\n\n\n
    Then you can run these like:<\/p>\n\n\n\n
    npm run build\nnpm run test<\/code><\/pre>\n\n\n\n
    This saves you from typing long terminal commands every time.<\/p>\n\n\n\n
    For test<\/code> and start<\/code> scripts, you can simply type npm start<\/code> and npm test<\/code> and skip run<\/code> to get the same result.<\/p>\n\n\n\n
    You can create any script name you want. Even weird ones like \"deploy:prod\": \"echo Deploying...\"<\/code>.<\/p>\n\n\n\n
    dependencies<\/h3>\n\n\n\n
    These are the packages your app actually needs to run<\/strong>.<\/p>\n\n\n\n
    For example, if you\u2019re using Express to handle routes, it goes here:<\/p>\n\n\n\n
    \"dependencies\": {\n  \"express\": \"^4.18.2\"\n}<\/code><\/pre>\n\n\n\n
    When someone installs your project using npm install<\/code>, Node reads this section and automatically downloads all these packages.<\/p>\n\n\n\n
    That little ^<\/code> symbol before the version means \u201cinstall the latest minor or patch<\/em> update.\u201d<\/p>\n\n\n\n
    For example, ^4.18.2 will install 4.19.5 if available but not 5.0.0 because that is a major version bump.<\/p>\n\n\n\n
    You could also use ~<\/code> to update safely within the same minor version or avoid any symbols if you want to install the exact specified version.<\/p>\n\n\n\n
    It\u2019s a way of keeping things fresh without breaking your code.<\/p>\n\n\n\n
    devDependencies<\/h3>\n\n\n\n
    These are the tools you need while building<\/strong>, but not when your app is running.<\/p>\n\n\n\n
    Things like linters, bundlers, or test frameworks live here.<\/p>\n\n\n\n
    \"devDependencies\": {\n  \"eslint\": \"^8.56.0\",\n  \"vite\": \"^5.0.0\"\n}<\/code><\/pre>\n\n\n\n
    If you deploy your app somewhere, these usually aren\u2019t included because they\u2019re not required for production.<\/p>\n\n\n\n
    You can install a dev dependency with:<\/p>\n\n\n\n
    npm install eslint --save-dev<\/code><\/pre>\n\n\n\n
    That --save-dev<\/code> flag tells npm to keep it in devDependencies<\/code>.<\/p>\n\n\n\n
    type<\/h3>\n\n\n\n
    This tells Node.js how to interpret your .js<\/code> files<\/strong>. Whether they should use the old CommonJS syntax or the modern ES Module syntax.<\/p>\n\n\n\n
    For example:<\/p>\n\n\n\n
    \"type\": \"module\"<\/code><\/pre>\n\n\n\n
    tells Node to expect modern import and export syntax:<\/p>\n\n\n\n
    import express from 'express';\nexport default app;<\/code><\/pre>\n\n\n\n
    If you leave it out, Node defaults to CommonJS mode, which uses require()<\/code> and module.exports<\/code> instead:<\/p>\n\n\n\n
    const express = require('express');\nmodule.exports = app;<\/code><\/pre>\n\n\n\n
    So in short:<\/p>\n\n\n\n
      \n
    • \"type\": \"module\"<\/code> \u2192 all .js<\/code> files are treated as ES modules.<\/li>\n\n\n\n
    • \"type\": \"commonjs\"<\/code> or no type \u2192 all .js<\/code> files are treated as CommonJS.<\/li>\n\n\n\n
    • .mjs<\/code> files are always<\/em> modules, and .cjs<\/code> files are always<\/em> CommonJS, no matter what this setting says.<\/li>\n<\/ul>\n\n\n\n
      This field decides how Node (not your browser) runs your code.<\/p>\n\n\n\n
      <\/p>\n","protected":false},"excerpt":{"rendered":"
      When I first started learning web development, the package.json file honestly intimidated me.I could read what it said, but it never made much sense. Words like dependencies and scripts just floated around in my head with no real meaning. I didn\u2019t have the right resources or anyone to explain what was actually going on. After […]<\/p>\n","protected":false},"author":2,"featured_media":10256,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[24],"tags":[],"class_list":["post-10050","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-dev-notes"],"_links":{"self":[{"href":"https:\/\/hellonitish.com\/blog\/wp-json\/wp\/v2\/posts\/10050","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/hellonitish.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/hellonitish.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/hellonitish.com\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/hellonitish.com\/blog\/wp-json\/wp\/v2\/comments?post=10050"}],"version-history":[{"count":13,"href":"https:\/\/hellonitish.com\/blog\/wp-json\/wp\/v2\/posts\/10050\/revisions"}],"predecessor-version":[{"id":10263,"href":"https:\/\/hellonitish.com\/blog\/wp-json\/wp\/v2\/posts\/10050\/revisions\/10263"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/hellonitish.com\/blog\/wp-json\/wp\/v2\/media\/10256"}],"wp:attachment":[{"href":"https:\/\/hellonitish.com\/blog\/wp-json\/wp\/v2\/media?parent=10050"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/hellonitish.com\/blog\/wp-json\/wp\/v2\/categories?post=10050"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/hellonitish.com\/blog\/wp-json\/wp\/v2\/tags?post=10050"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}