# WebFunctionCode

Code for a `WebFunction`.

WebFunction always reads its code from S3 at runtime, on every sandbox start, using the
Lambda service principal. The bucket holding the code must therefore have S3 versioning
enabled — enforced at synth time for buckets defined in the same app — and grant
`lambda.amazonaws.com` read access to the code object. The construct adds that grant
automatically on owned buckets (best-effort — imported buckets emit a warning instead).

Bucket encryption compatibility:

- `BucketEncryption.S3_MANAGED` (SSE-S3, AES256) — works, no key policy needed
- `BucketEncryption.KMS` or `BucketEncryption.DSSE` with a customer managed key —
  works; `kms:Decrypt` is granted to the Lambda service principal automatically
  (best-effort for imported keys)
- `BucketEncryption.KMS_MANAGED` (SSE-KMS with `aws/s3`) and
  `BucketEncryption.DSSE_MANAGED` — do not work: an AWS-managed key policy cannot
  be modified to authorize the Lambda service principal. For a bucket defined in
  this app this fails at synthesis; an imported bucket exposes no encryption
  settings, so there it surfaces as a read failure at runtime

Use one of the static factory methods to create an instance.

Unlike `lambda.Code`, there is deliberately no plain `fromAsset()`: each asset factory
names the bucket the code is staged to, so the choice is explicit at the call site.

- Source: [`aws-lambda/lib/webfunction-code.ts`](https://github.com/aws/aws-cdk/blob/v2.276.0/packages/aws-cdk-lib/aws-lambda/lib/webfunction-code.ts#L83)
- Type last changed: v2.276.0 · 10 Nov 2026

## Example

```ts
import * as s3 from 'aws-cdk-lib/aws-s3';

declare const codeBucket: s3.IBucket;

new lambda.WebFunction(this, 'PerRegionApi', {
  code: lambda.WebFunctionCode.fromBucket(codeBucket, 'app.zip', 'version-id'),
  runtime: lambda.WebFunctionRuntime.NODEJS_24_X,
  defaultEndpointAuth: lambda.WebFunctionAuthType.IAM_AUTH,
  defaultEndpoint: {
    endpointLocation: lambda.WebFunctionEndpointLocation.perRegion(['us-east-1', 'us-west-2']),
  },
});
```

## Initializer

```ts
new WebFunctionCode()
```

## Methods

- `bind(scope: Construct, options: WebFunctionCodeBindOptions): WebFunctionCodeConfig` — Binds the code to a construct and returns the S3 location.

  **Parameters**

  - `scope` — - The construct scope to bind to.
  - `options` — - Identity of the WebFunction, used to scope the read policy.

  **Returns:** The S3 location configuration for the code

- `bindToResource(_resource: CfnResource): void` — Called after the CloudFormation resource has been created, to let the code object bind to it.

  A no-op for every current code source.

  `lambda.Code` has the same hook, and its `AssetCode` uses it to attach asset metadata
  (`aws:asset:path` etc.) for tooling. That is deliberately not done here: of the consumers
  of that metadata, SAM CLI local invoke does not support WebFunction, and
  `cdk deploy --hotswap` would be semantically wrong — it performs an in-place code
  update, whereas WebFunction's model is "create a new revision, then shift traffic".
  An override can be added once a consumer is verified to handle WebFunction correctly.

- `fromAssetToManagedBucket(path: string, options?: WebFunctionManagedBucketAssetOptions): WebFunctionCode // chainable` (static) — Create WebFunction code from a local file or directory, staged into a bucket that CDK creates and configures for you.

  One bucket is created per stack and shared by every WebFunction in it that uses this
  factory. It is configured with everything WebFunction requires: versioning, AES256
  (SSE-S3) encryption, and a bucket policy granting `lambda.amazonaws.com` read access.

  The bucket is removed and emptied along with the stack that owns it. If a revision whose
  code it holds is retained, the bucket is retained as well, with a warning.

  Not supported in an environment bootstrapped with a customer managed KMS key; see the README.

- `fromAssetToProvidedBucket(bucket: IBucket, path: string, options?: WebFunctionProvidedBucketAssetOptions): WebFunctionCode // chainable` (static) — Create WebFunction code from a local file or directory, staged into a bucket you own.

  You own the bucket, so CDK only makes the narrowest change it needs: it adds a resource
  policy statement granting `lambda.amazonaws.com` read access to this function's code, and
  `kms:Decrypt` on the bucket's key if it is encrypted with a customer managed key. Both
  are best-effort — on an imported bucket or key they are no-ops and a warning is emitted
  instead, since the policy cannot be modified from this app.

  You are responsible for the bucket settings CDK cannot change:

  - S3 versioning must be enabled. This is validated at synth time for a bucket defined in
    the same app; an imported bucket is only caught at deployment time, where WebFunction
    rejects a bucket that reports no object version.
  - Encryption must not be `BucketEncryption.KMS_MANAGED` (SSE-KMS with `aws/s3`) or
    `BucketEncryption.DSSE_MANAGED`, whose key policy cannot be modified to authorize the
    Lambda service principal. SSE-S3 and a customer managed key both work.

  Not supported in an environment bootstrapped with a customer managed KMS key; see the README.

- `fromBucket(bucket: IBucket, key: string, objectVersion?: string): WebFunctionCode // chainable` (static) — Create WebFunction code from an S3 bucket.

  This method configures the bucket on a best-effort basis so it satisfies
  WebFunction's runtime requirements:

  - It adds a resource policy statement granting `lambda.amazonaws.com`
    `s3:GetObject` and `s3:GetObjectVersion`, scoped to the given object key,
    to the deploying account and to the revisions of the bound WebFunction.
    For buckets imported by attributes (e.g.
    `Bucket.fromBucketName`) the policy cannot be modified from this app;
    ensure the bucket already carries an equivalent statement.
  - This method does not change the bucket's versioning setting, so it is
    validated instead: a bucket defined in this app without
    `versioned: true` fails at synthesis. Imported buckets cannot be
    inspected, so for those the requirement is only enforced at deployment
    time, where WebFunction rejects a bucket that reports no object version.
  - Encryption with an AWS-managed KMS key is asserted against for the same
    reason: a bucket defined in this app using `BucketEncryption.KMS_MANAGED`
    or `BucketEncryption.DSSE_MANAGED` fails at synthesis, since that key's
    policy cannot be modified to authorize the service principal. Imported
    buckets cannot be inspected and are assumed to be compatible.