# ForwardReference

**Kind:** Interface

**Source:** [`packages/common/interfaces/modules/forward-reference.interface.ts`](https://github.com/nestjs/nest/blob/master/packages/common/interfaces/modules/forward-reference.interface.ts#L1)

**Part of:** [Common](subsystem-packages-common)

`ForwardReference<T>` is a lightweight wrapper interface used to defer access to a value until it is needed. It is typically used to resolve circular dependencies between modules, providers, or other components that cannot be referenced directly during initial declaration.

## Properties

| Property | Type |
|---|---|
| `forwardRef` | `T` |

## Diagram

```mermaid
graph LR
  A[Module or Provider A] --> B[ForwardReference<T>]
  B --> C[forwardRef: T]
  C --> D[Deferred Module or Provider B]
  D -. circular dependency .-> A
```

## Usage

```ts
import type { ForwardReference } from './forward-reference.interface';

interface UserModule {
  name: string;
}

const userModuleReference: ForwardReference<UserModule> = {
  forwardRef: {
    name: 'UserModule',
  },
};

// Resolve the deferred reference when needed.
const userModule = userModuleReference.forwardRef;

console.log(userModule.name); // "UserModule"
```

## AI Coding Instructions

- Use `ForwardReference<T>` when a dependency must be declared before its final value can be resolved, especially for circular module relationships.
- Keep the generic type `T` specific so consumers receive accurate type inference for `forwardRef`.
- Access the wrapped dependency through the `forwardRef` field rather than treating the wrapper itself as the referenced value.
- Do not add unrelated metadata to this interface; it should remain a minimal, typed reference wrapper.
- Ensure code that consumes a forward reference resolves `.forwardRef` at the appropriate integration boundary.

## Used by

8 references from 8 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.

### Imported by (8)

- `ClientsModule` — `packages/microservices/module/clients.module.ts`:17
- `ModuleFactory` — `packages/core/injector/compiler.ts`:8
- `InjectorDependency` — `packages/core/injector/injector.ts`:51
- `ByReferenceModuleOpaqueKeyFactory` — `packages/core/injector/opaque-key-factory/by-reference-module-opaque-key-factory.ts`:10
- `ModuleOpaqueKeyFactory` — `packages/core/injector/opaque-key-factory/interfaces/module-opaque-key-factory.interface.ts`:5
- `ModuleDefinition` — `packages/core/interfaces/module-definition.interface.ts`:4
- `IEntryNestModule` — `packages/core/nest-factory.ts`:39
- `DependenciesScanner` — `packages/core/scanner.ts`:75