add standalone env config sample (#439)

THardy98 · web-flow · commit 16f826f9991d · 2025-11-12T10:02:27.000-08:00
* add standalone env config sample

* update lockfile and list of samples

* Add to readme

* comment - not print
diff --git a/.scripts/list-of-samples.json b/.scripts/list-of-samples.json
@@ -13,6 +13,7 @@
     "ejson",
     "empty",
     "encryption",
+    "env-config",
     "expense",
     "fetch-esm",
     "food-delivery",
diff --git a/README.md b/README.md
@@ -143,6 +143,7 @@ and you'll be given the list of sample options.
 #### Production APIs
 
 - [**Production Build**](./production): Build code in advance for faster Worker startup times.
+- [**Environment Configuration**](./env-config): Configure Temporal Client connections using TOML configuration files with support for multiple environment profiles and programmatic overrides.
 - [**Debugging**](https://docs.temporal.io/dev-guide/typescript/debugging): The [vscode-debugger](./vscode-debugger) sample shows how to use the Temporal VS Code plugin to debug a running or completed Workflow Execution.
 - [**Patching**](https://docs.temporal.io/workflows/#workflow-versioning): Patch in new Workflow code when making updates to Workflows that have executions in progress in production.
 - [**Custom Logger**](./custom-logger): Use a [winston](https://github.com/winstonjs/winston) logger to get logs out of all SDK components.
diff --git a/env-config/.eslintignore b/env-config/.eslintignore
@@ -0,0 +1,3 @@
+node_modules
+lib
+.eslintrc.js
diff --git a/env-config/.eslintrc.js b/env-config/.eslintrc.js
@@ -0,0 +1,43 @@
+const { builtinModules } = require('module');
+
+const ALLOWED_NODE_BUILTINS = new Set(['assert']);
+
+module.exports = {
+  root: true,
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    project: './tsconfig.json',
+    tsconfigRootDir: __dirname,
+  },
+  plugins: ['@typescript-eslint', 'deprecation'],
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/eslint-recommended',
+    'plugin:@typescript-eslint/recommended',
+    'prettier',
+  ],
+  rules: {
+    '@typescript-eslint/no-floating-promises': 'error',
+    'deprecation/deprecation': 'warn',
+    'object-shorthand': ['error', 'always'],
+    '@typescript-eslint/no-unused-vars': [
+      'warn',
+      {
+        argsIgnorePattern: '^_',
+        varsIgnorePattern: '^_',
+      },
+    ],
+    '@typescript-eslint/no-explicit-any': 'off',
+  },
+  overrides: [
+    {
+      files: ['src/workflows.ts', 'src/workflows-*.ts', 'src/workflows/*.ts'],
+      rules: {
+        'no-restricted-imports': [
+          'error',
+          ...builtinModules.filter((m) => !ALLOWED_NODE_BUILTINS.has(m)).flatMap((m) => [m, `node:${m}`]),
+        ],
+      },
+    },
+  ],
+};
diff --git a/env-config/.gitignore b/env-config/.gitignore
@@ -0,0 +1,2 @@
+lib
+node_modules
diff --git a/env-config/.npmrc b/env-config/.npmrc
@@ -0,0 +1 @@
+package-lock=false
diff --git a/env-config/.nvmrc b/env-config/.nvmrc
@@ -0,0 +1 @@
+22
diff --git a/env-config/.prettierignore b/env-config/.prettierignore
@@ -0,0 +1 @@
+lib
diff --git a/env-config/.prettierrc b/env-config/.prettierrc
@@ -0,0 +1,2 @@
+printWidth: 120
+singleQuote: true
diff --git a/env-config/README.md b/env-config/README.md
@@ -0,0 +1,65 @@
+# Temporal External Client Configuration Samples
+
+This directory contains TypeScript samples that demonstrate how to use the Temporal SDK's external client configuration feature. This feature allows you to configure a `Client` using a TOML file and/or programmatic overrides, decoupling connection settings from your application code.
+
+## Prerequisites
+
+To run, first see [README.md](../README.md) for prerequisites.
+
+## Configuration File
+
+The [`config.toml`](./config.toml) file defines three profiles for different environments:
+
+- `[profile.default]`: A working configuration for local development.
+- `[profile.staging]`: A configuration with an intentionally **incorrect** address (`localhost:9999`) to demonstrate how it can be corrected by an override.
+- `[profile.prod]`: A non-runnable, illustrative-only configuration showing a realistic setup for Temporal Cloud with placeholder credentials. This profile is not used by the samples but serves as a reference.
+
+## Samples
+
+The following TypeScript scripts demonstrate different ways to load and use these configuration profiles.
+
+### [`load-from-file.ts`](./src/load-from-file.ts)
+
+This sample shows the most common use case: loading the `default` profile from the `config.toml` file.
+
+### [`load-profile.ts`](./src/load-profile.ts)
+
+This sample demonstrates loading the `staging` profile by name (which has an incorrect address) and then correcting the address programmatically. This highlights the recommended approach for overriding configuration values at runtime.
+
+## Running this sample
+
+1. `temporal server start-dev` to start [Temporal Server](https://github.com/temporalio/cli/#installation).
+2. `npm install` to install dependencies.
+3. Run any of the samples:
+   - `npm run load-default` - Load and connect using the default profile
+   - `npm run load-profile` - Load staging profile and override the incorrect address
+
+### Expected Output
+
+**Running `npm run load-default`:**
+
+```
+--- Loading default profile from config.toml ---
+Loaded 'default' profile from /path/to/config.toml.
+  Address: localhost:7233
+  Namespace: default
+  gRPC Metadata: {"my-custom-header":"development-value","trace-id":"dev-trace-123"}
+
+Attempting to connect to client...
+✅ Client connected successfully!
+```
+
+**Running `npm run load-profile`:**
+
+```
+--- Loading 'staging' profile with programmatic overrides ---
+The 'staging' profile in config.toml has an incorrect address (localhost:9999).
+We'll programmatically override it to the correct address.
+
+Loaded 'staging' profile from /path/to/config.toml with overrides.
+  Address: localhost:7233 (overridden from localhost:9999)
+  Namespace: staging
+
+Attempting to connect to client...
+✅ Client connected successfully!
+```
diff --git a/env-config/config.toml b/env-config/config.toml
@@ -0,0 +1,40 @@
+# This is a sample configuration file for demonstrating Temporal's environment
+# configuration feature. It defines multiple profiles for different environments,
+# such as local development, production, and staging.
+
+# Default profile for local development
+[profile.default]
+address = "localhost:7233"
+namespace = "default"
+
+# Optional: Add custom gRPC headers
+[profile.default.grpc_meta]
+my-custom-header = "development-value"
+trace-id = "dev-trace-123"
+
+# Staging profile with inline certificate data
+[profile.staging]
+address = "localhost:9999"
+namespace = "staging"
+
+# An example production profile for Temporal Cloud
+[profile.prod]
+address = "your-namespace.a1b2c.tmprl.cloud:7233"
+namespace = "your-namespace"
+# Replace with your actual Temporal Cloud API key
+api_key = "your-api-key-here"
+
+# TLS configuration for production
+[profile.prod.tls]
+# TLS is auto-enabled when an API key is present, but you can configure it
+# explicitly.
+# disabled = false
+
+# Use certificate files for mTLS. Replace with actual paths.
+client_cert_path = "/etc/temporal/certs/client.pem"
+client_key_path = "/etc/temporal/certs/client.key"
+
+# Custom headers for production
+[profile.prod.grpc_meta]
+environment = "production"
+service-version = "v1.2.3"
diff --git a/env-config/package.json b/env-config/package.json
@@ -0,0 +1,30 @@
+{
+  "name": "temporal-env-config",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "build": "tsc --build",
+    "build.watch": "tsc --build --watch",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint .",
+    "load-default": "ts-node src/load-from-file.ts",
+    "load-profile": "ts-node src/load-profile.ts"
+  },
+  "dependencies": {
+    "@temporalio/client": "^1.13.2",
+    "@temporalio/envconfig": "^1.13.2"
+  },
+  "devDependencies": {
+    "@tsconfig/node18": "^18.2.4",
+    "@types/node": "^22.9.1",
+    "@typescript-eslint/eslint-plugin": "^8.18.0",
+    "@typescript-eslint/parser": "^8.18.0",
+    "eslint": "^8.57.1",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-deprecation": "^3.0.0",
+    "prettier": "^3.4.2",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.6.3"
+  }
+}
diff --git a/env-config/src/load-from-file.ts b/env-config/src/load-from-file.ts
@@ -0,0 +1,45 @@
+/**
+ * This sample demonstrates loading the default environment configuration profile
+ * from a TOML file.
+ */
+
+import { Connection, Client } from '@temporalio/client';
+import { loadClientConnectConfig } from '@temporalio/envconfig';
+import { resolve } from 'path';
+
+async function main() {
+  console.log('--- Loading default profile from config.toml ---');
+
+  // For this sample to be self-contained, we explicitly provide the path to
+  // the config.toml file included in this directory.
+  // By default though, the config.toml file will be loaded from
+  // ~/.config/temporalio/temporal.toml (or the equivalent standard config directory on your OS).
+  const configFile = resolve(__dirname, '../config.toml');
+
+  // loadClientConnectConfig is a helper that loads a profile and prepares
+  // the configuration for Connection.connect and Client. By default, it loads the
+  // "default" profile.
+  const config = loadClientConnectConfig({
+    configSource: { path: configFile },
+  });
+
+  console.log(`Loaded 'default' profile from ${configFile}.`);
+  console.log(`  Address: ${config.connectionOptions.address}`);
+  console.log(`  Namespace: ${config.namespace}`);
+  console.log(`  gRPC Metadata: ${JSON.stringify(config.connectionOptions.metadata)}`);
+
+  console.log('\nAttempting to connect to client...');
+  try {
+    const connection = await Connection.connect(config.connectionOptions);
+    const client = new Client({ connection, namespace: config.namespace });
+    console.log('✅ Client connected successfully!');
+    await connection.close();
+  } catch (err) {
+    console.log(`❌ Failed to connect: ${err}`);
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});
diff --git a/env-config/src/load-profile.ts b/env-config/src/load-profile.ts
@@ -0,0 +1,47 @@
+/**
+ * This sample demonstrates loading a named environment configuration profile and
+ * programmatically overriding its values.
+ */
+
+import { Connection, Client } from '@temporalio/client';
+import { loadClientConnectConfig } from '@temporalio/envconfig';
+import { resolve } from 'path';
+
+async function main() {
+  console.log("--- Loading 'staging' profile with programmatic overrides ---");
+
+  const configFile = resolve(__dirname, '../config.toml');
+  const profileName = 'staging';
+
+  // The 'staging' profile in config.toml has an incorrect address (localhost:9999)
+  // We'll programmatically override it to the correct address
+
+  // Load the 'staging' profile.
+  const config = loadClientConnectConfig({
+    profile: profileName,
+    configSource: { path: configFile },
+  });
+
+  // Override the target host to the correct address.
+  // This is the recommended way to override configuration values.
+  config.connectionOptions.address = 'localhost:7233';
+
+  console.log(`\nLoaded '${profileName}' profile from ${configFile} with overrides.`);
+  console.log(`  Address: ${config.connectionOptions.address} (overridden from localhost:9999)`);
+  console.log(`  Namespace: ${config.namespace}`);
+
+  console.log('\nAttempting to connect to client...');
+  try {
+    const connection = await Connection.connect(config.connectionOptions);
+    const client = new Client({ connection, namespace: config.namespace });
+    console.log('✅ Client connected successfully!');
+    await connection.close();
+  } catch (err) {
+    console.log(`❌ Failed to connect: ${err}`);
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});
diff --git a/env-config/tsconfig.json b/env-config/tsconfig.json
@@ -0,0 +1,13 @@
+{
+  "extends": "@tsconfig/node18/tsconfig.json",
+  "version": "5.6.3",
+  "compilerOptions": {
+    "lib": ["es2021"],
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "rootDir": "./src",
+    "outDir": "./lib"
+  },
+  "include": ["src/**/*.ts"]
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+node_modules`
	`2`	`+lib`
	`3`	`+.eslintrc.js`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+printWidth: 120`
	`2`	`+singleQuote: true`