(aws-cdk-lib): Document deep import restrictions and importing experimental packages

What is the problem?

When using EdgeFunction from “aws_cloudfront.experimental” module via CDK v2, you need to modify “…/node_modules/aws-cdk-lib/package.json” to define package subpath of ‘./aws-cloudfront/lib/experimental’ by “exports”. If not doing such, you will encounter the error as below: “Error: Package subpath ‘./aws-cloudfront/lib/experimental’ is not defined by “exports” in …/node_modules/aws-cdk-lib/package.json”

Reproduction Steps

Import “EdgeFunction” in your codes for using L@E of CloudFront(CDK v2), conduct ‘cdk synth’ or ‘cdk deploy’, then the error comes. import {EdgeFunction} from 'aws-cdk-lib/aws-cloudfront/lib/experimental';

What did you expect to happen?

Without extra manual modifications to “…/node_modules/aws-cdk-lib/package.json” file, just through a simple import to use EdgeFunction, which is similar to the process of CDK v1.

What actually happened?

Needs extra manual modifications to “…/node_modules/aws-cdk-lib/package.json” file

CDK CLI Version

2.3.0

Framework Version

No response

Node.js Version

v16.13.1

OS

Amazon Linux2

Language

Typescript

Language Version

No response

Other information

No response

[peterwoodworth]

I don’t know how I wasn’t able to reproduce this yesterday - I can reproduce this just fine now. Thanks for following up

It turns out this is expected - We have prevented “deep imports” since 2.2.0. See the PR here #17707. Only specifically exported packages in package.json are allowed to be imported by the user.

As it turns out, the experimental library is not in this package. However, the folder lies inside the cloudfront package, and this folder is exported by cloudfront’s index.js. So the correct way to use the experimental library in v2 is as described in the above comment:

import * as cf from 'aws-cdk-lib/aws-cloudfront';

    new cf.experimental.EdgeFunction(this, 'ef', {
      code: Code.fromAsset('./lambda'),
      handler: 'hello.handler',
      runtime: Runtime.NODEJS_14_X
    });

Or

import { experimental } from 'aws-cdk-lib/aws-cloudfront';

    new experimental.EdgeFunction(this, 'ef', {
      code: Code.fromAsset('./lambda'),
      handler: 'hello.handler',
      runtime: Runtime.NODEJS_14_X
    });

My IDE doesn’t complain for me here though 😅

[terrificdm]

@peterwoodworth Hi, the issue will emerge when you really create a lambda resource in your CDK codes by “EdgeFunction”, just like below steps:

1. npm install -g aws-cdk@latest
2. mkdir edgefunction && cd edgefunction && cdk init --language typescript
3. uncomment env. variable to CDK_DEFAULT_ACCOUNT/REGION of “edgefunction.ts” file in “bin” folder
4. replace “edgefunction-stack.ts” file in “lib” folder with below one

import { Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as lambda from 'aws-cdk-lib/aws-lambda';
import {EdgeFunction} from 'aws-cdk-lib/aws-cloudfront/lib/experimental';

export class EdgefunctionStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);
    
    new EdgeFunction(this, 'LambdaFunction', {
      runtime: lambda.Runtime.NODEJS_14_X,
      handler: 'index.handler',
      code: lambda.Code.fromAsset('./lambda'),
      stackId: 'LambdaEdgeStack'
    });
  }
}

1. create a “lambda” folder under root directory of “edgefunction” folder, then put a sample code of lambda in folder.
2. cdk synth

And you will the error…

The weird thing is if I don’t specifically import {EdgeFunction} from “…aws-cloudfront/lib/experimental”, just import “aws-cloudfront” directly, and use “cloudfront.experimental.EdgeFunction” to reprsent {EdgeFunction} in my codes, it works… Eventhough my IDE is with an error notice “Property ‘experimental’ doesn’t exist…” just like below screenshot, which confused me a lot.