<h1>JS is plenty.</h1>
<p>I opened my inbox last week to three more pull requests. All asking the same thing. Please convert <code>remove-markdown</code> to TypeScript.</p>
<p>I maintain <code>remove-markdown</code>, <a href="https://www.npmjs.com/package/remove-markdown" target="_blank" rel="noopener nofollow">a JavaScript npm package with around 900,000 downloads a week</a>. The entire library is 80 lines, one function, zero dependencies. Requests to migrate it to TypeScript have been a steady drumbeat for a few years. My answer is no.</p>
<p>TypeScript is a tool I use myself. The case for migrating this specific library hasn’t added up. The developers sending those PRs already have what they need.</p>
<h2>What does remove-markdown actually do?</h2>
<p><code>remove-markdown</code> takes a Markdown string and returns plain text. One exported function. One file. A sequence of regex substitutions that strips list leaders, GFM tokens, fenced code blocks, HTML tags, links, blockquotes, headers, and emphasis markers.</p>
<p>The API surface is a string in, a string out, and an optional configuration object with 8 flags. That’s it. The library hasn’t needed a breaking change in years because there’s nothing complex enough to break.</p>
<h2>Does shipping <code>index.d.ts</code> give TypeScript users what they need?</h2>
<p><code>remove-markdown</code> ships an <code>index.d.ts</code> file. If you install it as a TypeScript developer, you get full IDE autocomplete, parameter types, and return type inference out of the box. Your editor knows that <code>removeMd</code> takes a <code>string</code> and returns a <code>string</code>. It knows the shape of the options object.</p>
<p>The source language is invisible to you as a consumer. TypeScript doesn’t know or care whether the library was written in <code>.ts</code> or <code>.js</code>. It reads <code>index.d.ts</code> and does its thing.</p>
<p>This is common practice. Sindre Sorhus, who maintains hundreds of npm packages, ships many of them as plain JavaScript with hand-written type declarations. The <a href="https://github.com/DefinitelyTyped/DefinitelyTyped" target="_blank" rel="noopener nofollow">DefinitelyTyped</a> project maintains types for thousands of JavaScript packages as a separate artifact. The split between source language and published types is a solved problem.</p>
<p>Most of the TypeScript migration PRs I receive are requesting something <code>remove-markdown</code> already provides.</p>
<h2>What does TypeScript actually prevent in a small library?</h2>
<p>TypeScript’s main value is catching type-shape errors. Passing the wrong kind of data to a function, accessing a property that doesn’t exist, returning the wrong type from a callback. In large codebases with many modules, that coverage is useful. The commonly cited estimate is that TypeScript catches roughly 15% of JavaScript bugs.</p>
<p>That 15% figure assumes a codebase where type-shape bugs are a realistic failure mode. It assumes functions accepting complex objects, APIs evolving across a large team, and interfaces that need to stay consistent across many files.</p>
<p><code>remove-markdown</code> takes a string. It returns a string. The options object has 8 fields, all well-understood, all documented.</p>
<p>The failure modes I worry about are broken regex patterns, edge cases in the GFM spec, and characters that slip through the substitutions. TypeScript is silent on every one of those. It can’t tell you your regex is wrong. It can’t validate that you’ve handled every Markdown edge case.</p>
<p>A threshold I’ve found useful is 10,000 lines of code. Below that, TypeScript’s benefits are largely theoretical. <code>remove-markdown</code> is 80 lines.</p>
<h2>What does migrating to TypeScript actually cost?</h2>
<p>The published JavaScript would be identical either way. TypeScript types are erased at compile time, so the bundle your users receive is the same regardless of the source language. What changes is your maintenance surface.</p>
<p>You’d add a build step, a <code>tsconfig.json</code>, and TypeScript version management, and the output artifact would be exactly what it is today. That overhead compounds over years.</p>
<p>Every few months there’s a TypeScript version bump, a new strict mode warning to resolve, or a tsconfig setting that changed behavior. For a library this stable, that’s pure friction with no payoff.</p>
<p>There’s also contributor access to consider. Right now, anyone can clone <code>remove-markdown</code> and start contributing immediately. No compilation step, no toolchain to install beyond Node. Adding TypeScript raises that floor.</p>
<p>Some well-known projects made the same call. Webpack chose JSDoc type annotations over TypeScript specifically to avoid introducing a compile step. Rich Harris migrated the Svelte 4 compiler from TypeScript back to JavaScript and cited improved debuggability and lower contributor friction. Both decisions came from experienced maintainers who decided the complexity didn’t pay off at their scale.</p>
<h2>When does TypeScript migration make sense for an npm package?</h2>
<p>The migration argument has real merit in specific cases. TypeScript source auto-generates <code>index.d.ts</code>, keeping types synchronized with the implementation. A hand-maintained declaration file can drift as the library evolves, and TypeScript source fixes that problem permanently.</p>
<p>If I add a new option to <code>index.js</code> and forget to update <code>index.d.ts</code>, TypeScript users get stale autocomplete until the next release. That lag is a real risk, and one I carry manually.</p>
<p>The contributor expectations argument has also shifted. TypeScript is now used by 43.6% of developers according to the 2025 Stack Overflow Developer Survey. A contributor who opens a <code>.js</code> file might read it as a signal about the project’s health, even if the code is perfectly clear.</p>
<p>Node.js v22 now supports running TypeScript natively by stripping type annotations at runtime. The traditional “you have to compile it” objection has weakened.</p>
<p>For a library with a growing API surface, multiple active contributors, or an <code>index.d.ts</code> that’s started to drift, migrating to TypeScript source makes sense.</p>
<h2>How do you decide whether a JavaScript npm library needs TypeScript?</h2>
<p>Three things clarify the tradeoff for any small npm library: whether the API surface is growing, whether types have drifted from the implementation, and whether there are multiple active contributors. For <code>remove-markdown</code>, all three answers are no.</p>
<p>If the API keeps growing, TypeScript’s type-safety benefits grow with the surface area. More options, more overloads, more data shapes means more surface for the compiler to check.</p>
<p>If <code>index.d.ts</code> is hand-maintained and options exist in the code that aren’t reflected in it, that’s a real maintenance cost. TypeScript source fixes the problem by generating declarations from the implementation.</p>
<p>If there are multiple active contributors, type errors caught by the compiler are errors that don’t reach code review. Solo-maintained libraries with a stable API get less leverage from that.</p>
<p>For <code>remove-markdown</code>, none of those apply.</p>
<p>JSDoc type annotations are worth knowing as a middle path. Adding them as comments lets <code>tsc --checkJs</code> validate the implementation without converting the source to <code>.ts</code>. Running with <code>--declaration</code> auto-generates <code>index.d.ts</code> from those annotations, giving you compiler-level checking while keeping plain JavaScript.</p>
<h2>FAQ</h2>
<p><strong>Q: Does shipping</strong> <code>index.d.ts</code> <strong>give TypeScript users full type safety?</strong></p>
<p>Yes. TypeScript reads the declaration file and provides full autocomplete, parameter types, and return type inference. The source language is irrelevant to the consumer experience. You get the same IDE behavior whether the library was written in TypeScript or JavaScript.</p>
<p><strong>Q: When should a small npm library migrate to TypeScript?</strong></p>
<p>Migrate when the <code>index.d.ts</code> is drifting from the implementation, when there are multiple active contributors who’d benefit from compiler-enforced contracts, or when the API surface is growing significantly. If none of those apply, a carefully maintained <code>index.d.ts</code> or JSDoc annotations are sufficient.</p>
<p><strong>Q: What’s the JSDoc middle path?</strong></p>
<p>Adding JSDoc type annotations to JavaScript source lets <code>tsc --allowJs --checkJs</code> validate the implementation without a compile step. Running with <code>--declaration</code> auto-generates <code>index.d.ts</code> from those annotations. Types live as comments, there’s no compilation step, and the source stays readable by anyone who knows JavaScript.</p>
<h2>Conclusion</h2>
<p>The question for any small library is whether TypeScript’s added complexity pays off for this specific codebase, with this specific API surface, and this specific team.</p>
<p>For <code>remove-markdown</code>, the math says no. 80 lines, one function, one primary contributor, and an <code>index.d.ts</code> that already works. TypeScript catches a different category of bugs than the ones this library faces.</p>
<p>If you maintain a small npm package and want to ship types without migrating, two things matter. Make sure your <code>types</code> field in <code>package.json</code> points to your declaration file, and keep that file in sync with every release. Your TypeScript users will have everything they need, and you’ll keep your build step free.</p>


matt abrams

The maintainer of `remove-markdown`, an npm package with ~900k weekly downloads, explains why he refuses TypeScript migration PRs. The library already ships an `index.d.ts` giving TypeScript users full autocomplete and type safety. At 80 lines with a stable API, TypeScript would add build tooling overhead with no meaningful bug-prevention benefit — since the real failure modes (broken regexes, GFM edge cases) are invisible to the type system. The post outlines a practical decision framework: migrate when the declaration file drifts from implementation, when multiple contributors exist, or when the API surface is growing. For stable, small libraries, a hand-maintained `index.d.ts` or JSDoc annotations with `tsc --checkJs` are sufficient alternatives.