Skip to content

Load feature-specific dependencies on first use #1577

Open

Description

@cristianrgreco

What happens

Importing testcontainers loads every dependency up front, including ones most test files never use. Measured with the local build of 12.2.0 on Node 24:

Import Time
require("testcontainers"), warm about 165 ms
require("testcontainers"), cold about 330 ms
undici alone 69 ms
dockerode alone 66 ms
archiver alone 57 ms
ssh-remote-port-forward alone 23 ms
docker-compose alone 15 ms

The individual figures are from separate processes and overlap, so they do not add up.

  • ssh-remote-port-forward (and ssh2, with its optional native cpu-features build) is needed only for TestContainers.exposeHostPorts.
  • undici is needed only for the HTTP wait strategy.
  • archiver is needed only when copying files into a container.
  • docker-compose is needed only for DockerComposeEnvironment.

All four are imported statically. Test runners that isolate modules per test file pay the import once per file.

Expected

Feature-specific dependencies are loaded on first use. get-port is already loaded this way in port-generator.ts.

Where

  • packages/testcontainers/src/port-forwarder/port-forwarder.ts
  • packages/testcontainers/src/wait-strategies/http-wait-strategy.ts
  • packages/testcontainers/src/generic-container/generic-container.ts and started-generic-container.ts
  • packages/testcontainers/src/container-runtime/clients/compose/

Notes

  • Runtime dependencies must keep loading from CommonJS (AGENTS.md).
  • ssh-remote-port-forward could become an optional dependency, which would also remove the native build step from installs that never expose host ports. That part would be major.
  • Measure before and after. If the saving is small, close this.

Dependencies

  • Nothing blocks this. It can start now.

Activity

  1. added
    maintenanceImprovements that do not change functionality
    patchBackward compatible bug fix
    on Oct 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    maintenanceImprovements that do not change functionalitypatchBackward compatible bug fix

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions