Module Configuration

Modules can be configured by editing their dagger.json file. The configuration in there contains all module metadata - from the name of the module and the SDK it uses, to the dependencies it requires. An initial configuration is automatically generated when using dagger init or dagger develop for the first time, and is kept up-to-date with dagger config/dagger install/etc.

For more information, refer to the JSON schema for the Dagger module configuration file.

File and directory filters

The JSON schema for the Dagger module configuration file dagger.json supports an include field. It tells the Dagger Engine of additional files to include or exclude when loading the module itself. By default, only dagger.json and all files under the module's source directory are included.

Notably, these filters only apply to loading the Dagger module. They do not apply to any directories passed as arguments to the Dagger module's functions (pre- and post-call filtering is separately available for directory arguments).

:::tip Adding excluding patterns prefixed with ! is particularly useful during local module development, to avoid uploading large cache or generated files that the Dagger Engine doesn't need. :::

TypeScript

TypeScript-specific SDK settings can be configured using the standard package.json file.

Alternative runtimes

TypeScript is supported by multiple runtimes: Node.js (via tsx), Deno (natively) and Bun (natively). The Dagger TypeScript SDK supports all of these, although Bun and Deno support is currently 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, refer to the sections below.

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

You can also set a specific version with a suffix (e.g., [email protected]).

  "dagger": {
    "runtime": "[email protected]"
  }

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

Set the field to bun to use the Bun runtime (and its package manager).

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

You can also set a specific version with a suffix (e.g., [email protected]).

  "dagger": {
    "runtime": "[email protected]"
  }

If dagger.runtime is not set, but a bun.lock or bun.lockb file is present, Dagger will automatically detect and configure Bun for use. You can generate this file with bun init and bun install, as in the example below:

bun init
bun install // to generate the bun.lock file
dagger init --sdk=typescript --name=example --source=.

:::important The module's source field must reference the same directory as the bun.lock or bun.lockb file. ::: </TabItem> <TabItem value="deno" label="Deno">

:::warning Deno runtime support is still experimental. Unexpected results may occur in some cases. :::

If a deno.json file is present, Dagger will automatically detect and configure Deno for use. You can generate this file with deno init, as in the example below:

deno init
dagger init --sdk=typescript --name=example --source=.

:::important The module's source field must reference the same directory as the deno.json file. ::: </TabItem> </Tabs>

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 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.lock or bun.lockb file is present, Dagger will choose bun as the runtime. Alternatively, if a deno.json, or deno.lock, file is present, Dagger will choose deno 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

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": "[email protected]"

If no version is specified, [email protected] 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": "[email protected]"

If no version is specified, [email protected] 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": "[email protected]"

If no version is specified, [email protected] 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'

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: [email protected], [email protected] or [email protected].
• If none of the above mentioned lock files are present, but a bun.lock or bun.lockb file is present, Dagger will choose bun as the runtime and package manager with a predefined default version: [email protected].
• [email protected] 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. :::

Alternative base images

The image to use is derived from the version in the dagger.runtime field if it's present. If this is not suitable for your needs, you can specify a custom base image in your module's package.json, tailoring the SDK to your project's needs.

:::warning It is recommended to use this feature only for advanced use cases such as adding bespoke environment variables, authentication files or operating system packages to the runtime container. Ensure that you avoid deviating from the default image too much, as doing so could create unexpected results. :::

To change the base image, set the field dagger.baseImage in your Dagger module's package.json file.

{
  "dagger": {
    "baseImage": "node:23.2.0-alpine@sha256:ecefaffd4706c5879af52e022fdb8ea30cbd6590e2a30d05347790d690727c6c"
  }
}

:::note Currently, only Alpine-based images are supported. :::

Bundled or vendored SDK

By default, the SDK is installed as a bundled local dependency, so all SDK related dependencies are already pre-bundled in the module's code and no extra dependencies are added to the module's package.json file.

The tsconfig.json is configured to import the bundled SDK from the sdk directory and correctly map imports paths:

{
    "paths": {
      "@dagger.io/dagger": ["./sdk/index.ts"],
      "@dagger.io/dagger/telemetry": ["./sdk/telemetry.ts"]
    }
}

The bundled SDK ensures better performance and compatibility with all the runtimes, without conflicting with the module's own dependencies.

However, you can also configure the SDK as a local vendored dependency:

# Cleanup the current SDK module's directory
rm -rf ./sdk

# Add `@dagger.io/dagger` as a local dependency
npm pkg set "dependencies[@dagger.io/dagger]=./sdk"

# Re generate the module's directory
dagger develop

This will generate a new sdk directory with the SDK as a vendored library and will update the tsconfig.json with the new import paths.

{
    "paths": {
      "@dagger.io/dagger": ["./sdk/src"],
      "@dagger.io/dagger/telemetry": ["./sdk/src/telemetry"]
    }
}

This may be useful if you share common dependencies between your module and the Dagger Engine but it will impact performance.

To migrate from the local vendored SDK dependency back to the bundled SDK, reverse the process:

# Cleanup the current SDK module's directory
rm -rf ./sdk

# Remove `@dagger.io/dagger` from dependencies
npm pkg delete "dependencies[@dagger.io/dagger]"

# Re generate the module's directory
dagger develop