Dependency Injection Patterns

TL;DR

Every Webiny extension type uses the same DI pattern: define a class implementing

*.Interface

*.createImplementation({ implementation, dependencies })

The Universal Pattern

import { SomeFactory } from "webiny/some/path";
import { Logger, BuildParams } from "webiny/api";

class MyImplementation implements SomeFactory.Interface {
  constructor(
    private logger: Logger.Interface,
    private buildParams: BuildParams.Interface
  ) {}

  execute(/* factory-specific params */) {
    this.logger.info("Doing something...");
    // buildParams.get() returns T | null — always account for null.
    const value = this.buildParams.get<string>("MY_PARAM");
  }
}

export default SomeFactory.createImplementation({
  implementation: MyImplementation,
  dependencies: [Logger, BuildParams]
});

Key rules:

1. One class per file -- each extension file exports a single implementation.
2. Constructor injection -- dependencies are received as constructor parameters, in the same order as the

   dependencies

   array.
3. Dependencies array -- must exactly match the constructor parameter order and types.
4. Interface types -- always type constructor params as

   Feature.Interface

   .

Where This Pattern Appears

ModelFactory

"webiny/api/cms/model"

GraphQLSchemaFactory

"webiny/api/graphql"

ApiKeyFactory

"webiny/api/security"

CliCommandFactory

"webiny/cli/command"

CorePulumi

"webiny/infra/core"

Event handlers use the same

createImplementation

pattern but are not injectable dependencies.

Examples Across Extension Types

API Extension (GraphQL Schema with DI)

GraphQL schemas use the builder pattern. The

execute

builder

addTypeDefs

addResolver

dependencies

addResolver

import { GraphQLSchemaFactory } from "webiny/api/graphql";
import { IdentityContext } from "webiny/api/security";

class WhoAmISchema implements GraphQLSchemaFactory.Interface {
  async execute(
    builder: GraphQLSchemaFactory.SchemaBuilder
  ): Promise<GraphQLSchemaFactory.SchemaBuilder> {
    builder.addTypeDefs(/* GraphQL */ `
      extend type Query {
        whoAmI: String
      }
    `);

    builder.addResolver({
      path: "Query.whoAmI",
      dependencies: [IdentityContext],
      resolver: (identityContext: IdentityContext.Interface) => {
        return () => {
          const identity = identityContext.getIdentity();
          return `Hello, ${identity.displayName}!`;
        };
      }
    });

    return builder;
  }
}

export default GraphQLSchemaFactory.createImplementation({
  implementation: WhoAmISchema,
  dependencies: []
});

Note:

GraphQLSchemaFactory

dependencies: []

addResolver({ dependencies })

CLI Command with DI

import { Ui } from "webiny/cli";
import { CliCommandFactory } from "webiny/cli/command";

class MyCommandImpl implements CliCommandFactory.Interface<{ name: string }> {
  constructor(private ui: Ui.Interface) {}

  execute(): CliCommandFactory.CommandDefinition<{ name: string }> {
    return {
      name: "greet",
      description: "Greet someone",
      params: [{ name: "name", description: "Name", type: "string" }],
      handler: async params => {
        this.ui.success(`Hello, ${params.name}!`);
      }
    };
  }
}

export default CliCommandFactory.createImplementation({
  implementation: MyCommandImpl,
  dependencies: [Ui]
});

Pulumi Handler with DI

import { Ui } from "webiny/infra";
import { CorePulumi } from "webiny/infra/core";

class MyPulumiImpl implements CorePulumi.Interface {
  constructor(private ui: Ui.Interface) {}

  execute(app: any) {
    this.ui.info("Deploying with environment:", app.env);
  }
}

export default CorePulumi.createImplementation({
  implementation: MyPulumiImpl,
  dependencies: [Ui]
});

Advanced Dependency Options

The

dependencies

Abstraction

[Abstraction, { optional: true }]

undefined

[Abstraction, { multiple: true }]

T[]

[Abstraction, { multiple: true, optional: true }]

undefined

[]

multiple

Multi-injection (

{ multiple: true }

)

Use when a class needs all registered implementations of an abstraction. The container calls

resolveAll()

Abstraction:

interface IPageType {
  name: string;
  label: string;
  modify(form: IFormModel): void;
}

export const PageType = createAbstraction<IPageType>("PageType");

export namespace PageType {
  export type Interface = IPageType;
}

Multiple implementations registered separately:

// StaticPageType.ts
class StaticPageTypeImpl implements PageType.Interface {
  name = "static";
  label = "Static Page";
  modify(form: IFormModel) {
    /* no-op — base form is sufficient */
  }
}

export const StaticPageType = PageType.createImplementation({
  implementation: StaticPageTypeImpl,
  dependencies: []
});

