<h2 id="content"><a href="#content" aria-hidden="true" tabindex="-1"><span class="icon icon-link"></span></a>Content</h2>
<ul>
<li><a href="#content">Content</a></li>
<li><a href="#introduction">Introduction</a></li>
<li><a href="#the-results">The results</a>
<ul>
<li><a href="#the-architecture">The architecture</a></li>
</ul>
</li>
<li><a href="#how-does-it-work-">How does it work ?</a>
<ul>
<li><a href="#transforming-the-request">Transforming the request</a></li>
<li><a href="#forwarding-to-requests-to-s3">Forwarding to requests to S3</a></li>
<li><a href="#returning-the-response">Returning the response</a></li>
</ul>
</li>
<li><a href="#the-outputs">The outputs</a>
<ul>
<li><a href="#astro-build-output">Astro build (output)</a></li>
<li><a href="#astro-build-to-aws-components">Astro build to AWS components</a></li>
</ul>
</li>
<li><a href="#conclusion">Conclusion</a></li>
</ul>
<h2 id="introduction"><a href="#introduction" aria-hidden="true" tabindex="-1"><span class="icon icon-link"></span></a>Introduction</h2>
<p>Astro is a great framework for create static sites, and it also has some neat features.</p>
<p>Did you know it’s not just limited to static sites anymore ? It now supports server-side rendering (SSR)!</p>
<p><strong>Yep, you heard that right!</strong></p>
<p>To makes things easier, Astro provides an integration out of the box for Node.js - <a href="https://github.com/withastro/astro/tree/main/packages/integrations/node" target="_blank" rel="nofollow noopener noreferrer">@astrojs/node</a>.</p>
<p>These “integrations” provide the ability to customize functionality and behaviors for your project.</p>
<p><strong>This got me thinking</strong> - can we run this at the edge with Lambda@Edge ?</p>
<p>Honestly, Googling around, I didn’t find much resources out there for something like this.</p>
<p>So, I thought to myself why don’t I try to build an integration for it.</p>
<p>After much experimentation, and trial &#x26; error....</p>
<p>Here we are - <a href="https://www.npmjs.com/package/@common-web/astro-lambda-edge" target="_blank" rel="nofollow noopener noreferrer">@common-web/astro-lambda-edge</a>!</p>
<p>The implementation is heavily inspired by <a href="https://github.com/withastro/astro/tree/main/packages/integrations/node" target="_blank" rel="nofollow noopener noreferrer">@astrojs/node</a>.</p>
<p>In this article, we’ll briefly go over how this package works!</p>
<h2 id="the-results"><a href="#the-results" aria-hidden="true" tabindex="-1"><span class="icon icon-link"></span></a>The results</h2>
<p>Before we get into the weeds, let’s talk about what the expected result from this build.</p>
<p>How does this Astro integration fit in with the overall AWS architecture that we plan to build ?</p>
<h3 id="the-architecture"><a href="#the-architecture" aria-hidden="true" tabindex="-1"><span class="icon icon-link"></span></a>The architecture</h3>
<p>The architecture that we are aiming for is serving our site through an AWS architecture that using Cloudfront, S3 and Lambda@Edge.</p>
<p><strong>There are two flows for our origin request (Lambda):</strong></p>
<ol>
<li>Perform server-side rendering</li>
<li>Forward to S3</li>
</ol>
<div style="margin: 2em auto;">
  <div style="display:flex;justify-content:center;">
    <img src="/images/astro-adapter-architecture.png" alt="Illustration of AWS architecture with Astro" style="width:80%" />
  </div>
  <div style="display:flex;justify-content:center;">
    <blockquote>Illustration of AWS architecture with Astro</blockquote>
  </div>
