This post is courtesy of Roman Boiko, Solutions Architect.

React is a popular front-end framework used to create single-page applications (SPAs). It is rendered and run on the client-side in the browser. However, for SEO or performance reasons, you may need to render parts of a React application on the server. This is where the server-side rendering (SSR) is useful.

This post introduces the concepts and demonstrates rendering a React application with AWS Lambda. To deploy this solution and to provision the AWS resources, I use the AWS Cloud Development Kit (CDK). This is an open-source framework, which helps you reduce the amount of code required to automate deployment.


This solution uses Amazon S3, Amazon CloudFront, Amazon API Gateway, AWS Lambda, and [email protected]. It creates a fully serverless SSR implementation, which automatically scales according to the workload. This solution addresses three scenarios.

1. A static React app hosted in an S3 bucket with a CloudFront distribution in front of the website. The backend is running behind API Gateway, implemented as a Lambda function. Here, the application is fully downloaded to the client and rendered in a web browser. It sends requests to the backend.

SSR app 1

2. The React app is rendered with a Lambda function. The CloudFront distribution is configured to forward requests from the /ssr path to the API Gateway endpoint. This calls the Lambda function where the rendering is happening. While rendering the requested page, the Lambda function calls the backend API to fetch the data. It returns a static HTML page with all the data. This page may be cached in CloudFront to optimize subsequent requests.

SSR app 2


3. The React app is rendered with a [email protected] function. This scenario is similar but rendering happens at edge locations. The requests to /edgessr are handled by the [email protected] function. This sends requests to the backend and returns a static HTML page.

SSR app 3



The example application shows how the preceding scenarios are implemented with the AWS CDK. This solution requires:

This solution deploys a [email protected] function so it must be provisioned in the US East (N. Virginia) Region.

To get started, download and configure the sample:

  1. From a terminal, clone the GitHub repository:
    git clone
  2. Provide a unique name for the S3 bucket, which is created by the stack and used for React application hosting. Change the placeholder <your bucket name> to your bucket name. To install the solution, run:
    cd react-ssr-lambda
    cd ./cdk
    npm install
    npm run build
    cdk bootstrap
    cdk deploy SSRApiStack --outputs-file ../simple-ssr/src/config.json cd ../simple-ssr
    npm install
    npm run build-all
    cd ../cdk
    cdk deploy SSRAppStack --parameters mySiteBucketName=<your bucket name>
  3. Note the following values from the output:
    • SSRAppStack.CFURL – the URL of the CloudFront distribution. Its root path returns the React application stored in S3.
    • SSRAppStack.LambdaSSRURL – the URL of the CloudFront /ssr distribution, which returns a page rendered by the Lambda function.
    • SSRAppStack.LambdaEdgeSSRURL – the URL of the CloudFront /edgessr distribution, which returns a page rendered by [email protected] function.Stack outputs
  4. In a browser, open each of the URLs from step 3. You see the same page with a different footer, indicating how it is rendered.Comparing the served pages

Understanding the React app

The application is created by the create-react-app utility. You can run and test this application locally by navigating to the simple-ssr directory and running the npm start command.

This small application consists of two components that render the list of products received from the backend. The App.js file sends the request, parses the result, and passes it to the component.

import React, { useEffect, useState } from "react";
import ProductList from "./components/ProductList";
import config from "./config.json";
import axios from "axios"; const App = ({ isSSR, ssrData }) => { const [err, setErr] = useState(false); const [result, setResult] = useState({ loading: true, products: null }); useEffect(() => { const getData = async () => { const url = config.SSRApiStack.apiurl; try { let result = await axios.get(url); setResult({ loading: false, products: }); } catch (error) { setErr(error); } }; getData(); }, []); if (err) { return <div>Error {err}</div>; } else { return ( <div> <ProductList result={result} /> </div> ); }
}; export default App;

Adding server-side rendering

To support SSR, I change the preceding application using several Lambda functions with the implementation. As I change the way data is retrieved from the backend, I remove this code from App.js. Instead, the data is retrieved in the Lambda function and injected into the application during the rendering process.

The new file SSRApp.js reflects these changes:

import React, { useState } from "react";
import ProductList from "./components/ProductList"; const SSRApp = ({ data }) => { const [result, setResult] = useState({ loading: false, products: data }); return ( <div> <ProductList result={result} /> </div> );
}; export default SSRApp;

Next, I implement SSR logic in the Lambda function. For simplicity, I use React’s built-in renderToString method, which returns an HTML string. You can find the corresponding file in the simple-ssr/src/server/index.js. The handler function fetches data from the backend, renders the React components, and injects them into the HTML template. It returns the response to API Gateway, which responds to the client.

