[discuss] docs/on-boarding/ux

After evaluating mikro-orm (MO) yesterday, I wanted to toy a bit around with MO but the actual experience of getting started was rocky. So, it’s an issue about your docs and how to get started and maybe a reason why MO doesn’t take off despite having the best architecture.

First I couldn’t get passed this:

7:19:59 AM - File change detected. Starting incremental compilation...
api    |
api    | node_modules/mikro-orm/dist/connections/AbstractSqlConnection.d.ts(1,8): error TS1259: Module '"/app/node_modules/knex/types/index"' can only be default-imported using the 'esModuleInterop' flag
api    | node_modules/mikro-orm/dist/query/QueryBuilderHelper.d.ts(1,8): error TS1259: Module '"/app/node_modules/knex/types/index"' can only be default-imported using the 'esModuleInterop' flag
api    |
api    | 7:19:59 AM - Found 2 errors. Watching for file changes.

My code:

import { MikroORM } from 'mikro-orm'
import { MongoDriver } from 'mikro-orm/dist/drivers/MongoDriver'

const main = async () => {
  const orm = await MikroORM.init({
    entitiesDirs: ['./build/**/entities'],
    driver: MongoDriver,
    driverOptions: {
      host: 'db',
      user: 'root',
      password: '<mypass>',
    },
  })
}

main()

• So, the reason I opted for MO was that the Mongo implementation should be better than the one from TypeORM (in particular relations) but when I see that the systems tries to get abstract SQL drivers and Knex => why all this baggage if I just want Mongo? Besides, I know that I have to set the esModuleInterop now but I would have be nice to have a note about this because every error early on just increases the risk that people bail out

Then:

• The docs have to clearly state how to import MikroORM. On the node server side people are still used to const/require and a default import; no big thing but still; you want to sell your lib, you want to get people into the funnel but if I have to ‘think’ to just get started I will opt out; it took me some time because your docs state nowhere how to import MikroORM

[B4nan]

I guess we can close this, added the note about esModuleInterop and type in the docs. Feel free to send more suggestions, ideally as concrete as possible.

[B4nan]

Besides, do you think that supporting SQL is important? I mean, TypeORM excels in SQL-land, is still a bit maintained and supporting many different DBs is challenging (even Knex is full of inconsistencies).

Yes it is, I am sure there are more SQL users currently. Also I would not say that TypeORM excels in SQL land, I feel like the problems with TypeORM are pretty much driver independent. The point is that MikroORM gives you different approach (UoW), that is even more important for SQL than for mongo (although now we have transactions support in mongo too).

Really? It would be a breaking change then (just added type: ‘mongo’ 😉

Yes, that is why I said it will change in v4 and not in v3.5. Its a breaking change, therefore it will be part of major release. Having default value for this was a wrong decision.