Test the package you publish, not the repo you built

The package you publish is a different object from the source you wrote. It has its own file list, its own entry points and its own runtime rules, and it runs inside someone else's node_modules. Tests in your repository never see that object.

Before I published metaproof, a zero-dependency linter for App Store metadata, I installed the packed tarball in an empty folder and ran npx metaproof. It was dead on arrival. Every test in the repository was green.

#The two-minute check

Run this before every first publish and after any change to how the package is built.

>1. Pack it exactly as npm will

npm pack --dry-run   # shows every file that would ship
npm pack             # writes <name>-<version>.tgz

Read the dry-run list. Anything missing from it (a dist folder, a template, a schema) will be missing for every user.

>2. Install the tarball where your source cannot help

mkdir -p /tmp/pack-check && cd /tmp/pack-check
npm init -y
npm install /path/to/your-package-0.1.0.tgz

The folder has to be outside your repository, so nothing resolves back to your source files or your dev dependencies.

>3. Run the real entry point

npx your-package --help
node -e "import('your-package').then(m => console.log(Object.keys(m)))"

Run the command your README tells people to run, and import the package the way a dependent would. One clean run of each is enough to catch a whole class of failures: a bin path that points at nothing, an exports map that hides the entry file, a dependency that only existed in devDependencies.

#What it caught: TypeScript inside node_modules

Current Node can run TypeScript directly by stripping the types at load. I ran metaproof that way through all of development, straight from the .ts files, and it worked every time.

Node only does this for your own source. Inside node_modules it refuses and exits with ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING. My package was about to ship the TypeScript source as written, so it ran perfectly from the repo and would have failed the moment anyone installed it.

#The fix

Ship compiled JavaScript and keep running the source where Node allows it:

• Point bin, exports and files at a dist folder of plain .js.
• Add a prepack script that runs tsc, so npm pack and npm publish always build first.
• Keep runtime dependencies where they were (zero, in metaproof's case).

metaproof's GitHub Action still runs the .ts source, because there it is first-party code and type stripping is allowed. Only what goes to npm is compiled. After the change I published metaproof 0.1.0 and ran npx metaproof from a clean install again.

#The rule

Before you tell anyone a thing exists, get it the way they will get it and run it once. A package is not your repo, a build is not your dev server, and a deploy is not your code. The check takes two minutes, and it decides whether you find the bug or a stranger does.