Skip to main content

Dagger Modules

Alternative runtimes​

important

The information in this section is only applicable to the TypeScript SDK. Alternative runtimes are not currently supported in the Python and Go SDKs.

TypeScript is supported by multiple runtimes: Node.js (via tsx), Deno (natively) and Bun (natively). However, the Dagger TypeScript SDK only supports Node.js (stable) and Bun (experimental).

By default, the TypeScript SDK executes functions using the Node.js runtime, but you can configure an alternative runtime in your Dagger module's package.json file.

To change the TypeScript SDK runtime, set the field dagger.runtime in your Dagger module's package.json file.

Node.js​

Set the field to node to use the Node.js runtime. Node.js is also the default runtime used if this field is omitted.

  "dagger": {
    "runtime": "node"
  }

You can also set a specific version with a suffix (e.g., node@20.15.0).

  "dagger": {
    "runtime": "node@20.15.0"
  }

Bun​

Set the field to bun to use the Bun runtime.

  "dagger": {
    "runtime": "bun"
  }

You can also set a specific version with a suffix (e.g., bun@1.0.11).

  "dagger": {
    "runtime": "bun@1.0.11"
  }
warning

Bun runtime support is still experimental. Unexpected results may occur in some cases.

Automatic detection​

When a runtime is not explicitly defined within the package.json file, Dagger automatically identifies the appropriate runtime by examining the project's lock files inside the project's dagger directory.

  • If Dagger finds any of the following lock files : package-lock.json, yarn.lock, or pnpm-lock.yaml, it automatically selects node as the runtime.
  • In the absence of the lock files mentioned above, if a bun.lockb file is present, Dagger will choose bun as the runtime.
  • If no or only unknown lock files are present, node is chosen.
warning

This behavior however should be seen as a sensible fallback and not as an explicit configuration.

Alternative package managers​

important

The information in this section is only applicable to the TypeScript SDK. Alternative runtimes are not currently supported in the Python and Go SDKs.

TypeScript can manage dependencies using multiple package managers. The Node.js runtime supports npm, pnpm and yarn. The Bun runtime supports bun.

By default, the TypeScript SDK executes functions using the Node.js runtime with yarn v1.22.22, but you can configure an alternative package manager or version in your Dagger module's package.json file by setting the packageManager property.

Npm​

Set the packageManager property to npm to use the npm package manager. You can also set a specific version with a suffix, as shown below:

  "packageManager": "npm@10.8.2"

If no version is specified, npm@10.7.0 is used by default.

Yarn​

Set the packageManager property to yarn to use the Yarn package manager. You can also set a specific version with a suffix, as shown below:

  "packageManager": "yarn@1.22.21"

If no version is specified, yarn@1.22.22 is used by default.

If you use Yarn 3.0 or above, the TypeScript SDK will also generate a .yarnrc.yml file in your module's root directory. This file is used to configure the Yarn package manager linker to node_modules, which is required to correctly resolve @dagger.io/dagger as local dependencies of your module.

nodeLinker: node-modules

Pnpm​

Set the packageManager property to pnpm to use the Pnpm package manager. You can also set a specific version with a suffix, e.g.:

  "packageManager": "pnpm@9.9"

If no version is specified, pnpm@8.15.4 is used.

The TypeScript SDK will also generate a pnpm-workspace.yml file in your module's root directory. This file is used to configure the Pnpm package manager, which is required to correctly resolve @dagger.io/dagger as local dependencies of your module.

packages:
  - './sdk'

Bun​

warning

Bun runtime support is still experimental. Unexpected results may occur in some cases.

Setting the runtime property to bun will use the Bun runtime and its package manager. You do not need to set the packageManager field explicitly. Here is an example:

  "dagger": {
    "runtime": "bun"
  }

Automatic detection​

When a package manager is not explicitly defined within the package.json file, Dagger automatically identifies the appropriate package manager by examining the project's lock files inside the project's .dagger directory.

  • If Dagger finds any of the following lock files : package-lock.json, yarn.lock, or pnpm-lock.yaml, it automatically selects the corresponding package manager with a predefined default version: npm@10.7.0, yarn@1.22.22 or pnpm@8.15.4.
  • If none of the above mentioned lock files are present, but a bun.lockb file is present, Dagger will choose bun as the runtime and package manager with a predefined default version: bun@1.0.11.
  • yarn@1.22.22 is the last default, when nothing mentioned above applies.
warning

This behavior however should be considered a sensible fallback, and not as an explicit configuration. Since this default can change, we encourage you to configure a package manager explicitly.