The npm Package I Was About to Ship Could Not Run Under npx

I built a small tool called metaproof. It lints the App Store metadata folder for my apps: field lengths per locale, wasted keywords, all offline with zero dependencies. I wrote it in TypeScript and prepared it for npm. The whole pitch is that you run one command, npx metaproof, and it tells you what Apple will reject before you submit.

Before I published or announced it, I installed the packed tarball in an empty folder and ran that exact command. It was dead on arrival.

#Node Will Not Strip Types Inside node_modules

Modern Node can run TypeScript directly now. It strips the types at load and runs the JavaScript underneath, no build step. That is how I ran metaproof all through development, straight from the .ts files, and it worked every time.

What I did not know is that Node only does this for your own source. The moment the code lives inside node_modules, it refuses. Install a package that ships raw .ts and Node throws ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING and quits. So my package, which would have shipped the TypeScript source exactly as I wrote it, ran perfectly from my repo and would have broken the instant anyone installed it. The environment that worked was mine. The environment that failed was the clean install.

#I Only Caught It Because I Tested the Installed Thing

I did not find the bug by reading code. I found it because the last step before publishing was to install the packed tarball in a clean directory, as a stranger would, not from the project where all my source sits. Locally everything was green. The package I was about to publish was broken. Those were two different objects and I had only been testing one of them.

#The Fix Is Boring

Compile to JavaScript for the shipped artifact. I pointed the package's bin, exports, and files at a dist folder of plain .js, added a prepack step that runs tsc before publish, and kept the runtime dependencies at zero. The GitHub Action still runs the .ts source directly, because that runs as first-party code where type stripping is allowed. Only the thing that goes to npm is compiled. After that, I published metaproof 0.1.0 and verified npx metaproof from a clean install.

#Test What You Ship, Not What You Built

The lesson is not really about TypeScript. The artifact you publish is a different object from the source you wrote, and the gap between them is exactly where "works on my machine" lives. A package is not your repo. A build is not your dev server. The deploy is not the code.

So the rule I run now: before I tell anyone a thing exists, I get it the way they will get it, install it fresh, and run the real entry point once. It takes two minutes and it is the difference between finding your own bug and letting a stranger find it for you.