From f13920e9f9aa8bea8264327ac486d4ec9cc215b5 Mon Sep 17 00:00:00 2001 From: Harold Sun Date: Thu, 21 May 2026 16:32:33 -0700 Subject: [PATCH] docs(cfn-lang-ext): correct language-extensions precedence order The activation precedence was documented as CLI > env var > samconfig.toml, but the actual behavior is CLI > samconfig.toml > env var. samconfig values are loaded into Click's default_map by configuration_callback, so by the time resolve_language_extensions_enabled runs, flag_value is already non-None and the env var is never consulted. Reorder the methods to match runtime behavior, drop the misleading word "equivalent", and add brief notes explaining why samconfig outranks the env var and when the env var is actually read. --- docs/cfn-language-extensions.md | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/docs/cfn-language-extensions.md b/docs/cfn-language-extensions.md index b6b1f60fcb..9fa4f2035c 100644 --- a/docs/cfn-language-extensions.md +++ b/docs/cfn-language-extensions.md @@ -17,7 +17,7 @@ The original template (with `Fn::ForEach` intact) is preserved for CloudFormatio ## Enabling Language Extensions -Local processing of `AWS::LanguageExtensions` is opt-in per command. Three equivalent activation methods, in priority order: +Local processing of `AWS::LanguageExtensions` is opt-in per command. Three activation methods, in priority order (highest first): 1. **CLI flag** — pass `--language-extensions` on a single invocation: @@ -27,19 +27,9 @@ Local processing of `AWS::LanguageExtensions` is opt-in per command. Three equiv sam deploy --language-extensions ... ``` - `--no-language-extensions` explicitly disables, overriding the env var below. + `--no-language-extensions` explicitly disables, overriding both samconfig.toml and the env var below. -2. **Environment variable** — set `SAM_CLI_ENABLE_LANGUAGE_EXTENSIONS=1` to enable for the current shell: - - ```bash - export SAM_CLI_ENABLE_LANGUAGE_EXTENSIONS=1 - sam build - sam local invoke MyFunction - ``` - - Truthy values (case-insensitive): `1`, `true`, `yes`. Anything else, including empty string, is off. - -3. **`samconfig.toml`** — persist the choice per project: +2. **`samconfig.toml`** — persist the choice per project: ```toml [default.build.parameters] @@ -67,6 +57,18 @@ Local processing of `AWS::LanguageExtensions` is opt-in per command. Three equiv language_extensions = true ``` + A `samconfig.toml` entry is loaded into Click's defaults, so it takes effect as if the flag were passed — and therefore wins over the env var. + +3. **Environment variable** — set `SAM_CLI_ENABLE_LANGUAGE_EXTENSIONS=1` to enable for the current shell: + + ```bash + export SAM_CLI_ENABLE_LANGUAGE_EXTENSIONS=1 + sam build + sam local invoke MyFunction + ``` + + Truthy values (case-insensitive): `1`, `true`, `yes`. Anything else, including empty string, is off. The env var is consulted only when neither the CLI flag nor samconfig.toml sets a value. + **Each command needs its own activation.** Passing `--language-extensions` to `sam build` does not propagate to a later `sam local invoke` — local processing is decided per command invocation. Use the env var or samconfig entry to enable across commands without repeating the flag. ## Fn::ForEach