You open a draft web page in your editor to quickly test an idea in the browser without a bundler and pull in a library via a content delivery network (CDN). You write the package name in the import string, point to the stylesheet—and get a 404 Not Found error in the console. You have to dig into the release tree and manually insert a technical folder into the middle of the URL, turning the link into an awkward string like https://cdn.jsdelivr.net/npm/ie-page-transitions@0.0.1/src/ie-page-transitions.css.
This quirk of the JavaScript ecosystem has always surprised me: why should someone using a finished package even need to know which folder the author put the compiled files into? Google Chrome Developer Relations engineer Bramus Van Damme showed on his Bram.us blog how to use a built-in feature of the npm CLI to publish only the contents of ./dist to the registry so modules import directly from the package root while keeping the repository tidy.
Why the Build Folder Leaks into Public Library URLs
In a modern JavaScript or TypeScript project, code lives on two shelves: ./src holds the source files, and ./dist is where the compiler outputs finished .js scripts, .d.ts type declarations, and .css styles. When you run npm publish from the project root, the tool packs the entire current directory along with its nested folder structure.
It's like delivering a toaster to a customer not in a retail box, but straight in the iron crate from the assembly bench stamped "Finished Goods Workshop." Bramus gives the example of the first version of his ie-page-transitions package (0.0.1), where all four working files—ie-page-transitions.css, ie-page-transitions.mpa.js, ie-page-transitions.shared.js, and ie-page-transitions.spa.js—went into the registry inside ./src.
In Node.js or during bundling, the exports field in the root package.json hides this layout. It acts like a front-desk receptionist: a request for import styles from 'ie-page-transitions/css' with { type: "css" } is quietly routed to the internal path ./src/ie-page-transitions.css. But when loading the package in a browser via a public CDN, that masking disappears: the server reads the tarball by its physical paths, and ./src/ or ./dist/ spills into the public URL.
Trying to drop the extra prefix, authors often go to the opposite extreme—abandoning ./dist and outputting compiled .js, .d.ts, and .map files straight into the repository root. On the registry storefront the paths look short, but inside the project chaos ensues: build artifacts mix with configs, tests, and source files, cluttering the Git working tree.
How Subfolder Publishing Works and Why the Package Loses Its Passport
To avoid turning the repository into a dumping ground while still exposing a clean interface, you just need to change the packing root. The npm publish command accepts a path to the target folder as an argument: npm publish ./dist.
Let's see how the archiver behaves with this invocation:
- If you pass
./distto the CLI,npmstops packing the repository root and makes./distthe root of the published tarball. - If
./distbecomes the tarball root, every compiled file inside it lands at the top level of the package—this is how Bramus publishedhic-pageflip,mermaid-element, andrich-input, trimming the CDN import down to a cleanimport { PageFlip } from 'https://cdn.jsdelivr.net/npm/hic-pageflip'. - However, if the archiver ignores everything outside
./dist, the published package loses its passport—package.json,README.md, andLICENSE, which were left a floor above in the repository root.
Here comes the second trap. Suppose you simply copy the root package.json into ./dist. In the original file, entry points are written relative to the repository root: "main": "./dist/index.js" and "exports": { ".": "./dist/index.js", "./submodule": "./dist/submodule.js" }. If you ship that manifest inside ./dist, once the package is installed, Node.js will look for ./dist/index.js relative to the new root—meaning it will resolve to the nonexistent path ./dist/dist/index.js, and imports will break.
In the pnpm package manager, this is solved by "publishConfig": { "directory": "dist" } (we covered other registry tooling in our breakdown of the pnpm 12.13.0 release). Yet the standard npm client, despite a decade of community requests, still does not support publishConfig.directory—so preparing ./dist has to be wired into your build step.
Automatically Building a Clean Manifest and Copying Metadata into dist
Let's walk through a utility package example to see how to automate preparing ./dist after compilation. We'll write a scripts/postbuild.js script using built-in node:fs and node:path modules that copies documentation and the license, strips dev-only sections from package.json, and rewrites paths in main, module, types, and exports relative to the new root:
import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const rootDir = path.resolve(__dirname, '..');
const distDir = path.join(rootDir, 'dist');
for (const file of ['README.md', 'LICENSE']) {
const srcPath = path.join(rootDir, file);
if (fs.existsSync(srcPath)) {
fs.copyFileSync(srcPath, path.join(distDir, file));
}
}
const pkgPath = path.join(rootDir, 'package.json');
const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
delete pkg.scripts;
delete pkg.devDependencies;
const distPkg = JSON.stringify(pkg, null, 2).replaceAll('./dist/', './') + '\n';
fs.writeFileSync(path.join(distDir, 'package.json'), distPkg, 'utf8');
When run, the loop copies README.md and LICENSE alongside the compiled modules so the registry web page displays documentation and the package stays legally compliant. Next, the script reads the root package.json, uses delete to strip scripts and devDependencies that library consumers don't need, and calls replaceAll('./dist/', './') to trim the build folder prefix from all entry points—turning "./dist/index.js" and "./dist/submodule.js" into direct paths "./index.js" and "./submodule.js".
To run the script automatically after compilation, add the hook "postbuild": "node scripts/postbuild.js" to your root package.json. And if your compiler generates source maps, check out our piece on when source maps in npm packages are justified and how to shrink JavaScript bundle size so you don't bloat the tarball with debug files.
When copying metadata into ./dist, never transfer .env files, a local .npmrc containing NODE_AUTH_TOKEN, or CI/CD configs. If your package ships CLI commands via the bin field, make sure their paths in dist/package.json are also adjusted relative to ./dist.
Guarding Against Muscle Memory and Inspecting the Tarball with npm pack
Even with the script in place, habit remains a risk: if you absentmindedly type npm publish from the project root, the CLI will run the build and upload the entire root directory instead of ./dist. To guard against this, Bramus turns the "prepublishOnly" hook into a safety catch—"if [ -z $PUBLISH ]; then echo 'ERROR: Use npm run pub' && exit 1; fi"—and moves publishing into "pub": "PUBLISH=true npm run build && npm publish ./dist --access public".
On an accidental npm publish, the $PUBLISH environment variable is empty (-z $PUBLISH), so the script exits with exit 1 and aborts the upload. Meanwhile, npm run pub sets PUBLISH=true, runs the build with postbuild.js, and publishes only ./dist. In team pipelines, this pairs well with isolated artifact publishing, covered in our guide to safe npm package releases and supply-chain protection.
Before your first upload, verify the tarball contents in dry-run mode using npm publish ./dist --dry-run or npm pack ./dist --dry-run. The CLI will assemble the package without uploading and print Tarball Contents: for hic-pageflip (1.0.1), the report shows hic-pageflip-1.0.1.tgz weighing 3.2 kB (9.1 kB unpacked) with 5 files right at the root—LICENSE (1.1kB), README.md (1.8kB), index.js (850B), package.json (1.2kB), and core/engine.js (4.2kB). You can also run npm pack ./dist and extract the archive with tar -xzf my-package-1.0.0.tgz to inspect the clean layout firsthand.
Don't worry if your current libraries still have /dist in their import paths—there's no need to drop everything and refactor every old repository overnight. Start with the next scheduled update of any small package: add a short manifest-prep script, verify the file list with npm pack ./dist --dry-run, and switch to clean publishing once you see every module sitting in its proper place.