// ProductPageType.ts (in another package/extension)
class ProductPageTypeImpl implements PageType.Interface {
  name = "product";
  label = "Product Page";
  modify(form: IFormModel) {
    form.fields(fields => ({
      product: fields.select().label("Product").required("Product is required")
    }));
    form.field("title").disabled(true);
    form.field("path").disabled(true);
  }
}

export const ProductPageType = PageType.createImplementation({
  implementation: ProductPageTypeImpl,
  dependencies: []
});

Consumer injects the array:

class CreatePagePresenterImpl implements CreatePagePresenter.Interface {
  constructor(
    private factory: FormModelFactory.Interface,
    private pageTypes: PageType.Interface[],
    private modifiers: CreatePageFormModifier.Interface[]
  ) {}
}

export const CreatePagePresenter = PresenterAbstraction.createImplementation({
  implementation: CreatePagePresenterImpl,
  dependencies: [
    FormModelFactory,
    [PageType, { multiple: true }],
    [CreatePageFormModifier, { multiple: true }]
  ]
});

Registration — each implementation is a separate

container.register()

export const CreatePageFeature = createFeature({
  name: "CreatePage",
  register(container) {
    container.register(StaticPageType); // first PageType impl
    container.register(ProductPageType); // second PageType impl
    container.register(CreatePagePresenter);
  }
});

When

CreatePagePresenter

pageTypes

[StaticPageTypeImpl, ProductPageTypeImpl]

Optional dependency (

{ optional: true }

)

Use when a dependency may not be registered. The container injects

undefined

class MyPresenterImpl {
  constructor(
    private required: RequiredService.Interface,
    private analytics: AnalyticsService.Interface | undefined
  ) {}
}

export const MyPresenter = Abstraction.createImplementation({
  implementation: MyPresenterImpl,
  dependencies: [RequiredService, [AnalyticsService, { optional: true }]]
});

Container API Reference

Registration

container.register(Impl)

RegistrationBuilder

.inSingletonScope()

resolve()

resolveAll()

container.registerInstance(Abstraction, instance)

container.registerFactory(Abstraction, factory)

resolve()

container.registerDecorator(Decorator)

container.registerComposite(Composite)

resolve()

Resolution

container.resolve(Abstraction)

container.resolveAll(Abstraction)

T[]

container.createChildContainer()

Lifetime Scopes

• Transient (default): New instance on every

  resolve()

  .
• Singleton (

  .inSingletonScope()

  ): Cached after first resolution, one instance per container.

Convention: Use cases = transient. Repositories, gateways, services, registries = singleton.

Decorators

Decorators wrap resolved instances. The decoratee is always the last constructor parameter. The

dependencies

class LoggingServiceDecorator implements MyService.Interface {
  constructor(
    private logger: Logger.Interface,
    private decoratee: MyService.Interface // LAST param — injected automatically
  ) {}

  execute() {
    this.logger.info("Before");
    this.decoratee.execute();
  }
}

export const MyServiceLoggingDecorator = MyService.createDecorator({
  decorator: LoggingServiceDecorator,
  dependencies: [Logger] // decoratee is NOT listed
});

// Registration:
container.registerDecorator(MyServiceLoggingDecorator);

Composites

Composites aggregate multiple implementations behind a single

resolve()

Abstraction.createComposite()

class AllValidatorsComposite implements Validator.Interface {
  constructor(private validators: Validator.Interface[]) {}

  validate(input: unknown) {
    for (const v of this.validators) v.validate(input);
  }
}

export const ValidatorComposite = Validator.createComposite({
  implementation: AllValidatorsComposite,
  dependencies: [[Validator, { multiple: true }]]
});

// Registration:
container.registerComposite(ValidatorComposite);

Key Rules

1. Always import from the feature path, not the package root.
2. Use

   Feature.Interface

   for constructor parameter types.
3. The

   dependencies

   array order must match the constructor parameter order.
4. Read the

   abstractions.ts

   file in the feature folder to see available methods.
5. Extensions with no dependencies use

   dependencies: []

   .

6. BuildParams.get<T>(name)

   returns

   T | null

   — always type the receiving property/variable as nullable (e.g.

   string | null

   ) and handle the

   null

   case.
7. BuildParam declarations belong inside the extension's

   Extension.tsx

   , not in

   webiny.config.tsx

   . Expose required params as React props on the extension component so the consumer decides where values come from (see

   webiny-full-stack-architect

   skill for the full pattern).
8. For multi-injection, type the constructor param as

   T[]

   and use

   [Abstraction, { multiple: true }]

   in the dependencies array.
9. Each implementation of a multi-bound abstraction is a separate

   container.register()

   call — they accumulate.

Related Skills

• webiny-custom-graphql-api

  -- DI in GraphQL schema extensions

• webiny-cli-extensions

  -- DI in CLI command extensions

• webiny-full-stack-architect

  -- Full-stack extension skeleton and registration pattern

• webiny-api-architect

  -- API-side architecture using DI

• webiny-admin-architect

  -- Admin-side architecture using DI