What is the difference between useExisting and useClass when aliasing a provider in NestJS?

Q: What is the difference between useExisting and useClass when aliasing a provider in NestJS?

// useClass — two SEPARATE instances even for the same class { provide: 'LOGGER_A', useClass: LogService } // instance 1 { provide: 'LOGGER_B', useClass: LogService } // instance 2 — different object // useExisting — same instance, two tokens { provide: LogService, useClass: LogService } // instance 1 { provide: 'LEGACY_LOG', useExisting: LogService } // same object as above useClass — when you want an independent instance with its own state. useExisting — when you want two token names to point to the exact same runtime object. useExisting is useful for maintaining backward-compatible tokens in evolving APIs. useExisting requires the referenced token to already be registered in the same module or an imported module.

Difficulty: 5/10

provider aliasing, dependency injection, NestJS modules

useClass with a class always creates a new independent instance managed by the container. useExisting resolves and returns the same singleton instance of the referenced token — no new instantiation occurs. Use useExisting when you need backward-compatible aliases without duplicating state.

useClass vs useExisting — instance behavior

When to use each:

1
useClass — when you want an independent instance with its own state.
2
useExisting — when you want two token names to point to the exact same runtime object.
3
useExisting is useful for maintaining backward-compatible tokens in evolving APIs.
4
useExisting requires the referenced token to already be registered in the same module or an imported module.

Scenario Questions

0-2 years experience

1You have a service A that depends on an interface IMyService. How would you configure the module to provide a concrete class MyService using useClass, and what would you change to make it use an existing provider instead?
2If you alias a provider with useExisting, what happens at runtime when another class injects the token? Explain the flow compared to useClass.
3Suppose you accidentally used useExisting when you intended to create a new instance. What would you observe in the behavior of the injected service?

Follow-up Questions

Can you give an example where useExisting is clearly better than useClass?
How does NestJS manage the lifecycle of a provider that is aliased with useExisting?
What testing considerations arise when you alias a provider with useExisting?