What a package ships: npm pack and the files list
Publishing a package is a copy of a folder, and the interesting question is which files go into the copy. The tests, the fixtures and the config of a linter are part of the repository and not of the package, and a tarball that carries them is bigger and tells a reader nothing. The files field of package.json answers the question, and npm shows the answer with npm pack --dry-run, without publishing anything.
The lesson packs the small tool of the previous lesson, reads the JSON report of a dry run with a program, removes one entry from the field and packs again, then swaps the whitelist for an ignore file. The last command writes the tarball and lists what is inside it.
npm pack --dry-run
The package is note-tools: two functions in src, a command in cli.js, a test, a readme and a licence. The files field names the folder and the two files, and the command names the entry file through main and the tool through bin.
The file package.json:
vi package.json
{
"name": "note-tools",
"version": "1.0.0",
"description": "Two helpers for a list of notes",
"license": "ISC",
"type": "commonjs",
"main": "src/format.js",
"bin": {
"note-count": "./cli.js"
},
"files": [
"src",
"cli.js",
"README.md"
]
}
The code of the package is two functions and a command that uses both. The command is the reason the tarball has to carry src at all, which the next section comes back to.
The file src/format.js:
function format(text) {
return text.trim().replace(/\s+/g, ' ');
}
module.exports = { format };
The file src/count.js:
function count(text) {
return text.split('\n').filter((line) => line.trim() !== '').length;
}
module.exports = { count };
The file cli.js:
#!/usr/bin/env node
const { readFileSync } = require('node:fs');
const { format } = require('./src/format');
const { count } = require('./src/count');
const text = readFileSync(process.argv[2], 'utf8');
console.log(count(text) + ' note(s): ' + format(text));
--dry-run does everything except write the file, and --json turns the report into an object with the name, the size, the count and one entry per file. The program keeps the fields a reader can check and prints the rest of the line as the size in bytes. It sits in the folder above the package, because a file inside the package would appear in the report of the third variant below.
The file pack-report.js:
let text = '';
process.stdin.setEncoding('utf8');
process.stdin.on('data', (chunk) => {
text += chunk;
});
process.stdin.on('end', () => {
const [report] = JSON.parse(text);
console.log(report.name + '@' + report.version + ' (' + report.filename + ')');
console.log('files in the tarball: ' + report.entryCount);
for (const file of report.files) {
console.log(' ' + file.path + ' ' + file.size);
}
console.log('packed size: ' + report.size + ' bytes');
});
npm pack --dry-run --json | node ../pack-report.js
note-tools@1.0.0 (note-tools-1.0.0.tgz)
files in the tarball: 6
LICENSE 163
README.md 96
cli.js 260
package.json 274
src/count.js 125
src/format.js 99
packed size: 779 bytes
Six files and no test. The list is sorted by path, which hides the order of the tarball, and the sizes are the bytes on disk before the compression. LICENSE, README.md and package.json were not in the field and ship anyway, because a package without a manifest cannot be installed and the other two are the description that a registry shows.
The files field
files is a whitelist: a path in it is included with everything under it, and everything else is left out except the three files above and the entry that main names. Remove src and the report shows both halves of that rule at once.
vi package.json
npm pack --dry-run --json | node ../pack-report.js
note-tools@1.0.0 (note-tools-1.0.0.tgz)
files in the tarball: 5
LICENSE 163
README.md 96
cli.js 260
package.json 263
src/format.js 99
packed size: 698 bytes
src/count.js is gone and src/format.js stayed, because it is the file that main names. The manifest is nine bytes shorter, which is the cost of the shorter array. The package that these files make is broken all the same: cli.js requires ./src/count, and that file is not in the tarball. npm cannot see a require, so the field is a statement of intent that a test of the packed tarball has to confirm.
The other list, and the fixed rules
Remove the field and add .npmignore, and the rule turns around: everything ships except the paths in the file. The two lists do not work together, because files wins when both exist, and the ignore file is not published itself.
The file .npmignore:
vi .npmignore
test/
*.log
npm pack --dry-run --json | node ../pack-report.js
note-tools@1.0.0 (note-tools-1.0.0.tgz)
files in the tarball: 6
LICENSE 163
README.md 96
cli.js 260
package.json 215
src/count.js 125
src/format.js 99
packed size: 757 bytes
The test is out and everything else is in, including the files that a package usually does not need. The ignore file itself is missing from the list, and so would be node_modules, .git and every .npmrc: a few rules are fixed and cannot be turned around by either list. A blacklist is therefore the right tool for a repository that is almost all package, and a whitelist is the right one for a project with a config file per tool.
The tarball itself
The field is back in the manifest for the last command, which writes the file that a registry would receive. --silent keeps the name of the file and drops the notice lines, and the name is the one the dry run reported.
vi package.json
npm pack --silent
note-tools-1.0.0.tgz
A tarball is a tar archive with a gzip around it, and every path inside it starts with package/, because the installer unpacks it into a folder of that name. The listing is the archive's own answer, and it is the check that the JSON report can only promise.
tar -tzf note-tools-1.0.0.tgz
package/LICENSE
package/cli.js
package/src/count.js
package/src/format.js
package/package.json
package/README.md
Six entries, the same six files. The same command with -x instead of -t unpacks them into a folder, which is what an install from the tarball does before it runs the lifecycle scripts of the package. The file is removed after the check, because a second npm pack would only write it again.
rm note-tools-1.0.0.tgz
That is the end of the part on tooling. The course page lists every lesson that is written, and the next part builds three projects from the pieces of this one.
Exercises
- Add test to the files field and pack again. Which entry appears, and why would a package that ships its tests be a reasonable choice?
- Set files to an empty array and pack. Which files remain, and which rule decides them?
- Unpack the tarball into a folder, install it into another project and run the command. Which file is missing, and what is the error?
- Put a private: true next to the name and run npm pack. Which command does the field stop, and does packing still work?
- Compare the packed size with the sum of the sizes in the report. Which numbers explain the difference, and what does gzip do to six small text files?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What does the files field of package.json control?
Answer
Which files go into the published package
It is a whitelist for the tarball, and package.json, the readme and the licence ship anyway.
-
What does this program print?
const files = ["LICENSE", "README.md", "cli.js", "src/count.js"]; console.log(files.filter((file) => file.startsWith("src/")).length);Answer
1
Only one entry starts with the folder prefix.
-
Which three files ship even when the files field does not name them?
Answer
package.json, the readme and the licence
A package needs its manifest and its description, and npm adds the entry file of main as well.
-
What does this program print?
const report = { entryCount: 6, size: 779, files: [{ path: "a", size: 100 }] }; console.log(report.files.length, report.entryCount);Answer
1 6
The list in this object has one entry, while the count says what the whole tarball holds.
-
What happens when both files and .npmignore exist?
Answer
The files field decides, and the ignore file is not used
The whitelist is the stronger statement, which is why a project picks one of the two.
-
What does this program print?
const paths = ["package/LICENSE", "package/src/count.js"]; console.log(paths.map((path) => path.split("/").pop()).join(", "));Answer
LICENSE, count.js
The last part of each path is the file name, and the tarball prefix disappears.
-
Why is a test of the packed tarball worth having?
Answer
Because npm cannot see which files the code requires at run time
A missing source file produces a package that installs and then fails, and only a run of the packed copy finds it.
-
What does this program print?
const files = ["LICENSE", "README.md", "cli.js", "package.json", "src/count.js", "src/format.js"]; console.log(files.length === 6, files.includes("test/format.test.js"));Answer
true false
The list has six entries and the test file is not one of them.
-
What does
npm pack --dry-runwrite?Answer
Nothing, it only reports what would be packed
The dry run prints the report and leaves the folder as it was.
-
How are the paths inside the tarball written?
Answer
With a package/ prefix in front of every path
The installer unpacks the archive into a folder named package, so the paths have to agree with it.
The programs and commands on this page were run with Node.js 24.22.1 and npm 11.12.1, and linted with ESLint 10.14.0 on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev