Skip to content

Commit

Permalink
doc: add link to the talk at CDK Day 2023
Browse files Browse the repository at this point in the history
  • Loading branch information
tmokmss authored Oct 2, 2023
1 parent de1debd commit d09529a
Showing 1 changed file with 2 additions and 30 deletions.
32 changes: 2 additions & 30 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -107,37 +107,9 @@ The below image is the architecture for `SociIndexBuild` construct. We currently
![soci-architecture](imgs/soci-architecture.png)

## Motivation - why do we need the `NodejsBuild` construct?
Previously, there are a few different ways to deploy frontend applications from CDK (1 and 2 below). But none is perfect with different pros and cons. This construct adds another option to deploy frontend apps.
I talked about why this construct can be useful in some situations at CDK Day 2023. See the recording or slides below:

### 1. Deploy depending resources first, then build a frontend app and deploy it separately
One common way to deploy apps is the following: deploy depending resources (e.g. backend API or Cognito user pools) first, then get values for frontend (e.g. API endpoint or userPoolId) from stack outputs, and build the frontend locally and deploy it separately.

This pattern is easy to use but there are also some disadvantages:

1. we cannot deploy frontend constructs and depending constructs at once (like in a single stack)
2. we need some manipulation outside of CDK to get values from stack output, and inject them to frontend build process. (e.g. manually copy-pasting the values or run a shell script using CloudFormation API to load values from stacks.)

Especially it is sometimes annoying when you want to keep you CDK app as simple as possible.

### 2. Use `S3Deployment.Source.data` to inject deploy-time values
Another possible way is to use [`s3-deployment.Source.data/jsonData`](https://github.com/aws/aws-cdk/pull/18659), storing deploy-time values in an S3 Bucket as a file and loading it from frontend apps on runtime.

In this case it is possible to define both frontend and backend in a single stack and deploy them at once. However, it requires another network request for apps to load those values, which is not very efficient and required additional implementation for runtime to support this mechanism. Also, the CDK internal implementation for this feature is relatively complex (it resolves tokens in the construct's own code unlike other constructs) and currently has [cross-stack bugs](https://github.com/aws/aws-cdk/issues/19257) that might be difficult to resolve.

You can see the working example of this pattern [in this repository](https://github.com/aws-samples/nextjs-authentication-ui-using-amplify-ui-with-cognito#deploy-cdk-stacks).

Now, the construct `NodejsBuild` of this package resolves the above disadvantages.

### 3. Deploy-time build
The main problem is that you cannot know the required values (e.g. API endpoint) unless you deploy the resources, and you cannot build and deploy frontend apps unless you know these values. To resolve it, you can build your frontend app during CloudFormation deployment time. By this, you can inject deploy-time values to your frontend build environment, thereby deploying it all at once.

The advantages of this way is:

1. All of the deployment process can be completed inside CDK. No need to use any additional shell script like the pattern #1.
2. The implementation of frontend is CDK agnostic. You can just use environment variables to inject API endpoint, unlike the pattern #2.
3. We can use both single stack strategy as well as multi-stacks strategy, without any complex mechanism like the pattern #2.

There are, however, a few considerations to be discussed when you use this constuct. Please check the next section.
[Recording](https://www.youtube.com/live/b-nSH18gFQk?si=ogEZ2x1NixOj6J6j&t=373) | [Slides](https://speakerdeck.com/tmokmss/deploy-web-frontend-apps-with-aws-cdk)

## Considerations
Since this construct builds your frontend apps every time you deploy the stack and there is any change in input assets (and currently there's even no build cache in the Lambda function!), the time a deployment takes tends to be longer (e.g. a few minutes even for the simple app in `example` directory.) This might results in worse developer experience if you want to deploy changes frequently (imagine `cdk watch` deployment always re-build your frontend app).
Expand Down

0 comments on commit d09529a

Please sign in to comment.