@semocodev/fastify-typeorm

Fastify v5 plugin for TypeORM 1.x. Decorates your Fastify instance with one or more TypeORM DataSource instances, with graceful shutdown on fastify.close().

Requirements

| Peer dependency | Version | | --------------- | ---------- | | fastify | >=5.0.0 | | typeorm | >=1.0.0 | | Node.js | >=22.0.0 |

Installation

npm install @semocodev/fastify-typeorm typeorm fastify
# plus your database driver, e.g.:
npm install pg              # PostgreSQL
npm install mysql2          # MySQL / MariaDB
npm install better-sqlite3  # SQLite

Note: TypeORM requires reflect-metadata. Import it once at the top of your app entry point before any entity imports:

import 'reflect-metadata'

Usage

Single DataSource (direct mode)

Pass DataSourceOptions directly or a pre-built DataSource via connection. fastify.orm is the DataSource instance.

import 'reflect-metadata'
import Fastify from 'fastify'
import fastifyTypeorm from '@semocodev/fastify-typeorm'
import { User } from './entities/User.js'

const fastify = Fastify()

// From options — plugin calls new DataSource(opts).initialize()
await fastify.register(fastifyTypeorm, {
  type: 'postgres',
  host: 'localhost',
  port: 5432,
  username: 'app',
  password: 'secret',
  database: 'mydb',
  entities: [User],
  synchronize: false,
})

fastify.get('/users', async () => {
  return fastify.orm.getRepository(User).find()
})

await fastify.listen({ port: 3000 })

Pre-built DataSource

import { DataSource } from 'typeorm'

const dataSource = new DataSource({
  type: 'postgres',
  // ...
})

await fastify.register(fastifyTypeorm, { connection: dataSource })

The plugin calls initialize() only if the DataSource is not yet initialized.

Multiple DataSources (namespace mode)

Use the namespace option. fastify.orm[namespace] returns the corresponding DataSource.

import 'reflect-metadata'
import Fastify from 'fastify'
import fastifyTypeorm from '@semocodev/fastify-typeorm'

const fastify = Fastify()

await fastify.register(fastifyTypeorm, {
  namespace: 'primary',
  type: 'postgres',
  host: 'localhost',
  database: 'main_db',
  entities: [User],
})

await fastify.register(fastifyTypeorm, {
  namespace: 'analytics',
  type: 'postgres',
  host: 'analytics-host',
  database: 'analytics_db',
  entities: [Event],
})

fastify.get('/report', async () => {
  const users = await fastify.orm['primary'].getRepository(User).find()
  const events = await fastify.orm['analytics'].getRepository(Event).find()
  return { users, events }
})

TypeScript

The module augments FastifyInstance with:

interface FastifyInstance {
  orm: DataSource | Record<string, DataSource>
}

For direct mode, fastify.orm is typed as DataSource. For namespaced mode, use fastify.orm['namespace'] — typed as DataSource.

The package also exports helper interfaces if you want stronger typing in your own code:

import type {
  FastifyTypeormDirect,
  FastifyTypeormNamespaced,
} from '@semocodev/fastify-typeorm'

// Direct mode — use this in route handlers or plugins that expect orm to be a DataSource
function myPlugin(fastify: FastifyInstance & FastifyTypeormDirect) {
  fastify.orm.getRepository(User) // typed as DataSource
}

// Namespaced mode
function myOtherPlugin(fastify: FastifyInstance & FastifyTypeormNamespaced) {
  fastify.orm['primary'] // typed as DataSource
}

Plugin registration

This plugin is wrapped with fastify-plugin, which means it breaks encapsulation: the fastify.orm decorator is available on the root instance and all child scopes, regardless of where register() is called.

// Even registered inside a scoped plugin, orm is visible everywhere
await fastify.register(async (app) => {
  await app.register(fastifyTypeorm, { type: 'sqlite', database: ':memory:' })
  // app.orm is accessible here...
})

// ...and also here, on the parent scope
fastify.get('/ping', async () => fastify.orm.isInitialized)

Note: Fastify processes register() calls asynchronously. Always await fastify.ready() (or await fastify.listen()) before accessing fastify.orm outside a route or hook handler.

await fastify.register(fastifyTypeorm, { /* opts */ })
await fastify.ready() // ensures the plugin has finished initializing

console.log(fastify.orm.isInitialized) // true

Graceful shutdown

All registered DataSources are automatically destroyed when fastify.close() is called (via the onClose hook), including in namespaced mode.

Differences from fastify-typeorm-plugin (inthepocket)

| Feature | inthepocket/fastify-typeorm-plugin | @semocodev/fastify-typeorm | | -------------------- | ------------------------------------ | --------------------------- | | TypeORM API | createConnection() (removed in v1) | DataSource (v1.x) | | Fastify version | v3/v4 | v5+ | | Namespace support | ❌ | ✅ | | Pre-built DataSource | ❌ | ✅ | | TypeScript-first | Partial | ✅ Full | | Maintained | ❌ Archived | ✅ |

License

MIT