@mondaydotcomorg/dockerfile-registry-sdk

@mondaydotcomorg/dockerfile-registry-sdk

Node.js SDK for fetching Dockerfiles from the dockerfile-registry. Provides a CLI and programmatic API with smart routing between template-based and service-specific Dockerfiles.

Features

• Smart routing - Automatically chooses between template and service override Dockerfiles based on configuration
• Zero runtime dependencies - Uses only Node.js built-in modules
• CLI + programmatic API - Use from the command line or import in your code
• TypeScript-first - Full type definitions included
• Dry-run mode - Resolve tags without downloading

Requirements

• Node.js >= 20
• A GitHub token — resolved from the first available source:
  • --token CLI flag / token option
  • GITHUB_TOKEN environment variable
  • GH_TOKEN environment variable
  • gh auth token from the GitHub CLI (run gh auth login once)

Installation

# Install globally
npm install -g @mondaydotcomorg/dockerfile-registry-sdk

# Or run directly with npx
npx @mondaydotcomorg/dockerfile-registry-sdk

# Or add to your project
yarn add @mondaydotcomorg/dockerfile-registry-sdk

How It Works

The SDK automatically chooses the right fetching strategy:

• With .dockerrc.json: Routes to template-based Dockerfiles (language templates)
• Without .dockerrc.json or empty config: Routes to service-specific overrides

Configuration

Create a .dockerrc.json file for template-based Dockerfiles:

{
  "version": "1",
  "language": "node",
  "baseVersion": "22",
  "serviceRepoType": "standalone",
  "dockerfileTag": "stable"
}

Field	Description
version	Config schema version (currently "1")
language	Language runtime: node, go, or python
baseVersion	Base version (e.g., "22" for Node.js 22.x, or "22.14" for a specific version)
serviceRepoType	Repository type: standalone or monorepo
dockerfileTag	Tag suffix: stable (default) or latest — composes into {repoType}-{lang}-{ver}-{tag}

For service-specific overrides, omit the config file and pass --service-name. If no --service-name is provided, the SDK falls back to the name field from package.json.

CLI Usage

# Fetch using .dockerrc.json (template-based)
export GITHUB_TOKEN=your_token
dockerfile-registry-sdk

# Fetch service override
dockerfile-registry-sdk -s harmony

# Download to a specific directory
dockerfile-registry-sdk ./build

# Dry-run: print resolved tag without downloading
dockerfile-registry-sdk -n

# Force overwrite existing Dockerfile
dockerfile-registry-sdk -F

# Output result as JSON
dockerfile-registry-sdk --json

# Verbose logging (to stderr)
dockerfile-registry-sdk -v

# Use a custom config file
dockerfile-registry-sdk -f path/to/.dockerrc.json

# Pass token explicitly
dockerfile-registry-sdk --token ghp_xxx

CLI Options

Option	Description
-f, --config-file <path>	Path to .dockerrc.json (default: .dockerrc.json)
-s, --service-name <name>	Service name for override fetch
-r, --repo <owner/repo>	GitHub repository (default: DaPulse/dockerfile-registry)
-n, --dry-run	Resolve tag without downloading
-F, --force	Overwrite existing Dockerfile
-v, --verbose	Enable verbose logging
--token <token>	GitHub token (falls back to GITHUB_TOKEN, GH_TOKEN, or gh auth token)
--json	Output result as JSON
-h, --help	Show help message

Environment Variables

• GITHUB_TOKEN / GH_TOKEN: GitHub token for downloading releases. If neither is set, the SDK falls back to gh auth token from the GitHub CLI.
• DOCKERRC_JSON: Inline JSON config instead of reading from file (CI override pattern)

Programmatic API

import {
  fetchDockerfile,
  fetchTemplateDockerfile,
  fetchServiceOverrideDockerfile,
} from '@mondaydotcomorg/dockerfile-registry-sdk';

// Smart router (reads .dockerrc.json automatically)
const result = await fetchDockerfile({
  token: process.env.GITHUB_TOKEN,
});
// result: { tag: "standalone-node-22-stable", files: ["Dockerfile", "metadata.json"], outputDir: "." }

// Template-based fetch (explicit config)
const result = await fetchTemplateDockerfile({
  config: {
    version: '1',
    language: 'node',
    baseVersion: '22',
    serviceRepoType: 'standalone',
    dockerfileTag: 'stable',
  },
  token: process.env.GITHUB_TOKEN,
  outputDir: './build',
});

// Service override fetch
const result = await fetchServiceOverrideDockerfile({
  serviceName: 'harmony',
  token: process.env.GITHUB_TOKEN,
});

// Dry-run (resolve tag only, no download)
const { tag } = await fetchDockerfile({ dryRun: true });

Types

interface FetchOptions {
  configFile?: string; // Path to .dockerrc.json
  config?: Partial<DockerrcConfig>; // Inline config object
  serviceName?: string; // Service name for override
  repo?: string; // GitHub repo (default: DaPulse/dockerfile-registry)
  outputDir?: string; // Output directory (default: ".")
  token?: string; // GitHub token
  dryRun?: boolean; // Resolve tag only
  force?: boolean; // Overwrite existing files
  verbose?: boolean; // Enable verbose logging to stderr
}

interface FetchResult {
  tag: string; // Resolved release tag
  files: string[]; // List of written file paths
  outputDir: string; // Output directory used
}

CI Integration

steps:
  - name: Fetch Dockerfile
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    run: npx @mondaydotcomorg/dockerfile-registry-sdk

  - name: Build Docker image
    run: docker build -t myapp .

Tag Resolution

Template-based Dockerfiles

The SDK computes the release tag from your .dockerrc.json:

Config	Computed Tag
language: node, baseVersion: 22, tag: stable	standalone-node-22-stable
language: go, baseVersion: 1, tag: stable	standalone-go-1-stable
language: python, baseVersion: 3, tag: stable	standalone-python-3-stable
language: node, baseVersion: 22, dockerfileTag: latest	standalone-node-22-latest

Service Override Dockerfiles

The tag is based on the service name:

Service Name	Computed Tag
harmony	service-override-harmony-latest
chronos	service-override-chronos-latest
my-service	service-override-my-service-latest

Error Handling

The SDK exports typed error classes, each with a distinct exit code:

Error Class	Exit Code	When
ConfigError	1	Invalid or missing configuration
AuthError	2	Missing or invalid GitHub token
DownloadError	3	Release not found or download failure

import { ConfigError, AuthError, DownloadError } from '@mondaydotcomorg/dockerfile-registry-sdk';

try {
  await fetchDockerfile({ token });
} catch (err) {
  if (err instanceof ConfigError) {
    // Fix .dockerrc.json
  } else if (err instanceof AuthError) {
    // Set GITHUB_TOKEN, pass --token, or run `gh auth login`
  } else if (err instanceof DownloadError) {
    // Release tag may not exist
  }
}

License

Internal use only.