README
DEMO
cdk-web :rocket::muscle: AWS CDK in your browser! (experimental)
this package is also mirrored on NPM under aws-cdk-web. read about the differences below.
table of content
why?
- it's fun.
- you might be limited in tooling (e.g. Node is not allowed)
- you might be behind a corporate proxy and a browser is all you get reliably
- you might not have time for native tooling because you just want to deploy a damn bucket!
usage
load cdk-web.js
somewhere into your HTML file:
<script src="https://unpkg.com/cdk-web"></script>
and start writing CDK apps like you would normally do in Node:
const cdk = require("aws-cdk-lib");
const ec2 = require("aws-cdk-lib/aws-ec2");
const sqs = require("aws-cdk-lib/aws-sqs");
const sns = require("aws-cdk-lib/aws-sns");
const s3 = 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 = app.synth();
console.log(assembly);
output of app.synth()
contains all you need to get your generated stack.
pseudo cli reference
you can simulate the functionality of native CDK CLI by require()
ing PseudoCli via require("aws-cdk")
.
Classes
Typedefs
- PseudoCliParams :
Object
PseudoCli
Kind: global class
- PseudoCli
- new PseudoCli(options)
- .app ⇒
cdk.App
- .stack ⇒
cdk.Stack
- .credentials ⇒
AWS.Credentials
|undefined
- .synth() ⇒
Object
- .deploy()
- .destroy()
new PseudoCli(options)
NOTE 1: for this to work, the cdk bucket must have a respectable CORS policy attached to it. you can change the CORS policy in [ Properties > Permissions > Edit CORS Configuration ]. a sample policy to wildcard-allow everything looks like this:
[ { "AllowedHeaders": ["*"], "AllowedMethods": ["HEAD","GET","POST","PUT","DELETE"], "AllowedOrigins": ["*"] } ]
NOTE 2: Providing "credentials" is optional but you won't be able to take live actions (e.g deploy and destroy)
Param | Type |
---|---|
options | PseudoCliParams |
cdk.App
pseudoCli.app ⇒ Kind: instance property of PseudoCli
cdk.Stack
pseudoCli.stack ⇒ Kind: instance property of PseudoCli
AWS.Credentials
| undefined
pseudoCli.credentials ⇒ Kind: instance property of PseudoCli
Object
pseudoCli.synth() ⇒ just like native "cdk synth". it synthesizes your stack.
Kind: instance method of PseudoCli
Returns: Object
- the template JSON.
Example
const PseudoCli = require("aws-cdk");
const cli = new PseudoCli({
stack,
credentials: {
accessKeyId: "your AWS access key goes here",
secretAccessKey: "your AWS secret goes here",
// sessionToken: "in case you have a session token",
},
});
// just like executing "cdk synth"
const template = cli.synth();
console.log(template);
pseudoCli.deploy()
just like native "cdk deploy". it deploys your stack to a live AWS account
Kind: instance method of PseudoCli
Example
const PseudoCli = require("aws-cdk");
const cli = new PseudoCli({stack, credentials: { ... }});
// just like executing "cdk deploy"
await cli.deploy();
pseudoCli.destroy()
just like native "cdk destroy". it destroys your previously deployed stack in a live AWS account
Kind: instance method of PseudoCli
Example
const PseudoCli = require("aws-cdk");
const cli = new PseudoCli({stack, credentials: { ... }});
// just like executing "cdk destroy"
await cli.destroy();
Object
PseudoCliParams : Kind: global typedef
Properties
Name | Type |
---|---|
stack | cdk.Stack |
credentials | AWS.Credentials | undefined |
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.
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.
exports
default behavior
a global require
function is exposed that can resolve the following modules in a browser environment:
aws-cdk-lib
: core CDK libraryaws-cdk-lib/*
: core scoped CDK modulesconstructs
: the AWS constructs librarypath
: node path utilities to be used withfs
fs
: in-memory and in-browser file system API
after you call app.synth()
you can investigate what normally goes into your cdk.out
by calling require('fs').vol.toJSON()
which returns everything on "disk" within your browser.
overriding behavior
you can override the default export behavior by defining window.CDK_WEB_REQUIRE
to a string before loading cdk-web.js
in your HTML. For example:
<!DOCTYPE html>
<html>
<body>
<script>window.CDK_WEB_REQUIRE = "my_custom_cdk_require"</script>
<script src="cdk-web.js"></script>
<script>
// window.require is now window.my_custom_cdk_require
const cdk = my_custom_cdk_require('aws-cdk-lib');
</script>
</body>
</html>
vs cdk-webaws-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.