Mongoose and TypeScript: How to Type Your Models Without Writing Everything Twice

Every MERN project that adds TypeScript eventually asks the same question: do I write an interface next to this schema, or does Mongoose figure the type out for me? For years the honest answer was "kind of, but not really," and a lot of the advice still floating around online reflects that older, messier reality, Medium posts from 2019 to 2022 with a bolted-on update note added later saying Mongoose fixed this, without the rest of the post being rewritten around it.

Here's where things actually stand today, and where the remaining sharp edges are, the ones nobody bothers to write up because they only show up once you're deep into a real app: typing instance methods, typing a populated field, and knowing when inference genuinely isn't the right tool.

If you're mid-upgrade rather than starting fresh, some of what breaks TypeScript-wise is covered separately in our Mongoose 9 migration guide, worth a look if a tsc run that was clean yesterday isn't clean today.

The old-school pattern, and still the most common one in codebases that adopted TypeScript before Mongoose's own types matured, looks like this. You write the shape once as an interface, then again as the schema definition that actually enforces it at runtime:

You're writing the shape twice, in two syntaxes that don't check each other. Add a field to the schema and forget the interface, or the other way around, and TypeScript doesn't catch it, because as far as the type checker is concerned IUser is correct, it's just wrong relative to what actually gets saved to MongoDB.

This is exactly the kind of bug TypeScript exists to prevent, and it slips through anyway because the two definitions are allowed to drift. A field renamed in the schema during a refactor leaves a stale, now-meaningless property sitting in the interface. A field added to the schema for a new feature doesn't show up on the type until someone remembers to add it manually, so it silently types as any wherever it leaks through, or worse, the property access on a strict type just gets flagged as an error that someone reflexively suppresses instead of investigating.

None of this is a Mongoose problem specifically, it's what happens any time a data shape is declared in two unrelated places. The fix isn't discipline or code review, it's removing the second declaration entirely and deriving it from the first.

Mongoose ships a built-in utility type, InferSchemaType, that reads a schema definition and produces the matching TypeScript type automatically. It's been the officially recommended pattern for a while now, and it's the right default for new code:

The schema is now the single source of truth. Change a field's type in the schema and the derived User type updates on the next compile, automatically, with no second file to remember. This is the correct amount of effort for the duplication problem: delete one of the two places, keep the one that actually does something at runtime.

But User here is just the plain data shape, and that's a narrower thing than most people expect. It doesn't know about .save(), it doesn't know about ._id, and it doesn't know about anything Mongoose attaches to a document once it comes back from the database. If you try to call user.save() on something typed as plain User, TypeScript will correctly complain that save doesn't exist on that type, because as far as the inferred type is concerned, it's a description of the data, not a live document.

This is the piece most quick tutorials skip entirely, which is exactly why it causes so much confusion downstream. HydratedDocument<T> wraps a plain inferred type with everything Mongoose adds at runtime once a document is created or comes back from a query: _id, save(), populate(), toObject(), and the rest of the Document interface.

Skip this step and you'll spend an afternoon fighting TypeScript errors on totally ordinary Mongoose calls, save() doesn't exist, _id doesn't exist, and the instinct is usually to reach for as any on the query result rather than realize a two-line type wrapper was the actual fix. model<UserDocument>(...) is what makes every downstream query on UserModel come back already typed as UserDocument, so this only needs setting up once per model, not once per query.

InferSchemaType reads the field definitions, and only the field definitions. Custom instance methods and static methods attached to a schema live outside that object entirely, so they need to be typed explicitly and threaded through the schema's own generic parameters. This is the step that trips people up because the generics reference the schema's own inferred type, which looks circular the first time you write it, but it's the documented pattern and it does work:

Static methods, the ones called on the model itself rather than on a document instance, follow the same idea but attach through the schema's Model generic instead of the Methods one:

This is the one that causes the most genuine confusion, and there's an open issue on Mongoose's own GitHub repository where developers are stuck on exactly this, with no canonical fix linked from anywhere easy to find. By default, a referenced field types as its raw ObjectId, even after you've called .populate() on it at runtime:

The reason is structural, not a bug: .populate() is a database-level operation that changes the shape of the result at query time, and TypeScript's static type system has no way to see that a specific call to .populate("owner") changed owner from an ObjectId into a full User document. The type of group was already fixed at the point Group was defined. You have to tell TypeScript explicitly, using the generic parameter .populate() itself accepts for exactly this purpose:

This scales the same way for populating multiple fields, or an array of references, chain multiple .populate() calls and pass each one its own generic, or intersect the shapes if you're populating in one call with an array of paths. If members is an array of refs, the populated shape is an array too:

Our MongooseTS tool detects any field with a ref option in a pasted schema and generates this exact populate snippet automatically, using your actual field and model names instead of a generic placeholder, so you don't have to reconstruct the syntax from memory every time.

The same underlying issue applies to virtuals: they're computed at access time from a getter function, not stored in the database, so they're not part of the raw field definitions InferSchemaType reads either. If you want a virtual like fullName to show up as a typed property on your document, you need to add it to the type explicitly, the same way methods and statics get threaded through, this time via the schema's fourth generic parameter for virtuals:

It's worth calling out that virtuals aren't included in the result of .toObject() or .toJSON() unless you explicitly set { virtuals: true } in the schema's toObject/toJSON options, that's a runtime behavior detail, not a typing one, but it's the thing people usually hit right after finally getting the type correct: the type says fullName exists, and then it's missing from the JSON response because the schema option wasn't set.

Inference is the right default, not a rule without exceptions. There are two situations where writing the interface first, and shaping the schema to match it, is still the better call.

The first is a genuinely conditional shape, most commonly a discriminator pattern where a field's type depends on the value of another field. InferSchemaType derives a single flat shape from a single schema definition, it doesn't reason about Mongoose discriminators producing different sub-shapes per kind:

The second case is API-contract-first design: when the interface needs to exist before the schema does, because it's shared with a frontend, an OpenAPI spec, or another service, and the schema is being written to satisfy an already-agreed-upon shape rather than the other way around. In that situation, inferring from the schema would mean the contract lives implicitly inside a Mongoose-specific file, which is the wrong place for something other parts of the system depend on.

Outside of those two cases, treat inference as the default and reach for a hand-written interface only when you can point to a specific reason it's needed, not as a habit carried over from before InferSchemaType existed.

Putting all of the above together: a schema, a model, and an Express route that queries and populates a reference, fully typed from the schema definition down to the response.

Nothing in this example is hand-maintained twice. The schema is the only place the shape is written down, InferSchemaType derives the data type from it, HydratedDocument adds the document behavior, and the .populate() generic covers the one spot TypeScript genuinely can't infer on its own.

Reading through generic examples only gets you so far, the interesting edge cases are always in your actual schema, not a toy one. If you want to see everything above applied to your own fields, paste your schema into MongooseTS and get the generated interface back instantly, either as a plain interface or the InferSchemaType style shown throughout this guide, with a ready-to-paste .populate() snippet for any ref field it finds. It runs entirely in your browser, nothing you paste is sent anywhere.

If your actual pain point right now is an aggregation pipeline rather than a model's shape, our PipelineExplain tool walks a MongoDB aggregation pipeline stage by stage in plain English, no database connection required, the other Mongoose-adjacent tool on the site.