feat(storage): resolve S3 config from S3_* env vars at runtime

astro.config.mjs is evaluated in Node at Astro build time, so values
passed to s3({...}) are captured and baked into the virtual emdash/config
module. Operators running the same image across multiple container
deployments (per-tenant credentials injected at boot) have no way to
change those values without a rebuild.

Adds runtime resolution: any field omitted from s3({...}) is read from
the matching S3_* env var when the container starts. Existing
deployments that pass explicit values to s3({...}) are unaffected.

Env var names match the existing docs convention (S3_ENDPOINT, S3_BUCKET,
S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, S3_REGION, S3_PUBLIC_URL).

Precedence per field: explicit s3({...}) value > S3_* env var > absent.
Empty strings are treated as absent in both sources. Endpoint values are
validated as http/https URLs with a host at both sources; invalid values
throw MISSING_S3_CONFIG with the source named so operators know whether
to fix their env var or their astro.config.mjs.

endpoint and bucket remain required. accessKeyId and secretAccessKey
become optional in the type (both or neither). Relaxes s3() to accept
Partial<S3StorageConfig> so s3() with no args is valid for fully
env-driven deployments.

Scope: Node. process.env is used for runtime reads, guarded with
typeof-process for bundler safety. Workers users should continue
passing explicit values to s3({...}); worker binding resolution is not
in scope for this change.

Author: UpperM

.changeset/feat-s3-runtime-env-fallback.md

@@ -0,0 +1,15 @@
+---
+"emdash": minor
+---
+
+Adds runtime resolution of S3 storage config from `S3_*` environment
+variables (`S3_ENDPOINT`, `S3_BUCKET`, `S3_ACCESS_KEY_ID`,
+`S3_SECRET_ACCESS_KEY`, `S3_REGION`, `S3_PUBLIC_URL`). Any field omitted from
+`s3({...})` is read from the matching env var on Node at runtime, so
+container images can be built once and receive credentials at boot without a
+rebuild. Explicit values in `s3({...})` still take precedence.
+
+`s3()` with no arguments is now valid for fully env-driven deployments.
+`accessKeyId` and `secretAccessKey` are now optional in `S3StorageConfig`
+(both or neither). Workers users should continue passing explicit values to
+`s3({...})`.

docs/src/content/docs/deployment/storage.mdx

