All articles
165 articles · updated weekly See our Tools
All articles
All

Is TypeScript worth it for small projects?

TS adds a build step, but pays off in autocomplete, safe refactors, and bugs caught early. See the real tradeoff and when it is NOT worth it for small projects.

Is TypeScript worth it for small projects?
COVER · All

"TypeScript is for big projects" is one of the most repeated and least true claims in the JavaScript ecosystem. The reasoning behind it is defensible: TS adds a build step, requires configuration, and at first feels like you are typing twice the code for the same result. In a 200-line script, that friction is intimidating. But the math has changed over the last few years, and what used to be a real setup cost has become almost noise. The right question is no longer "is it worth it for a small project?", but "at what exact point does the prototype stop being throwaway?".

This piece is about the concrete tradeoff: what you pay, what you gain, and when it is actually better to ignore the type system on purpose.

Today's cost is smaller than you remember

TypeScript's reputation for "friction" comes from an era of huge tsconfig.json files, slow ts-node, and badly configured webpack. That world is dead. Today, tsx runs a .ts file directly, with no separate build: npx tsx script.ts and you are done. vite understands TS natively, bun executes TS with no intermediate step, and recent node already ships with type stripping built in. The "build step" that scared everyone is now, in practice, a flag you don't even notice.

That changes the conversation. When setup cost an afternoon, skipping TS on something small made sense. When it costs an npm i -D typescript and a six-line tsconfig, the opportunity cost has all but vanished. You pay seconds, not hours.

Where the benefit shows up — and it shows up early

TypeScript's payoff is not proportional to project size; it is proportional to how many times you read and change the same code. And even a 200-line script gets reopened the following week without you remembering the shape of that config object.

Three benefits land before the 200-line mark:

  • Real autocomplete. With types, the editor knows that user. offers name and email, not naem. In plain JS, autocomplete is a guess based on heuristics.
  • Safe refactor. Rename a field, change a function signature, move a module — the compiler points to every place that broke before you run it.
  • Bugs caught before execution. undefined is not a function at 11pm becomes a red underline at 2pm.

Consider the most common case in a small project: consuming an API.

type Repo = { name: string; stars: number; archived: boolean };

const res = await fetch("https://api.example.com/repos");
const repos: Repo[] = await res.json();

const active = repos.filter((r) => !r.archived);

From here, r. hands you name, stars, and archived. Mistyping r.star (without the "s") becomes a compile error, not a silent undefined summed into a total. Writing these types by hand is tedious, and it is exactly the kind of task you should not do manually: drop a sample response into a JSON to TypeScript generator and it spits out the ready interface in seconds — you only adjust what the sample didn't cover.

Inference: you write less than you think

The "typing twice" objection starts from a wrong image of TypeScript, one where every variable carries an explicit annotation. In practice, inference does the heavy lifting and you annotate very little.

// No annotations here — TS infers everything
const total = [1, 2, 3].reduce((a, b) => a + b, 0); // number
const names = ["ana", "bia"].map((n) => n.toUpperCase()); // string[]

The practical rule that works: annotate the boundaries (function parameters, API responses, config shape) and let the interior infer. You end up writing less annotation than you imagine, and the editor still knows the type of everything. People who complain about verbosity are almost always annotating what the compiler already knew.

any is debt, not an escape hatch

any is TypeScript's escape valve: it turns off checking for that value. It is tempting to use it to "make the error go away," but every any is debt — a hole through which the bugs TS was supposed to catch quietly slip back in.

function parse(raw: any) {
  return raw.data.items.map((i) => i.id); // zero checking, zero autocomplete
}

In a small project the impact of any is smaller, but the habit is the same one that rots large projects. When you don't know the type, unknown is almost always the better choice: it forces you to verify before using, instead of pretending you know.

When it is NOT worth it

Being honest about the tradeoff means admitting where TS gets in the way. It is not worth it for:

  • A throwaway weekend prototype, where the goal is to validate an idea in an afternoon and toss it. Fighting the type system here is wasted effort — the code won't survive until Monday.
  • A one-off script, run once and deleted: a .js pasted into the terminal does the job.
  • Exploration moments inside a typed project, where you still don't know the shape of the data. Here, a temporary any or // @ts-expect-error is acceptable — as long as they get typed again once the shape stabilizes.

The dividing line is simple: will this code be read again? If yes, types pay off. If it is genuinely ephemeral, don't force it.

JSDoc: the middle ground with no build

There is a third path few people remember. You can get type checking in plain .js files, with no build step at all, using JSDoc plus // @ts-check:

// @ts-check

/** @param {string} name @param {number} age */
function greet(name, age) {
  return `${name} is ${age} years old`;
}

greet("Ana", "30"); // error: '30' is not a number

VS Code reads this and gives you the same red underlines as TS, with zero build configuration. It is an excellent middle ground for a small script where you want the safety net without even creating a tsconfig. It doesn't scale as well to complex types (generics get verbose in JSDoc), but for the small case it is underrated.

My opinion: when in doubt, use TS

After migrating more legacy JS than I would like, my position is blunt: when in doubt, start typed. The reason is less technical and more about how projects behave. The "small project" almost always grows — that script meant to run once becomes a cron, then gets an endpoint, then becomes the base of a product. And migrating legacy JavaScript to TypeScript later is genuinely worse than having started typed: you inherit implicit decisions, undocumented data shapes, and hundreds of any that need to be unwound one by one.

Starting typed costs minutes. Migrating later costs days. The asymmetry is too large to bet against.

The one honest exception is the real weekend prototype. There, don't fight the type system — if an any unblocks you, use it and move on. The goal is to learn whether the idea is any good, not to build a monument. For that case, and only that one, loose JS is still the right tool. If you are just getting started and want to firm up the base before adding types, it's worth revisiting what JavaScript is first — TypeScript makes a lot more sense once the JS underneath is already familiar.

Frequently asked questions

Does TypeScript make the code slower?

Not at runtime. The types are erased at compile time — the JavaScript that runs is the same you would write by hand, with no checks at execution time. The only cost is at build/dev, and tools like tsx, vite, and bun have made that cost almost imperceptible in small projects.

Do I need a complicated tsconfig?

No. A minimal tsconfig.json with "strict": true and a target already covers most small cases. Most configuration complexity comes from monorepos, custom paths, and bundler integrations — none of which is necessary for a script of a few hundred lines.

Is it worth converting an existing small JS project?

Usually yes, if it is going to stay alive. You can migrate incrementally: rename .js to .ts one file at a time, tolerate temporary any, and tighten the types gradually. If the project is frozen and nobody will touch it, leave it — migrating dead code doesn't pay.

TypeScript or JSDoc for a small script?

JSDoc with // @ts-check is great if you want checking with no build step and the types are simple. As soon as generics, complex unions, or many shared types show up, plain TS gets cleaner and less verbose. Start with JSDoc if the build aversion is the blocker; switch to TS when the verbosity starts to bother you.

What to take away

The cost of TypeScript on a small project has shrunk to the point where it is no longer a serious argument: the build step became a flag, and the benefits of autocomplete, safe refactor, and bugs caught early show up well before 200 lines. Reserve loose JavaScript for what is genuinely disposable — weekend prototypes and one-off scripts. For everything else, start typed: it is cheaper to pay minutes now than days of migration later, when the "small project" inevitably grows.

RD
Author
Rafael Duarte
Backend developer with a background in fintech and B2B SaaS — worked on teams that scaled APIs from zero to millions of requests. Carries enough production scars to hold strong opinions on tools, patterns and architecture decisions. Not an academic: he read the UUID RFC when he had to choose between v4 and v7 for a write-heavy table.
View profile