</div>
<p><strong>What each component does:</strong></p>
<ul>
<li>
<p><strong>S3 bucket</strong> - For storing the static assets (<code class="language-">css
</code>, <code class="language-">js
</code>, etc)</p>
</li>
<li>
<p><strong>Cloudfront</strong> - Accelerating and delivering the data/content globally by bringing it closer to the user</p>
</li>
<li>
<p><strong>Lambda@Edge</strong> - For the performing the server-side rendering</p>
</li>
</ul>
<p>So, from this we know what we expect from our astro build.</p>
<p>What we need is the static assets, server code (to run the ssr).</p>
<h2 id="how-does-it-work-"><a href="#how-does-it-work-" aria-hidden="true" tabindex="-1"><span class="icon icon-link"></span></a>How does it work ?</h2>
<p>This package (<strong>@common-web/astro-lambda-edge</strong>) actually does not change the Astro output too much.</p>
<p>Rather, it slightly alters the server output to better fit the expectations of Lambda@edge. Specifically, the origin request.</p>
<p>There are a few key elements in this adapter that helps to make Astro compatible for our desired AWS architecture with Cloudfront and Lambda@Edge.</p>
<p>Let’s through them in a bit more detail.</p>
<h3 id="transforming-the-request"><a href="#transforming-the-request" aria-hidden="true" tabindex="-1"><span class="icon icon-link"></span></a>Transforming the request</h3>
<p>The cloudfront event that we receive in our Lambda is going to be different than what you’d typically expect in something like a node server.</p>
<p>Therefore, we need to map this request so it is compatible with a node server (because this is what Astro is expecting).</p>
<p>These are things like headers, url, etc.</p>
<h3 id="forwarding-to-requests-to-s3"><a href="#forwarding-to-requests-to-s3" aria-hidden="true" tabindex="-1"><span class="icon icon-link"></span></a>Forwarding to requests to S3</h3>
<p>There are two paths in our Lambda@Edge function:</p>
<ol>
<li>SSR render (<code class="language-">/
</code>, <code class="language-">/about
</code>, etc)</li>
<li>Foward to S3 (<code class="language-">.css
</code>, <code class="language-">.js
</code>, etc)</li>
</ol>
<p>Since we are storing our assets in S3, in our Lambda@Edge we will need to foward any requests that has asset extensions (<code class="language-">.css
</code>, <code class="language-">.js
</code>, <code class="language-">.png
</code> etc) to S3.</p>
<h3 id="returning-the-response"><a href="#returning-the-response" aria-hidden="true" tabindex="-1"><span class="icon icon-link"></span></a>Returning the response</h3>
<p>With Cloudfront, it expects the response to be in a certain format.</p>
<p>So, that means we’ll need to map the response we get from Astro into a format that is compatible with Cloudfront.</p>
<p>To see the format, check out <a href="https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/aws-lambda/common/cloudfront.d.ts#L75-L81" target="_blank" rel="nofollow noopener noreferrer">CloudFrontResultResponse</a>.</p>
<h2 id="the-outputs"><a href="#the-outputs" aria-hidden="true" tabindex="-1"><span class="icon icon-link"></span></a>The outputs</h2>
<p>Let’s quickly go over what outputs we will get when we run astro build.</p>
<h3 id="astro-build-output"><a href="#astro-build-output" aria-hidden="true" tabindex="-1"><span class="icon icon-link"></span></a>Astro build (output)</h3>
<p>Here is what the output from Astro with <strong>@common-web/astro-lambda-edge</strong> adapater looks like.</p>
<div style="margin: 2em auto;">
  <div style="display:flex;justify-content:center;">
    <img src="/images/astro-adapter-visualized-build.png" alt="Illustration of Astro build assets" style="width:80%" />
  </div>
  <div style="display:flex;justify-content:center;">
    <blockquote>Illustration of Astro build assets</blockquote>
  </div>
</div>
<h3 id="astro-build-to-aws-components"><a href="#astro-build-to-aws-components" aria-hidden="true" tabindex="-1"><span class="icon icon-link"></span></a>Astro build to AWS components</h3>
<p>Here is how those build assets map to the components in our AWS Architecture.</p>
<div style="margin: 2em auto;">
  <div style="display:flex;justify-content:center;">
    <img src="/images/astro-adapter-to-aws.png" alt="Illustration of Astro build assets mapped to AWS" style="width:80%" />
  </div>
  <div style="display:flex;justify-content:center;">
    <blockquote>Illustration of Astro build assets mapped to AWS</blockquote>
  </div>
</div>
<h2 id="conclusion"><a href="#conclusion" aria-hidden="true" tabindex="-1"><span class="icon icon-link"></span></a>Conclusion</h2>
<p>And that’s it for the overview.</p>
<p>Essentially, this adapter package makes the Astro SSR server compatible with Cloudfront and Lambda@Edge. That’s really all it does!</p>
<p><strong>Links:</strong></p>
<ul>
<li>
<p><strong>npm</strong> - <a href="https://www.npmjs.com/package/@common-web/astro-lambda-edge" target="_blank" rel="nofollow noopener noreferrer">@common-web/astro-lambda-edge</a></p>
</li>
<li>
<p><strong>github code</strong> - <a href="https://github.com/Jareechang/common-web/tree/master/packages/astro-lambda-edge" target="_blank" rel="nofollow noopener noreferrer">astro-lambda-edge</a></p>
</li>
</ul>
<p>Give it a try, and let me know what you think! Feel free to submit changes/fixes if you see it missing something!</p>
<p>And... that’s all for now, stay tuned for more!</p>
<p>If you found this helpful or learned something new, please do share this article with a friend or co-worker 🙏❤️ (Thanks!)</p>


Jerry Chang

Go Back

Astro: Building the Lambda@Edge Adapter

Enjoy the content ?