aws-cdk-web

cdk-web :rocket: DEMO

:muscle:  AWS CDK in your browser!

           

cdk-web and aws-cdk-web are functionally identical packages on npm. read about the differences below.

index

usage	docs	building	testing	types

usage

you need to load aws-sdk v2 and cdk-web somewhere in your HTML:

via npm

npm install --save cdk-web aws-sdk

via unpkg

<script src="https://sdk.amazonaws.com/js/aws-sdk-2.1000.0.min.js"></script>
<script src="https://unpkg.com/cdk-web"></script>

via jsdelivr

<script src="https://sdk.amazonaws.com/js/aws-sdk-2.1000.0.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/cdk-web@latest/dist/cdk-web.min.js"></script>

then a global CDK variable is exposed in your web browser. start writing CDK apps like you would normally do in NodeJS:

const cdk = CDK.require("aws-cdk-lib");
const ec2 = CDK.require("aws-cdk-lib/aws-ec2");
const sqs = CDK.require("aws-cdk-lib/aws-sqs");
const sns = CDK.require("aws-cdk-lib/aws-sns");
const s3 = CDK.require("aws-cdk-lib/aws-s3");
const app = new cdk.App();
const stack = new cdk.Stack(app, "BrowserStack");
const vpc = new ec2.Vpc(stack, "VPC");
const queue = new sqs.Queue(stack, "Queue");
const topic = new sns.Topic(stack, "Topic");
const bucket = new s3.Bucket(stack, "Bucket");
const assembly = await app.synth();
console.log(assembly);

you just replace all calls to require for cdk with CDK.require. output of app.synth() contains all you need to get your generated stack.

cdk-web vs cdk

I have been asked many times, why would someone need cdk-web or simply "what is the point"?

• cdk-web runs much faster than CDK thanks to it being entirely in-memory (better performance:)
• cdk-web is a symmetrical package that works both in Node and browsers (source code reuse + portability)
• cdk-web is arguably securer than CDK, again thanks to it being entirely in-memory (no artifacts left on disk)
• cdk-web weighs a whopping 200MB less than CDK (ideal for AWS Lambda like environments where size is a of essence)
• cdk-web does not have a dependency on any NPM packages (faster installs for enterprise users behind Artifactory, etc.)
• cdk-web allows you to Bring Your Own AWS SDK bundle (customized AWS SDK bundles compatibility - org governance)
• cdk-web allows you to Build Your Own AWS CDK bundle (customized AWS CDK bundles with approved modules - org enforcement)

documentation

documentation on various topics from bootstrapping, cli, async constructs and etc. are located under docs.

building

executing npm run build builds CDK for web. everything is bundled in dist/cdk-web.js. you may open up dist/index.html in your browser if you want to just play with the compiled bundle. you can build a dev bundle verbosely with DEBUG='CdkWeb*' and CDK_WEB_DEBUG=1 environment variables set.

check out docs/development.md if you are trying to use this in development.

testing

testing is done by Puppeteer. the actual generated bundle is loaded into Puppeteer and tests are executed against it. run npm test to execute them.

types

cdk-web ships with a single .d.ts file that gives you the same typings as the native cdk. to get it to work, check out docs/types.md. typings for aws-cdk-lib and constructs are all bundled.

cdk-web vs aws-cdk-web

The two packages are identical, mirrored, and released to at the same time. You may use the other mirror if you are behind a corporate proxy and your NPM packages go through a third-party repository such as Artifactory. The mirror does not list any packages as dependencies in its package.json (neither dev, nor prod). This prevents cdk-web to be incorrectly flagged as vulnerable due to its outdated devDependencies. cdk-web is a compiled project. Its compiler and toolchain being outdated does not impact its runtime. It's all client side JavaScript anyway. The mirror is only provided for your convenience.

The following application-specific resources are only included in cdk-web:

• esbuild.wasm: used by the NodeJS construct
• cdk-web.js.map: used by JS DevTools and debuggers