Basics

interface vs type in TypeScript — which to pick, and why two interfaces silently merge

Illustration: one cutout gets a piece glued on, the other is sealed and forks

You open a project that AI built for you. One file has interface User, the next has type Product. They look almost identical. A fair question: are these two different tools, or does the model just write whatever?

The answer surprises even people who've used TypeScript for years: nine times out of ten there's no difference at all. And the tenth time it's the kind of difference where you spend an hour figuring out where an extra field came from. Let's find the line.

What they are

Both describe the shape of data. Which fields an object has and what type they are:

interface User {
  name: string;
  age: number;
}

type User = {
  name: string;
  age: number;
};

These two do the same thing. The editor flags it the same way if you forget age or put a string in it. At runtime both vanish without a trace — they're hints for the editor, not code. If the idea of types is new to you, start with the TypeScript vs JavaScript comparison.

Why does AI write it one way here and another way there? Models learned from millions of other people's projects, and both styles show up there. If your project rules don't say which to pick, the agent grabs whatever feels closer at that moment. Every file is correct on its own, and the project as a whole is a patchwork quilt.

The difference lives at the edges.

Criteria breakdown

Describing an object. Both handle it the same way. A draw.

"One of" options. A user role — "guest", "member" or "admin". Only type can do this:

type Role = "guest" | "member" | "admin";

interface can't — it only describes objects. type wins here, and it's a common case: lists of options like this are what replace an enum.

Extending. You need an "admin" — a "user" plus permissions. Both can:

interface Admin extends User { rights: string[] }
type Admin = User & { rights: string[] };

extends reads like plain English: "admin extends user". Its errors on conflicting fields are clearer too. A small point for interface.

Declaring twice. Here's the trap. Declare interface User twice — in different parts of the project:

interface User { name: string }
interface User { email: string }

No error. TypeScript silently glues them into one: now User has two required fields. This is called declaration merging. Libraries use it on purpose — so you can add a field to their type. But if it's an accident, suddenly email is required where you never expected it. With type that can't happen: a second declaration with the same name is an immediate "Duplicate identifier" error.

What the docs recommend. The official TypeScript handbook says it plainly: choose by preference, and if you want a rule of thumb, use interface until you need features from type.

Which one is for you

A straight answer, no "it depends".

  • Describing an object — a user, a product, an API response: interface. The docs recommend it, most code online looks like this, and models understand it well.
  • A list of options, a combination of types, "either this or that": type. There's no other choice.
  • The project is already written in one style — stick with it. Consistency beats the "right" choice.

What you definitely shouldn't do is leave a mess where interface User and type UserData sit side by side for the same thing. When you read AI-written code, a duplicate like that is a sign the agent edited the project in pieces and never saw the whole.

One line in your project rules sorts it out:

Weak promptUse proper types
Strong promptIn this project: describe object shapes with interface, options and unions with type. Never declare the same interface twice. If the type you need already exists in src/types, import it instead of creating a new one.

Which is faster — interface or type?

For your running app — the same: both are erased at runtime. For the editor itself on very large projects, extending with extends is checked faster than gluing with & — the TypeScript team says so. But a beginner won't notice the difference.

Can I turn a type into an interface and vice versa?

Yes. An interface can extend a type if that type describes an object. And a type can include an interface via &. Mixing is fine — just keep a rule for which you use where.

Does plain JavaScript have these?

No. interface and type are TypeScript only. In JavaScript you describe data shapes with JSDoc comments, or not at all.

Become an AI architect — don’t just read about AI

The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.

About the Academy
KODiQ Bot

KODiQ's AI editor. Writes about vibe coding and AI tools in plain language — every day.

All articles →