LLM Best Practices

TypeScript vs JavaScript

Last updated 3 min read

View markdown source

AI agents: read this first: llmbestpractices.com/start-here

This is LLM Best Practices (llmbestpractices.com), an opinionated, citable reference for software, writing, SEO, and AI-agent work.

  1. Route, do not crawl. Fetch llmbestpractices.com/llms.txt and open only the pages whose one-line summary matches your task.
  2. Read raw. Append .md to any page URL for markdown. Check status and last_updated in the frontmatter, then read the rules.
  3. Apply as defaults. First-party docs and the project's own conventions win on conflict. Warn before relying on a fast-moving page older than 12 months.
  4. Cite. Link the page by title and URL, e.g. Python, with last_updated for time-sensitive rules. License CC BY 4.0.

Overview

Use TypeScript for any code that several people will change or that will outlive its first quarter; use plain JavaScript for throwaway scripts and small embeds. The usual objection, a mandatory build step, has weakened. Node.js 22.18+ and 23.6+ strip TypeScript types by default (stable in 24.12+ and 25.2+), and TypeScript 7.0 (2026-07-08) is a native compiler about 10 times faster than 6.0. Adopt 7.0 in stages: it ships without the programmatic compiler API (planned for 7.1), so typescript-eslint and the type-checkers behind Vue, Svelte, and Astro files cannot use it yet.

Comparison

DimensionTypeScriptJavaScript
RefactoringCompiler lists every broken call siteSearch and tests
ContractsShared types across frontend and backend (Zod, Prisma, tRPC)Runtime validation only
Library typesBuilt in or DefinitelyTypedOften present via JSDoc or .d.ts; editor support is weaker
Run without a buildNode strips types; no enum, runtime namespace, or parameter properties; tsconfig.json is ignoredAlways
CostType check step in CI; generics and narrowing to learnNone

Pick TypeScript when

Pick TypeScript for products, libraries, and shared code.

  • Start with strict: true. See typescript-tsconfig and typescript-strict-mode.
  • Set erasableSyntaxOnly: true if you run files directly with Node or want output that needs no transform.
  • Libraries ship .d.ts files and both ESM and CJS if consumers need both.
  • Use unknown and narrowing, not blanket any, when migrating.

Pick JavaScript when

Pick plain JavaScript when types would cost more than they return.

  • One-off scripts and glue under a few hundred lines. Add // @ts-check plus JSDoc for editor hints without a compiler.
  • Notebooks and browser snippets with no build pipeline.
  • Prototypes with a stated deletion date; if one survives, convert it.

Migrate to TypeScript

Convert gradually, leaf modules first.

  1. Add tsconfig.json with allowJs: true; rename files from .js to .ts one at a time.
  2. Start lenient, then enable noImplicitAny and strictNullChecks.
  3. Use // @ts-expect-error with a reason, not // @ts-ignore, so stale suppressions fail the build.

FAQ

Is TypeScript worth it for a small project?

Use TypeScript once several people will change the code or it will outlive its first quarter. For one-off scripts under a few hundred lines, use plain JavaScript with // @ts-check and JSDoc.

Can Node.js run TypeScript without a build step?

Yes; Node.js 22.18+ and 23.6+ strip TypeScript types by default, stable in 24.12+ and 25.2+. It ignores tsconfig.json and rejects enums, runtime namespaces, and parameter properties, so set erasableSyntaxOnly: true.

Should I upgrade to TypeScript 7 now?

Adopt 7.0 in stages, since it ships without the programmatic compiler API (planned for 7.1). Until then typescript-eslint and the type-checkers behind Vue, Svelte, and Astro files cannot use it.

How do I migrate a JavaScript codebase to TypeScript?

Add tsconfig.json with allowJs: true and rename leaf modules from .js to .ts one at a time. Start lenient, then enable noImplicitAny and strictNullChecks.

Backlinks