const handler = async function (event) { try { const url = config.SSRApiStack.apiurl; const result = await axios.get(url); const app = ReactDOMServer.renderToString(<SSRApp data={} />); const html = indexFile.replace( '<div id="root"></div>', `<div id="root">${app}</div>` ); return { statusCode: 200, headers: { "Content-Type": "text/html" }, body: html, }; } catch (error) { console.log(`Error ${error.message}`); return `Error ${error}`; }

For rendering the same code on [email protected], I change the code to work with CloudFront events and also modify the response format. This function searches for a specific path (/edgessr). All other logic stays the same. You can view the full code at simple-ssr/src/edge/index.js:

const handler = async function (event) { try { const request = event.Records[0].cf.request; if (request.uri === "/edgessr") { const url = config.SSRApiStack.apiurl; const result = await axios.get(url); const app = ReactDOMServer.renderToString(<SSRApp data={} />); const html = indexFile.replace( '<div id="root"></div>', `<div id="root">${app}</div>` ); return { status: "200", statusDescription: "OK", headers: { "cache-control": [ { key: "Cache-Control", value: "max-age=100", }, ], "content-type": [ { key: "Content-Type", value: "text/html", }, ], }, body: html, }; } else { return request; } } catch (error) { console.log(`Error ${error.message}`); return `Error ${error}`; }

The create-react-app utility configures tools such as Babel and webpack for the client-side React application. However, it is not designed to work with SSR. To make the functions work as expected, I transpile these into CommonJS format in addition to transpiling React JSX files. The standard tool for this task is Babel. To add it to this project, I create the configuration file .babelrc.json with instructions to transpile the functions into Node.js v12 format:

{ "presets": [ [ "@babel/preset-env", { "targets": { "node": 12 } } ], "@babel/preset-react" ]

I also include all the dependencies. I use the popular frontend tool webpack, which also works with Lambda functions. It adds only the necessary dependencies and minimizes the package size. For this purpose, I create configurations for both functions. You can find these in the webpack.edge.js and webpack.server.js files:

const path = require("path"); module.exports = { entry: "./src/edge/index.js", target: "node", externals: [], output: { path: path.resolve("edge-build"), filename: "index.js", library: "index", libraryTarget: "umd", }, module: { rules: [ { test: /\.js$/, use: "babel-loader", }, { test: /\.css$/, use: "css-loader", }, ], },

The result of running webpack is one file for each build. I use these files to deploy the Lambda and [email protected] functions. To automate the build process, I add several scripts to package.json.

"build-server": "webpack --config webpack.server.js --mode=development",
"build-edge": "webpack --config webpack.edge.js --mode=development",
"build-all": "npm-run-all --parallel build build-server build-edge"

Launch the build by running npm run build-all.

Deploying the application

After the application successfully builds, I deploy to the AWS Cloud. I use AWS CDK for an infrastructure as code approach. The code is located in cdk/lib/ssr-stack.ts.

First, I create an S3 bucket for storing the static content and I pass the name of the bucket as a parameter. To ensure only CloudFront can access my S3 bucket, I use an access identity configuration:

const mySiteBucketName = new CfnParameter(this, "mySiteBucketName", { type: "String", description: "The name of S3 bucket to upload react application" }); const mySiteBucket = new s3.Bucket(this, "ssr-site", { bucketName: mySiteBucketName.valueAsString, websiteIndexDocument: "index.html", websiteErrorDocument: "error.html", publicReadAccess: false, //only for demo not to use in production removalPolicy: cdk.RemovalPolicy.DESTROY }); new s3deploy.BucketDeployment(this, "Client-side React app", { sources: [s3deploy.Source.asset("../simple-ssr/build/")], destinationBucket: mySiteBucket }); const originAccessIdentity = new cloudfront.OriginAccessIdentity( this, "ssr-oia" ); mySiteBucket.grantRead(originAccessIdentity);

I deploy the Lambda function from the build directory and configure an integration with API Gateway. I also note the API Gateway domain name for later use in the CloudFront distribution.

const ssrFunction = new lambda.Function(this, "ssrHandler", { runtime: lambda.Runtime.NODEJS_12_X, code: lambda.Code.fromAsset("../simple-ssr/server-build"), memorySize: 128, timeout: Duration.seconds(5), handler: "index.handler" }); const ssrApi = new apigw.LambdaRestApi(this, "ssrEndpoint", { handler: ssrFunction }); const apiDomainName = `${ssrApi.restApiId}.execute-api.${this.region}`;

I configure the [email protected] function. It’s important to create a function version explicitly to use with CloudFront:

const ssrEdgeFunction = new lambda.Function(this, "ssrEdgeHandler", { runtime: lambda.Runtime.NODEJS_12_X, code: lambda.Code.fromAsset("../simple-ssr/edge-build"), memorySize: 128, timeout: Duration.seconds(5), handler: "index.handler" }); const ssrEdgeFunctionVersion = new lambda.Version( this, "ssrEdgeHandlerVersion", { lambda: ssrEdgeFunction } );

Finally, I configure the CloudFront distribution to communicate with all the origins:

const distribution = new cloudfront.CloudFrontWebDistribution( this, "ssr-cdn", { originConfigs: [ { s3OriginSource: { s3BucketSource: mySiteBucket, originAccessIdentity: originAccessIdentity }, behaviors: [ { isDefaultBehavior: true, lambdaFunctionAssociations: [ { eventType: cloudfront.LambdaEdgeEventType.ORIGIN_REQUEST, lambdaFunction: ssrEdgeFunctionVersion } ] } ] }, { customOriginSource: { domainName: apiDomainName, originPath: "/prod", originProtocolPolicy: cloudfront.OriginProtocolPolicy.HTTPS_ONLY }, behaviors: [ { pathPattern: "/ssr" } ] } ] } );

The template is now ready for deployment. This approach allows you to use this code in your Continuous Integration and Continuous Delivery/Deployment (CI/CD) pipelines to automate deployments of your SSR applications. Also, you can create a CDK construct to reuse this code in different applications.

Cleaning up

To delete all the resources used in this solution, run:

cd react-ssr-lambda/cdk
cdk destroy SSRApiStack
cdk destroy SSRAppStack


This post demonstrates two ways you can implement and deploy a solution for server-side rendering in React applications, by using Lambda or [email protected]

It also shows how to use open-source tools and AWS CDK to automate the building and deployment of such applications.

For more serverless learning resources, visit Serverless Land.