I’ve been on the lookout for a replacement for typeorm for some time and mikro orm looks promising.

The quickstart does not have enough information to get the tool running end-to-end in a typescript environment, so the longer Getting Started - Chapter 1 is required reading too. Even so, there were some additional gotchas that meant a bit of googling, a bit of debugging, and a few hours in total to get the tool running. These commits (one, two) show what was changed to add mikro-orm.

I had to swap out tsx for ts-node, considering mikro (like typeorm) also uses typescript decorators that esbuild does not support. There’s a bunch of package.json/tsconfig.json settings that need to be correct for this to work, and ultimately the only way I could make ts-node happy was by starting the app with node --experimental-specifier-resolution=node --loader ts-node/esm ./src/index.ts. This however does not allow the tool to detect correctly that ts-node is in use (source) at dev time, and confusingly it will return a No entities found error as it’s actually looking in dist for the entities and not src. Explicitly setting { tsNode: true } in config solves for this though finding this solution required debugging into the library and before fixing it my app was silently exiting without any error message.

The tool has a CLI and one of it’s features, which, once installed is executed via npx mikro-orm, however, in the case of typescript it must be executed via npx mikro-orm-esm. One of the nice features of the CLI is that it confirms your configuration. Although a working configuration at CLI time can still stuffer from the No entities found error at runtime without the fix above.

$ npx mikro-orm-esm debug
Current MikroORM CLI configuration
 - dependencies:
   - mikro-orm 6.1.9
   - node 20.10.0
   - knex 3.1.0
   - pg 8.11.3
   - typescript 5.4.2
 - package.json found
 - ts-node enabled
 - searched config paths:
   - /home/stafford/git/spacetraders-again/src/mikro-orm.config.ts (found)
   - /home/stafford/git/spacetraders-again/mikro-orm.config.ts (not found)
   - /home/stafford/git/spacetraders-again/src/mikro-orm.config.js (not found)
   - /home/stafford/git/spacetraders-again/mikro-orm.config.js (not found)
 - configuration found
 - database connection succesful
 - `tsNode` flag explicitly set to true, will use `entitiesTs` array (this value should be set to `false` when running compiled code!)
 - could use `entities` array (contains 0 references and 1 paths)
   - /home/stafford/git/spacetraders-again/dist/**/*.entity.js (not found)
 - will use `entitiesTs` array (contains 0 references and 1 paths)
   - /home/stafford/git/spacetraders-again/src/**/*.entity.ts (found)

There is a heap of documentation and google might be required to find docs specific to a given error message. An example is this monster stackoverflow answer where the author of the tool explains one of the error messages I encountered. There’s almost a little too much to learn, such that the early getting started documentation almost presumes you can make decisions about topics that you haven’t yet learned about, for example the Metadata Providers and ts-morph which is used to infer more schema via type information rather than decorator annotations.

Once the CLI was configured, and the separate migrations library installed and referenced, migrations appeared to Just Work™️. Once runtime was configured, read/write appeared simple enough. With the gotchas out of the way and the setup time spent, I’m looking forward to using the query functionality further as I build out more of my app.