What is TypeScript? (and why your AI writes it by default)

What it actually is

TypeScript is JavaScript with extra syntax for types. A type describes what shape a piece of data has: name: string says this variable holds text, price: number says that one holds a number, and a bigger type can spell out every field an object carries. Everything you know about JavaScript still applies; the annotations sit on top.

Think of a type as the shape of an electrical plug. A socket accepts one shape, so a mismatch shows up the instant you try to plug in, not as smoke behind the wall a week later. Types do the same for data: hand text to a function that was promised a number, and the checker refuses on the spot, while you build, before any user sees it.

Browsers can’t run TypeScript. A compile step converts your .ts files into plain JavaScript and strips out every annotation, and that stripped output is what ships. The types exist only while you build, as a checking layer. That’s why the running app behaves exactly like a JavaScript app: it is one.

Why your AI just did this

Two reasons. The first is defaults. The starters your agent reaches for come with TypeScript wired in. create-next-app installs and configures it automatically, tsconfig.json included, so when Cursor or Claude Code scaffolds a new app, the .tsx files are there before you’ve expressed an opinion.

The second reason is self-interest. Your agent writes a lot of code fast, and the type checker reviews every line of it for free. If the agent calls a function with the wrong arguments, or assumes an API response carries a field it doesn’t, the checker flags the exact file and line at build time. Agents are good at reading those flags: they see the error, fix it, rerun, often before you notice. The annotations also work as documentation the agent can trust. Instead of guessing what user contains, it reads the type and knows.

When you’ll run into it

The first sighting is usually file extensions: .ts files, .tsx for React components, and a tsconfig.json in the project root. If those are in your repo, you’re writing TypeScript, whether you chose it or not.

The classic ambush is the build that fails after the app seemed fine. You ran npm run dev for days and clicked through every screen. Then npm run build, or a Vercel deploy, dies with something like:

app/page.tsx:14:7 - error TS2322: Type 'string | undefined' is not assignable to type 'string'.

Nothing broke overnight. Many dev setups skip type checking to stay fast: Vite transpiles your TypeScript but never checks it, and its docs tell you to run the check separately. Production builds are stricter, and Next.js fails next build on any type error. The mistake was there all along; the build is the first process that looked. Build vs dev covers the wider version of that split.

Reading the error takes ten seconds once you know the layout. File (app/page.tsx), line and column (14:7), an error code (TS2322), then the sentence. “X is not assignable to Y” means your code produced X-shaped data where Y-shaped data was promised. Here, the value might be text or might be undefined (missing), and the receiving code insists on text that is always there. You don’t have to solve it; copy the whole message to your agent verbatim.

You’ll also meet type errors as red underlines in VS Code or Cursor while you type, collected in the Problems tab. Same errors, caught earlier. They’re separate from linter warnings: a linter judges style and suspicious patterns, the type checker judges whether data shapes line up.

What to check

• Run npx tsc --noEmit before deploying; it runs the same shape check the build does, without producing any files, so you find the error while it’s cheap
• Paste the whole type error to your agent verbatim: file path, line number, error code, both quoted type names. Paraphrasing strips the diagnosis
• Find the two quoted types in the message. The first is what your code produced, the second is what the receiving code expects, and the fix belongs on whichever side is wrong about reality
• Treat | undefined in an error as real information: some data can be missing, like an optional field or a fetch that can fail. Ask the agent to handle the missing case, not to assert it away
• Push back when a fix uses any, an as cast, or @ts-ignore. Those mute the checker for that spot; the mismatch survives and resurfaces in production
• Refuse ignoreBuildErrors: true in next.config.ts. Next.js’s own docs flag it as dangerous, and it silences every future type error along with this one

Say it like a dev

Instead of: “the app worked fine yesterday and now the deploy is broken” Say: “npm run build fails with TS2322 in app/page.tsx line 14: Type ‘string | undefined’ is not assignable to type ‘string’. Handle the undefined case instead of casting it away.”

Instead of: “make the red squiggles go away” Say: “Fix this type error properly: no any, no as casts, no @ts-ignore. If the type itself is wrong, correct the type.”

Instead of: “TypeScript keeps complaining, can we switch to normal JavaScript?” Say: “Keep TypeScript, but before you fix this error, explain in plain language what shape mismatch it’s pointing at.”