Çfarë është npm dhe çfarë bëjnë package.json dhe lockfile?

Question

Accepted Answer

**npm** (Node Package Manager) është mjeti parazgjedhur i Node për instalimin dhe menaxhimin e paketave palësh të tretë (varësitë) dhe ekzekutimin e skripteve të projektit. Dy skedar përcaktojnë një projekt: **`package.json`** (manifesti) dhe **`package-lock.json`** (pema e saktë e varësisë).

## package.json — manifesti i projektit

```json
{
  "name": "my-app",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "start": "node server.js",
    "dev": "nodemon server.js",
    "test": "vitest"
  },
  "dependencies": {        // needed at RUNTIME
    "express": "^4.18.0"
  },
  "devDependencies": {     // needed only for DEVELOPMENT (testing, building)
    "vitest": "^1.0.0"
  }
}
```

Çdo përshkrim metadate, skripte dhe varësi. `^4.18.0` është një **diapazon semver** — `^` lejon përditësime të përputhshme minor/patch (4.x.x por jo 5.0.0).

## Lockfile — instalime të sakta dhe të përsëritshme

```text
package.json says:  express ^4.18.0  (a RANGE — could install 4.18.0 or 4.19.2...)
package-lock.json:  express 4.18.2   (the EXACT version + every nested dependency)
```

Lockfile pin versioni **i saktë** i secilit paket (duke përfshirë varësitë kalimtare) i cili u instalua. Kjo garanton që të gjithë në ekip — dhe CI, dhe produkcioni — marrin pemën e varësisë *identike*, duke parandaluar gabimet "funksionon në kompjuterin tim" nga driftimi i versionit.

## Komandat kryesore

```bash
npm install              # install all deps from package.json (updates lockfile)
npm install express      # add a dependency
npm install -D vitest    # add a devDependency
npm ci                   # install EXACTLY from the lockfile (used in CI — fast, strict)
npm run dev              # run a script defined in package.json
```

`npm ci` (vs `npm install`) instalon në mënyrë rigoroze nga lockfile pa e modifikuar atë — komanda e saktë për riproduksionin CI/produksion.

## Commitoni lockfile-in

```text
✓ ALWAYS commit package-lock.json → reproducible installs across the team & CI
```

## Pse kjo ka rëndësi

npm dhe këta dy skedarë janë themeli i secilit projekt Node.

Përqasja `package.json` (varësitë vs devDependencies, diapazonet semver, skriptet) dhe veçanërisht **pse lockfile ekziston** (instalime deterministe, të përsëritshme të pemës së plotë të varësisë) është thelbësore — commit i lockfile-it dhe përdorimi i `npm ci` në CI parandalon dështimet delikate, të vështira për të korrigjuar të shkaktuara nga shokët e ekipit ose produksioni që marrin versione të ndryshme të paketave.