@@ -93,6 +93,21 @@ storage: r2({
 
 The S3 adapter works with Cloudflare R2 (via S3 API), MinIO, and other S3-compatible services.
 
+<Aside type="caution" title="Install the AWS SDK first">
+	EmDash uses the AWS SDK at runtime for the S3 adapter but does not bundle it — core is
+	deliberately SDK-agnostic so R2-only and local-only deployments stay lean. Install the SDK
+	in your project before using `s3()`:
+
+    ```sh
+    pnpm add @aws-sdk/client-s3 @aws-sdk/s3-request-presigner
+    ```
+
+    If you skip this step, `astro build` will fail with `Rollup failed to resolve import
+    "@aws-sdk/client-s3"`. The R2 binding adapter (`r2()`) and local adapter do not need the
+    SDK and are unaffected.
+
+</Aside>
+
 ```js title="astro.config.mjs"
 import emdash, { s3 } from "emdash/astro";
 
@@ -114,14 +129,66 @@ export default defineConfig({
 
 ### Configuration
 
-| Option            | Type     | Description                    |
-| ----------------- | -------- | ------------------------------ |
-| `endpoint`        | `string` | S3 endpoint URL                |
-| `bucket`          | `string` | Bucket name                    |
-| `accessKeyId`     | `string` | Access key                     |
-| `secretAccessKey` | `string` | Secret key                     |
-| `region`          | `string` | Region (default: `"auto"`)     |
-| `publicUrl`       | `string` | Optional CDN or public URL     |
+| Option            | Type     | Required | Description                    |
+| ----------------- | -------- | -------- | ------------------------------ |
+| `endpoint`        | `string` | yes      | S3 endpoint URL                |
+| `bucket`          | `string` | yes      | Bucket name                    |
+| `accessKeyId`     | `string` | no\*     | Access key                     |
+| `secretAccessKey` | `string` | no\*     | Secret key                     |
+| `region`          | `string` | no       | Region (default: `"auto"`)     |
+| `publicUrl`       | `string` | no       | Optional CDN or public URL     |
+
+\* Both `accessKeyId` and `secretAccessKey` must be provided together, or both omitted.
+
+### Resolving S3 config from environment variables
+
+Any field omitted from `s3({...})` is read from the matching `S3_*` environment variable
+when the process starts. This lets you build a container image once and inject credentials
+at boot without a rebuild. Explicit values in `s3({...})` always take precedence over
+environment variables.
+
+| Environment variable   | Field             | Notes                              |
+| ---------------------- | ----------------- | ---------------------------------- |
+| `S3_ENDPOINT`          | `endpoint`        | Must be a valid `http`/`https` URL |
+| `S3_BUCKET`            | `bucket`          |                                    |
+| `S3_ACCESS_KEY_ID`     | `accessKeyId`     |                                    |
+| `S3_SECRET_ACCESS_KEY` | `secretAccessKey` |                                    |
+| `S3_REGION`            | `region`          | Defaults to `"auto"`               |
+| `S3_PUBLIC_URL`        | `publicUrl`       | Optional CDN prefix                |
+
+Environment variables are read from `process.env` when the process starts. This is a
+Node-only feature.
+
+```js title="astro.config.mjs — runtime environment variable example"
+import emdash, { s3 } from "emdash/astro";
+
+export default defineConfig({
+	integrations: [
+		emdash({
+			// s3() with no args: all fields from S3_* environment variables
+			storage: s3(),
+
+			// Or mix: override one field, rest from environment
+			// storage: s3({ publicUrl: "https://cdn.example.com" }),
+		}),
+	],
+});
+```
+
+<Aside type="note" title="Cloudflare Workers">
+	This runtime resolution does not work on Cloudflare Workers. Worker secrets and variables
+	are exposed through the `env` parameter of the fetch handler (or `import { env } from
+	"cloudflare:workers"`), not through `process.env` — even with the `nodejs_compat` flag
+	enabled. For Workers deployments:
+
+    - If you are using R2, use the [`r2()` adapter](#cloudflare-r2-binding) from
+      `@emdash-cms/cloudflare`. This is the recommended path.
+    - If you need a non-R2 S3-compatible backend on Workers, pass explicit values to
+      `s3({...})` in `astro.config.mjs`. Note that `astro.config.mjs` runs at build time,
+      so Worker secrets are not directly accessible there; you will need to inject values
+      through your build pipeline.
+
+</Aside>
 
 ### R2 via S3 API
 

docs/src/content/docs/reference/configuration.mdx

@@ -72,7 +72,10 @@ storage: r2({
 	publicUrl: "https://pub-xxxx.r2.dev", // optional
 });
 
-// S3-compatible (any platform)
+// S3-compatible (any platform) — all fields from S3_* environment variables
+storage: s3()
+
+// Or with explicit values
 storage: s3({
 	endpoint: "https://s3.amazonaws.com",
 	bucket: "my-bucket",
@@ -387,29 +390,50 @@ r2({
 });
 ```
 
-### `s3(config)`
+### `s3(config?)`
+
+S3-compatible storage. All config fields are optional: any field omitted from
+`s3({...})` is resolved from the matching `S3_*` environment variable when the
+Node process starts. Explicit values always take precedence.
 
-S3-compatible storage.
+**Prerequisite:** install `@aws-sdk/client-s3` and `@aws-sdk/s3-request-presigner`
+in your project. EmDash core does not bundle the AWS SDK. See
+[Storage Options → S3-Compatible Storage](/deployment/storage/#s3-compatible-storage)
+for details.
 
-| Option            | Type     | Description                |
-| ----------------- | -------- | -------------------------- |
-| `endpoint`        | `string` | S3 endpoint URL            |
-| `bucket`          | `string` | Bucket name                |
-| `accessKeyId`     | `string` | Access key                 |
-| `secretAccessKey` | `string` | Secret key                 |
-| `region`          | `string` | Region (default: `"auto"`) |
-| `publicUrl`       | `string` | Optional CDN URL           |
+| Option            | Type     | Description                         |
+| ----------------- | -------- | ----------------------------------- |
+| `endpoint`        | `string` | S3 endpoint URL (`S3_ENDPOINT`)     |
+| `bucket`          | `string` | Bucket name (`S3_BUCKET`)           |
+| `accessKeyId`     | `string` | Access key (`S3_ACCESS_KEY_ID`)     |
+| `secretAccessKey` | `string` | Secret key (`S3_SECRET_ACCESS_KEY`) |
+| `region`          | `string` | Region, default `"auto"` (`S3_REGION`) |
+| `publicUrl`       | `string` | Optional CDN URL (`S3_PUBLIC_URL`)  |
 
 ```js
+// All fields from S3_* environment variables (Node container deployments)
+s3()
+
+// Mix: CDN from config, rest from environment
+s3({ publicUrl: "https://cdn.example.com" })
+
+// All explicit (unchanged from before)
 s3({
 	endpoint: "https://xxx.r2.cloudflarestorage.com",
 	bucket: "media",
 	accessKeyId: process.env.R2_ACCESS_KEY_ID,
 	secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
 	publicUrl: "https://cdn.example.com",
-});
+})
 ```
 
+Runtime environment variable resolution is a Node-only feature. On Cloudflare
+Workers, secrets and variables are exposed through the `env` parameter of the
+fetch handler, not through `process.env`, so `S3_*` environment variables are
+not picked up. Workers deployments should either use the [`r2(config)`](#r2config)
+adapter or pass explicit values to `s3({...})`. See
+[Storage Options](/deployment/storage/#s3-compatible-storage) for details.
+
 ## Live Collections
 
 Configure the EmDash loader in `src/live.config.ts`:

packages/core/src/astro/storage/adapters.ts

@@ -32,20 +32,34 @@ import type { StorageDescriptor, S3StorageConfig, LocalStorageConfig } from "./t
 /**
  * S3-compatible storage adapter
  *
- * Works with AWS S3, Cloudflare R2 (via S3 API), Minio, etc.
+ * Works with AWS S3, Cloudflare R2 (via S3 API), MinIO, etc.
+ *
+ * Any field omitted here is resolved from the matching `S3_*` environment
+ * variable when the container starts (`S3_ENDPOINT`, `S3_BUCKET`,
+ * `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_REGION`, `S3_PUBLIC_URL`).
+ * Explicit values always take precedence over env vars.
+ *
+ * Note: env var resolution reads `process.env` on Node at runtime.
+ * Workers users should continue passing explicit values to `s3({...})`.
  *
  * @example
  * ```ts
+ * // All fields from env (container deployments)
+ * storage: s3()
+ *
+ * // Mix: CDN from config, credentials from env
+ * storage: s3({ publicUrl: "https://cdn.example.com" })
+ *
+ * // All explicit (unchanged from before)
  * storage: s3({
  *   endpoint: "https://xxx.r2.cloudflarestorage.com",
  *   bucket: "media",
- *   accessKeyId: process.env.R2_ACCESS_KEY_ID!,
- *   secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
- *   publicUrl: "https://cdn.example.com", // optional CDN
+ *   accessKeyId: process.env.R2_ACCESS_KEY_ID,
+ *   secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
  * })
  * ```
  */
-export function s3(config: S3StorageConfig): StorageDescriptor {
+export function s3(config: Partial<S3StorageConfig> = {}): StorageDescriptor {
 	return {
 		entrypoint: "emdash/storage/s3",
 		config,

packages/core/src/astro/storage/types.ts

@@ -39,10 +39,18 @@ export interface S3StorageConfig {
 	endpoint: string;
 	/** Bucket name */
 	bucket: string;
-	/** Access key ID */
-	accessKeyId: string;
-	/** Secret access key */
-	secretAccessKey: string;
+	/**
+	 * Access key ID.
+	 * May be resolved from the `S3_ACCESS_KEY_ID` env var at runtime on Node.
+	 * Must be provided together with `secretAccessKey`, or both omitted.
+	 */
+	accessKeyId?: string;
+	/**
+	 * Secret access key.
+	 * May be resolved from the `S3_SECRET_ACCESS_KEY` env var at runtime on Node.
+	 * Must be provided together with `accessKeyId`, or both omitted.
+	 */
+	secretAccessKey?: string;
 	/** Optional region (defaults to "auto") */
 	region?: string;
 	/** Optional public URL prefix for CDN */