Metadata Providers

As part of entity discovery process, MikroORM uses so called MetadataProvider to get necessary type information about your entities' properties. There are 3 built-in metadata providers you can use:

You can also implement custom metadata provider by extending abstract MetadataProvider class.

TsMorphMetadataProvider

With TsMorphMetadataProvider MikroORM will use ts-morph to read TypeScript source files of all entities to be able to detect all types. Thanks to this, defining the type is enough for runtime validation.

To use it, first install the @mikro-orm/reflection package.

import { TsMorphMetadataProvider } from '@mikro-orm/reflection';

await MikroORM.init({
  metadataProvider: TsMorphMetadataProvider,
  // ...
});

If you use folder-based discovery, you should specify paths to the compiled entities via entities as well as paths to the TS source files of those entities via entitiesTs. When you run the ORM via ts-node, the latter will be used automatically, or if you explicitly pass tsNode: true in the config.

When running via node, .d.ts files are used to obtain the type, so we need to ship them in the production build. TS source files are no longer needed (since v4). Be sure to enable compilerOptions.declaration in your tsconfig.json.

After the discovery process ends, all metadata will be cached. By default, FileCacheAdapter will be used to store the cache inside ./temp folder in JSON files.

You can generate production cache via CLI command mikro-orm cache:generate.

You can implement custom cache adapter by implementing CacheAdapter interface.

ReflectMetadataProvider

ReflectMetadataProvider uses reflect-metadata module to read the type from decorator metadata exported by TypeScript compiler.

You will need to install reflect-metadata module and import at the top of your app's bootstrap script (e.g. main.ts or app.ts).

import 'reflect-metadata';

Next step is to enable emitDecoratorMetadata flag in your tsconfig.json.

As this approach does not have performance impact, metadata caching is not really necessary.

await MikroORM.init({
  metadataProvider: ReflectMetadataProvider,
  // ...
});

Limitations and requirements

Explicit types

Type inference is not supported, you need to always explicitly specify the type:

@Property()
createdAt: Date = new Date();

Collection properties and Identified references

You need to provide target entity type in @OneToMany and @ManyToMany decorators:

@OneToMany(() => Book, b => b.author)
books = new Collection<Book>(this);

@ManyToOne(() => Publisher, { wrappedReference: true })
publisher!: IdentifiedReference<Publisher>;

Optional properties

Reading property nullability is not supported, you need to explicitly set nullable attribute:

@Property({ nullable: true })
prop?: string;

Enums

By default, enum is considered as numeric type. For string enums, you need to explicitly provide one of:

• reference to the enum (which will force you to define the enum before defining the entity)

  @Enum(() => UserRole)
  role: UserRole;
• name of the enum (if it is present in the same file)

  @Enum({ type: 'UserRole' })
  role: UserRole;
• list of the enum items

  @Enum({ items: ['a', 'b', 'c'] })
  role: UserRole;

Circular dependencies

Reading type of referenced entity in @ManyToOne and @OneToOne properties fails if there is circular dependency. You will need to explicitly define the type in the decorator (preferably via entity: () => ... callback).

@ManyToOne({ entity: () => Author })
author: Author;

There can be recursion issues when you define multiple entities (with circular dependencies between each other) in single file. In that case, you might want to provide the type via decorator's type or entity attributes and set the TS property type to something else (like any or object).

Additional typings might be required

You might have to install additional typings, one example is use of ObjectId in MongoDB, which requires @types/mongodb to be installed.

JavaScriptMetadataProvider

JavaScriptMetadataProvider is deprecated, use EntitySchema instead.

This provider should be used only if you are not using TypeScript at all and therefore you do not use decorators to annotate your properties. It will require you to specify the whole schema manually.

await MikroORM.init({
  metadataProvider: JavaScriptMetadataProvider,
  // ...
});

You can read more about it in Usage with JavaScript section.