These days, as expected, some chatbots are AI-powered and can generate answers to queries through Retrieval-Augmented Generation (RAG). I have been curious about how this works, built it out myself, and now, we’ll look at how to build an AI-powered RAG chatbot.

For this tutorial, you’ll build a RAG chatbot that answers queries about travel policies to Mars. The chatbot retrieves its answers from our own data source (travel policy documents) stored in an S3 bucket. The document serves as our internal data source for the chatbot to reference when generating prompts.

Instead of scripted responses from pre-trained data, the chatbot will pull contextual answers directly from the knowledge base.

Let's get started :)

Table of Contents

• Prerequisites

• What is Retrieval-Augmented Generation (RAG)?

• What is Amazon Bedrock?

• Getting Started: Access models on Bedrock

• Step 1: Upload Travel Policy Documents to the S3 Bucket

• Step 2: Create a Knowledge base in Amazon Bedrock

• Step 3: Create an Amazon Lex Chatbot

• Step 4: Add a Welcome Intent to Your Chatbot

• Step 5: Build the Chatbot

• Step 6: Adding Amazon QnAIntent

• Conclusion

Prerequisites

• An AWS account, logged in as an IAM user with admin privileges

• Access to Amazon Titan Embeddings G1 - text model on Amazon Bedrock

• Access to Anthropic Claude 3.5 Sonnet on Amazon Bedrock.

• Access to travel policy documents. You can download these from Google Drive here.

• Experience using the AWS console.

• No coding required.

What is Retrieval-Augmented Generation (RAG)?

Large Language Models (LLMs) like GPT-4 and Claude are basically everywhere. They get some things amazingly right and others very interestingly wrong, like hallucinations, where the model generates factually incorrect or fabricated information. This brings us to the idea of RAG.

Marina Danilevsky, Senior Research Scientist at IBM, in a lecture, referred to RAG as a “framework” for helping LLMs be more accurate and up-to-date.

Before going into the full scope of RAG, let’s talk briefly about the “generation” part. Generation, in the context of RAG, refers to LLMs that generate texts in response to a user query, referred to as a prompt.

These LLMs can sometimes give incorrect answers, due to limited context or outdated information. Especially because they only fetch information from pre-trained data. Imagine you're asked how many Grammy Awards your favorite artist has, and you give an answer you read in a magazine four years ago. You might be correct, but there are two problems with this answer: first, you didn't cite a source, and second, it's outdated.

This is the problem LLMs have traditionally had. The answers were outdated, and no credible sources were cited.

Now, imagine if you had looked up the answer first, from a reputable source on Google. Your answer would be more accurate and factual, and if there was ever a doubt from the person who asked the question, you could easily share the link to the reputable source on Google, and there would be no further doubts or questions.

What does this have to do with LLMs and RAG? Well, now, instead of the LLM only getting answers from its pre-trained data, risking providing outdated answers, when RAG gets involved, it retrieves answers to queries directly from a content store, which could comprise external sources, such as the internet, or internal sources, such as documents (which will be used in this tutorial). This way, its generated answers are more accurate.

RAG helps the LLM stay up to date by further retrieving information from other sources rather than solely from its pre-trained data.

What is Amazon Bedrock?

Amazon Bedrock is AWS's managed service that gives you access to foundation models, essentially the core AI engines that power generative AI applications. The beauty of Bedrock is that it handles all the heavy lifting for you. No need to provision GPUs, set up model pipelines, or deal with infrastructure headaches.

It's a single platform where you can experiment with, customize, and deploy top-tier AI models from providers like Anthropic, Stability AI, and Amazon's own Titan models (used in this tutorial).

Here's a practical example: let’s say you're building a customer support chatbot. With Bedrock, you simply pick a language model that fits your needs, fine-tune it for your specific use case, and integrate it into your app, all without touching server configuration or infrastructure code.

Getting Started: Access models on Bedrock

To get access to models on AWS via Bedrock:

• Log in to your AWS IAM account with root privileges.

• Navigate to Amazon Bedrock > Model catalog.

• Locate the “Titan Embeddings G1 - Text” model and “Claude 3.5 Sonnet” models.

When you click these models, you are directed to a page with more details. You don’t need to do anything on this page. We will be using these models later in this tutorial. In the following sections, we’ll walk through the steps to build the chatbot.

Step 1: Upload Travel Policy Documents to the S3 Bucket

To upload documents, navigate to the Amazon S3 page in your AWS console, then create a bucket. For more details on creating a bucket, refer to the AWS documentation. Next, upload the downloaded document to the S3 bucket.

Note that the document is zipped; you will need to unzip it before uploading.

Step 2: Create a Knowledge base in Amazon Bedrock

Now that we have created our S3 buckets and uploaded our documents, we can’t just hook up our chatbot built with Lex directly to the S3 buckets. S3 isn’t really “smart” from an AI perspective. To get the AI capabilities needed to make this work, we need Amazon Bedrock.

First, we need to create a knowledge base in Amazon Bedrock.

To get started, head back to the Bedrock page opened up earlier and navigate to Build > Knowledge Bases. Click Create. From the dropdown, choose “Knowledge base with vector store.” Leave IAM permissions as “Create and use a new service role”. This is what allows Bedrock to access other services. Choose “Amazon S3” as the data source type. Click Next.

Next, click Browse S3 and select the created bucket with the uploaded documents. Click Next. On the next page, click Select model to choose an embedding model. Select the “Titan Embeddings G1 - Text”, then select “Amazon OpenSearch Serverless” and click Apply.

Leave everything else the same and click Next. On the next page, click Create Knowledge Base. Note that this takes some time (a few minutes), so you need to be patient with this step. Once your knowledge base is created, you’ll be taken to a new page with a message like one in the image below:

The second message tells you that you need to sync the knowledge base with data sources. To do this, scroll down to the Data source section, select the data source, then click Sync. Wait a few seconds and everything syncs.

Note: If you have more data than we have in this tutorial (just four PDFs), syncing may take longer.

Now, we have our Bedrock knowledge base set up. The knowledge base connects to the S3 bucket containing the travel documents.

It's now time to create the chatbot. For this, we’ll use Amazon Lex.

Step 3: Create an Amazon Lex Chatbot

In your AWS console, navigate to Amazon Lex, then click Create bot. Select Create a blank bot under the Traditional creation method. For the bot name, you can call it “Mars travel bot” or any name you prefer.

Under the “IAM permissions” section, select Create a role with basic Amazon Lex permissions. Under the “Children’s Online Privacy Protection Act (COPPA)” section, select No, since our bot isn't subject to COPPA, and click Next.

On the next page, enter a short description in the Description text field. Select your preferred voice interaction option available for text-to-speech. This is the voice your users will hear when they use the chatbot.

The cool thing about Lex is that you can play a voice sample for each voice. This can help you make the best decision for your business. Next, click Done.

Step 4: Add a Welcome Intent to Your Chatbot

After hitting the Done button, you should see a page for creating an intent next. An intent is basically an action that fulfils a user's request.

Let's start with creating a welcome intent. To get started, change Intent name to “WelcomeIntent”. Then scroll down to the “Sample utterances” section and add utterances. These are example texts that you expect a user to type or speak when they start using your chatbot. So, if the user says “Hi” the chatbot responds with a welcome message. For this tutorial, I added the following expected utterances:

• “Hi”

• “Hey”

• “hello”

You can add as many as you want.

In the “Initial response” section, you can provide a response to the user's utterance. Under the Message group dropdown, you can type in something like “Hi! welcome! How can I help you today?” Next, click the Advanced options button. This reveals a dialog box. Under Set values, select the “Wait for users input” option. You can select other options, but for this tutorial, we are going with this. Click Update options.

When you navigate back to the Intents page, you’ll notice a “Fallbackintent” intent automatically generated for you. This intent is supposed to be invoked when a user launches your bot with an utterance that differs from the one created for the welcome intent.

Step 5: Build the Chatbot

In the previous step, we built an intent for the bot. Now it's time to build the actual chatbot that bundles up all of this configuration into something usable.

To get started, click Build at the top-right side of your screen.

Once the building is completed, you’ll get a message at the top of the page. Now, it’s time to test the bot. Next, click Test at the top-right side of your screen.

You get a pre-built chatbot for testing your implementation. Enter a text or utterance, in this case, for example, “Hi”, and you get an initial response. Remember, the utterance and initial response were set in the previous section.

When you click on Inspect. You’ll see the current intent. In this case, the welcomeIntent.

At this point, we haven’t fully integrated the AI capabilities required to get answers about travel policies to Mars.

Step 6: Adding Amazon QnAIntent

The Amazon QnAIntent introduces GenAI capabilities to our bot. It is a built-in intent that uses Generative AI to fulfill Frequently Asked Questions (FAQ) requests by querying the authorized knowledge content.

To get started, navigate to Add intent > Use built-in intent on the Intents page. Select the QnAIntent option, as shown in the image below:

Give it a name of your choice. Click Add. You’ll be directed to the intent page. In the “QnA configuration” section, select Claude3.5 Sonnet as the desired model.

For the ID, since we had already created a knowledge base earlier, navigate back to Amazon Bedrock > Knowledge Bases and copy your Knowledge Base ID and paste it into the “Knowledge base for Amazon Bedrock Id” field. Click Save intent. Before testing your changes, click Build to build the bot again.

Now, let’s run a little test with the chatbot. I will be prompting it about items I can expense for my trip.

The image above shows me having a conversation with the chatbot. I sent an utterance for the welcome intent, and it responded with a welcome message. When I asked the chatbot about what items I can expense for the trip, it pulled the information from the Bedrock knowledge base, which is connected to the S3 bucket housing the travel policy documents.

Try experimenting with other questions like “How much does my trip cost?” or “Can I bring my pets?”

Want to add a proper web UI to your bot? Follow the step-by-step instructions in this GitHub repository.

FYI - you should delete resources such as your knowledge base, S3 bucket, and vector store (navigate to Amazon OpenSearch Service > Serverless > Dashboard and delete the knowledge base vector collection) to avoid incurring any unwanted charges from AWS.

Conclusion

You've just built an AI-powered chatbot that pulls answers from your own data sources. No more generic responses or outdated information. By combining Amazon Lex, Bedrock, S3, and RAG, you've created a system that actually understands your documentation/knowledge base and delivers accurate, contextual answers.

The real power here isn't just in the technology stack, it's in what you can do with it. Scale this approach to handle customer support queries, internal HR questions, product documentation, or any scenario where you need instant, accurate responses from your own knowledge base.

This is just the beginning. Experiment with different foundation models in Bedrock, expand your knowledge base with more documents, or refine your intents to handle more complex conversations. The infrastructure is built, now it's time to customize it for your specific use case.

If you found this tutorial helpful, consider sharing it with your team or fellow developers.

If you're a junior cloud engineer ready to move beyond theoretical AWS concepts and build something real, this tutorial walks you through creating a complete serverless coffee shop management system.

You'll learn how to architect, deploy, and secure a production-ready application using AWS's most powerful serverless services.

Without further ado, let's get started!

Table of Contents

• Prerequisites

• Tools We’ll be Using

• What We are Building

• Why Serverless?

• Architectural Overview

• Build a Serverless Full-Stack App

  • Step 1: Create a DynamoDB table

  • Step 2: Create an IAM role for the Lambda function

  • Step 3: Create Lambda Layer And Lambda Functions

  • Step 4: Create an API Gateway To Expose Lambda Functions

  • Step 5: Set up React Application And Upload Build To S3 Bucket

  • Step 6: Set up Amazon API Gateway Authorizer

  • Step 7: Create Cloudfront Distribution With Behaviors For S3 And API Gateway

  • Step 8: Set up React Application And Upload Build To S3 Bucket

• Troubleshooting Access Denied Error

  • Step 1: Set up Origin Access Control (OAC)

  • Step 2: Update S3 Bucket Policy

  • Step 3: Set Default Root Object

• Conclusion

Prerequisites

• Basic knowledge of AWS.

• Basic knowledge of AWS serverless services.

• Knowledge of React (not required).

• Basic knowledge of Postman or other API testing tools.

Tools We’ll be Using

• React.js

• AWS Lambda

• DynamoDB

• API Gateway

• Cognito

• CloudFront

What We are Building

We'll build a complete serverless coffee shop management system using AWS cloud services. Coffee shop owners will securely log in through AWS Cognito authentication and have full control over their inventory, adding new products, updating stock levels, viewing current inventory, and removing discontinued items. To follow along with this tutorial, you can clone the repo here.

This is what our user interface (UI) looks like:

Why Serverless?

AWS serverless services like Lambda, Cognito, and API Gateway automatically scale to zero during quiet periods and instantly ramp up when traffic spikes. While 'serverless' might sound like there are no servers at all, this isn't actually the case. It means that AWS handles all the heavy lifting, provisioning, managing, and scaling of the infrastructure behind the scenes. You only pay for what you use.

Architectural Overview

Our architecture uses DynamoDB as the data store, with Lambda functions (enhanced by Lambda layers) handling all API Gateway requests. Cognito secures the API Gateway, while CloudFront CDN delivers everything globally. The React frontend connects directly to the Cognito UserPool and gets hosted on S3 with CloudFront distribution. For production deployments, you can add a custom domain using CloudFlare and AWS Certificate Manager.

Build a Serverless Full-Stack App

In this section, you’ll build a full-stack serverless architecture.

Step 1: Create a DynamoDB table

To create a DynamoDB table, navigate to your AWS console and select the DynamoDB section. You can do this quickly by typing “DynamoDB” into the AWS search bar and clicking on DynamoDB. Next, follow the steps below to complete your table creation:

1. Click Create table.

2. Input table name as “CoffeeShop” or anything you want to name it.

3. Input partition key as “coffeeId” or anything you want to name it.

4. Click Create table.

Step 1.1: Create items

You need to create items for the table. This helps with testing connectivity to your DynamoDB table.

For our use case, we’ll be creating an item in the table called “coffee” and input attributes such as coffeeId, name, price, and availability. To create an item:

1. Click Explore items on the left navigation pane.

2. Click Create items.

3. Click the CoffeeShop radio button, then click Create item.

4. Click Add new attribute. This allows you to add different data types such as strings and booleans. The JSON structure below shows the attributes created.

{
    "coffeeId": "c123",
    "name": "new cold coffee",
    "price": 456,
    "available": true
}

Step 2: Create an IAM role for the Lambda function

Next, create a Lambda function that interacts with the DynamoDB table using an IAM role attached to the function. We’ll be setting up an IAM role named "CoffeeShopRole" that serves as a shared execution role for all Lambda functions in the coffee shop application.

This role includes the following permissions:

• CloudWatch Logs: Full logging capabilities (create, write, and manage log streams)

• DynamoDB Access: Complete read, write, update, and delete operations on the "CoffeeShop" table.

To do this:

1. Navigate to the AWS IAM console.

2. Navigate to Roles.

3. Click Create role.

4. Select the Lambda service.

5. Search for “AWSLambdaBasicExecutionRole.”

6. Name your role and click Create role.

This is what the role looks like:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "dynamodb:PutItem",
                "dynamodb:DeleteItem",
                "dynamodb:GetItem",
                "dynamodb:Scan",
                "dynamodb:UpdateItem"
            ],
            "Resource": "arn:aws:dynamodb::<DYNAMODB_TABLE_NAME>"
        },
        {
            "Effect": "Allow",
            "Action": [
                "logs:CreateLogGroup",
                "logs:CreateLogStream",
                "logs:PutLogEvents"
            ],
            "Resource": "*"
        }
    ]
}

This policy allows us to create CloudWatch logs. Next, create an inline policy to allow communications to DynamoDB. Select the following actions for the table:

• Get

• Put

• Update

• Scan

• Delete

Next, connect your table ARN to the policy by navigating to the created table and copying the ARN into the policy.

Step 3: Create Lambda Layer And Lambda Functions

Now, we need to connect our Lambda function to the DynamoDB table. For this, we’ll need the DynamoDB JavaScript SDK. To get started, create two folders: lambda > get in your IDE, preferably VS Code. Navigate into these folders in your terminal and run the npm init command to initialize your project. Update your package.json file with this:

{
  "name": "get",
  "type": "module",
  "version": "1.0.0",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC",
  "description": ""
}

Note: that we’ll be using ECMAScript throughout the course of this tutorial.

Next, we have to create a reusable Node.js Lambda layer containing the DynamoDB JavaScript SDK and shared utility functions. This layer acts like a common library that can be attached to multiple Lambda functions, eliminating the need to bundle the same dependencies repeatedly in each function's deployment package.

To use the SDK, create a new folder in your directory titled index.mjs and paste in the code below:

// getCoffee function
import { DynamoDBClient, GetItemCommand } from "@aws-sdk/client-dynamodb"; // ESM import
const config = {
    region: "us-east-1",
};
const client = new DynamoDBClient(config);
export const getCoffee = async (event) => {
    const coffeeId = "c123";
    const input = {
        TableName: "CoffeShop",
        Key: {
            coffeeId: {
                S: coffeeId,
            },
        },
    };
    const command = new GetItemCommand(input);
    const response = await client.send(command);
    console.log(response);
    return response;
}

The code above is the getCoffee function that connects to the DynamoDB table called CoffeShop, looks up the coffee with the ID c123, and displays its details.

Change region to your specific region.

Next, install the Lambda dependencies for the SDK using the command below:

npm i @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb

Then, create a zip file for all the current files using the command below:

zip -r get.zip ./*

This creates a zip file in your project directory. Now, navigate to the Lambda function page on your AWS console and upload this zip file.

Click Test to test your application. If you run into an error, edit the Runtime settings and change the handler name to index.getCoffee. Deploy and run the code again, you should get a successful response from DynamoDB as shown below:

Response:

{
  "$metadata": {
    "httpStatusCode": 200,
    "requestId": "R14Q5UMTP3K9P9NAF1OGG0IB57VV4KQNSO5AEMVJF66Q9ASUAAJG",
    "attempts": 1,
    "totalRetryDelay": 0
  },
  "Item": {
    "available": {
      "BOOL": true
    },
    "price": {
      "N": "34"
    },
    "name": {
      "S": "My New Coffee"
    },
    "coffeeId": {
      "S": "c123"
    }
  }
}

Now, let’s make the necessary changes to make our function ready for the API gateway to get the API. When someone requests a coffee using the /coffee endpoint, we want the app to returns a list of all coffees. But if the request is made to /coffee/c123 or /coffee/id, then the app returns only details about that specific coffee.

To do this, head back to your index.mjs file and paste in the code below:

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, GetCommand, ScanCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({});
const docClient = DynamoDBDocumentClient.from(client);
const tableName = process.env.tableName || "CoffeShop";
const createResponse = (statusCode, body) => {
    const responseBody = JSON.stringify(body);
    return {
        statusCode,
        headers: { "Content-Type": "application/json" },
        body: responseBody,
    };
};
export const getCoffee = async (event) => {
    const { pathParameters } = event;
    const { id } = pathParameters || {};
    try {
        let command;
        if (id) {
            command = new GetCommand({
                TableName: tableName,
                Key: {
                    "coffeeId": id,
                },
            });
        }
        else {
            command = new ScanCommand({
                TableName: tableName,
            });
        }
        const response = await docClient.send(command);
        return createResponse(200, response);
    }
    catch (err) {
        console.error("Error fetching data from DynamoDB:", err);
        return createResponse(500, { error: err.message });
    }
}

Run the zip -r get.zip ./* command again and re-upload the zip file in your Lambda function page.

This AWS Lambda function implements a serverless API endpoint for retrieving coffee data from a DynamoDB table, using the AWS SDK v3 to create a document client that can either fetch a specific coffee item by ID (when an id parameter is provided in the URL path) or return all items from the table (when no ID is specified, though there's a missing import for ScanCommand).

The function extracts the coffee ID from the incoming event's path parameters, constructs the appropriate DynamoDB command (GetCommand for single items or ScanCommand for all items), executes the database operation, and returns a properly formatted HTTP response with JSON headers and appropriate status codes - either a 200 success response with the coffee data or a 500 error response if something goes wrong during the database operation.

Repeat the steps above for the create, update, and delete functions. You can find these functions in your cloned project repo.

Step 4: Create an API Gateway To Expose Lambda Functions

To create an API that points to the Lambda function:

1. Navigate to API Gateway > Routes and click Create.

2. Create the following endpoints.

GET /coffee  -> getCoffee lambda function
GET /coffee/{id}  -> getCoffee lambda function
POST /coffee  -> createCoffee lambda function
PUT /coffee/{id}  -> updateCoffee lambda function
DELETE /coffee/{id}  -> deleteCoffee lambda function

3. Navigate to Integrations and create integrations for these endpoints. To do this, go to the Manage integrations tab, click Create, and select Lambda as the integration target.

Now, in your API Gateway portal, click on API: CoffeeShop...(random numbers) and copy the invoke URL for testing, as shown in the image below:

The get request with an id returns a 200 OK response with the created items in DynamoDB. You can play around with the rest of the endpoints on Postman :)

Adding Lambda Layer to Solve the Dependency Issue

Before we continue with this tutorial, I’d like to address one problem with the previous steps so far. All functions use the same dependency, but for each function, we had to maintain separate node_modules folders and packages.json files. To fix this issue, we’ll be using Lamba Layer. Layer contains all the dependencies, while the functions contain only your code.

To get started:

1. Create a new folder in your IDE called LambdaWithLayer.

2. Create two additional folders under the LambdaWithLayer named LambdaFunctionsWithLayer and nodejs.

Note: You must use the name nodejs for this to work.

3. Navigate to the nodejs folder and initialize using the npm init command.

4. Install dependencies using the command below:

npm i @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb

5. Create a new file called utils.js under the nodejs folder and paste in the code below:

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import {
    DynamoDBDocumentClient,
    ScanCommand,
    GetCommand,
    PutCommand,
    UpdateCommand,
    DeleteCommand
} from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({});
const docClient = DynamoDBDocumentClient.from(client);
const createResponse = (statusCode, body) => {
    return {
        statusCode,
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(body),
    };
};
export {
    docClient,
    createResponse,
    ScanCommand,
    GetCommand,
    PutCommand,
    UpdateCommand,
    DeleteCommand
};

Here, we imported all the commands for our API operations. Now, we can create Lambda Functions without installing the SDK dependencies for each one. For example, you can create a get folder under the LambdaFunctionsWithLayer folder for the get function, then create an index.mjs file under the get folder. Next, paste the code below:

import { docClient, GetCommand, ScanCommand, createResponse } from '/opt/nodejs/utils.mjs'; // Import from Layer
const tableName = process.env.tableName || "CoffeShop";
export const getCoffee = async (event) => {
    const { pathParameters } = event;
    const { id } = pathParameters || {};
    try {
        let command;
        if (id) {
            command = new GetCommand({
                TableName: tableName,
                Key: {
                    "coffeeId": id,
                },
            });
        }
        else {
            command = new ScanCommand({
                TableName: tableName,
            });
        }
        const response = await docClient.send(command);
        return createResponse(200, response);
    }
    catch (err) {
        console.error("Error fetching data from DynamoDB:", err);
        return createResponse(500, { error: err.message });
    }
}

Now we can see that, in the code, we no longer require dependencies for the get function. We just imported from the layer.

Repeat the above steps for other functions.

Note: You can find the code for other functions in the cloned repo.

6. Create a zip folder for each function. You can do this by creating a file called create_zip.sh under the LambdaFunctionsWithLayer folder. Then paste the script below:

echo "Creating zip for layer"
zip -r layer.zip nodejs
echo "Creating zip for GET Function"
cd LambdaFunctionsWithLayer/get
zip -r get.zip index.mjs
mv get.zip ../../
cd ../..
echo "Creating zip for POST Function"
cd LambdaFunctionsWithLayer/post
zip -r post.zip index.mjs
mv post.zip ../../
cd ../..
echo "Creating zip for UPDATE Function"
cd LambdaFunctionsWithLayer/update
zip -r update.zip index.mjs
mv update.zip ../../
cd ../..
echo "Creating zip for DELETE Function"
cd LambdaFunctionsWithLayer/delete
zip -r delete.zip index.mjs
mv delete.zip ../../
cd ../..
echo "Success!"

Run the script using the sh create_zip.sh command. This creates zip files (including a layer.zip file) that you can upload to your AWS Lambda function Layer page.

7. In your AWS Lambda function page, navigate to Layers and upload the layer.zip file**.**

8. Update the functions by uploading the newly created zip files for each code.

9. Add the layer to the function by clicking Layers in the function view:

Next, click Add a layer, then select Custom layers. Then choose “DynamoDBLayer” and version “1”.

10. Click Add.

11. Repeat for all the other functions.

Step 5: Set up React Application And Upload Build To S3 Bucket

To set up our React application, navigate to the frontend folder of the cloned repository on your local machine and run npm install to install the dependencies. Then run npm run dev to start your development environment on your local machine. You should see the preview in your browser at: http://localhost:5173/.

If you inspect the page using Chrome DevTools, you’ll see that we ran into some CORS error:

Now, let’s fix this problem. To do that:

1. Navigate your API Gateway page.

2. Click on CORS on the left navigation panel.

3. Click Configure.

4. Copy your localhost URL and paste it into the Access-Control-Allow-Origin field.

Ensure to remove the / at the end of your URL as shown in the image above.

5. Click Add.

6. Enter the Access-Control-Allow-Headers field with the text content-type and click Add.

7. Include GET, POST, OPTIONS, PUT, and DELETE in Access-Control-Allow-Methods.

8. Click Save.

Now it returns our coffee, and the CORS error has been resolved.

When you add a new coffee, you should see the newly created items in your DynamoDB database.

Step 6: Set up Amazon API Gateway Authorizer

AWS Congnito helps you secure your Amazon API Gateway. Gateway validates the access token with Amazon Cognito to ensure it is valid and has not expired, and grants or denies access based on token validity.

To get started:

1. Navigate to Amazon Cognito > User pools.

2. Click Create user pool.

3. Select Single-page application (SPA).

4. Select email as the preferred sign-in and sign-up method.

5. Use http://localhost:5174/ or your own local URL as the return URL.

6. Click Create user directory.

You’ll be presented with a page containing code that we can copy and paste into our app for integration. But before we do that, let's head back to API Gateway and integrate it with Cognito. To do that:

1. Go to the Authorization section in API Gateway.

2. Navigate to Manage authorizers.

3. Click Create.

4. Select JWT and name it “Cognito-CoffeeShop”

5. Copy your issuer URL from Cognito Overview. Your issuer URL is the Token signing key URL. If you click on the URL, you’ll be taken to your browser, where you'll see the keys that’ll be used for verification.

6. For the Audience, navigate to the Cognito user pool, then to App clients, and select CoffeShopClient. Copy the Client ID.

7. Click Create.

8. Go to Routes and add authorizations to each endpoint.

Now, to integrate with our front-end app:

Navigate into the frontend folder and run the command below:

npm install oidc-client-ts react-oidc-context --save

2. Go to the App clients section in Cognito user pools to find the readily available code snippets for integration.

3. Edit your main.jsx file to include the code below:

import { createRoot } from 'react-dom/client'
import { BrowserRouter as Router, Route, Routes } from "react-router-dom";
import './index.css'
import App from './App.jsx'
import ItemDetails from "./ItemDetails";
import { AuthProvider } from "react-oidc-context";
const cognitoAuthConfig = {
  authority: "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_rXq7q3KLm",
  client_id: "6fjfrlaup7oph5lhf1q8q6pnp4",
  redirect_uri: "http://localhost:5174",
  response_type: "code",
  scope: "email openid phone",
};
createRoot(document.getElementById('root')).render(
  <AuthProvider {...cognitoAuthConfig}>
    <Router>
      <div>
        <Routes>
          <Route path="/" element={<App />} />
          <Route path="/details/:id" element={<ItemDetails />} />
        </Routes>
      </div>
    </Router>
  </AuthProvider>
)

Here, we imported AuthProvider from react-oidc-context, then wrapped our app with AuthProvider. Then, move the code in the App.jsx file to a newly created Home.jsx file, and update App.jsx file with the code below:

import { useEffect, useState } from "react";
import "./App.css";
// App.js
import { useAuth } from "react-oidc-context";
function App() {
  const auth = useAuth();
  const signOutRedirect = () => {
    const clientId = "6fjfrlaup7oph5lhf1q8q6pnp4";
    const logoutUri = "http://localhost:5174/";
    const cognitoDomain = "https://us-east-1rxq7q3klm.auth.us-east-1.amazoncognito.com";
    window.location.href = `${cognitoDomain}/logout?client_id=${clientId}&logout_uri=${encodeURIComponent(logoutUri)}`;
  };
  if (auth.isLoading) {
    return <div>Loading...</div>;
  }
  if (auth.error) {
    return <div>Encountering error... {auth.error.message}</div>;
  }
  if (auth.isAuthenticated) {
    return (
      <div>
        <button onClick={() => auth.removeUser()}>Sign out</button>
        <Home />
      </div>
    );
  }
  return (
    <div>
      <button onClick={() => auth.signinRedirect()}>Sign in</button>
      <button onClick={() => signOutRedirect()}>Sign out</button>
    </div>
  );
}
export default App;

Now, when you run the application again, you should see this login page on your browser:

When you click on Sign in, you’ll get directed to the Sign in page. Click Sign up. You should see the page below to create your account.

During sign-up, a verification code is sent to your sign-up email. Once you’re logged in, you can then access your coffee dashboard.

Step 7: Create Cloudfront Distribution With Behaviors For S3 And API Gateway

To create a distribution.

1. Navigate to CloudFront.

2. Click Create distribution.

3. In the Origin page, select the S3 bucket and browse through your created S3 buckets.

4. Select your coffee shop bucket.

5. Set origin path to /dist.

6. Select Origin access control under Origin access.

7. Update your React code and AWS Cognito with the distribution domain name provided in the CloudFront log-in pages tab.

Step 8: Set up React Application And Upload Build To S3 Bucket

In this step, we’ll be building our React application and uploading the static files to an Amazon S3 bucket, which is then served from a CloudFront distribution.

To get started:

1. Create an S3 bucket and give it the name “mycoffeeShop123new”. This name should be globally unique across all AWS accounts.

2. In the frontend folder, run the npm run build command. This creates a dist folder in your directory.

3. Head back to the S3 bucket and drag-and-drop the dist folder into S3 to upload it.

4. Click Upload.

Now, copy your CloudFront distribution URL and try to access your site in a private browser, for example, Chrome incognito. You should see your site live in the browser.

Troubleshooting Access Denied Error

You may encounter an access denied error in the browser:

<Error>
    <Code>AccessDenied</Code>
    <Message>Access Denied</Message>
</Error>

It may be because of a likely S3 + CloudFront configuration error. Here are the steps to resolve this issue:

Step 1: Set up Origin Access Control (OAC)

1. Go to CloudFront > Your Distribution > Origins tab.

2. Select your S3 origin and click Edit.

3. Under Origin access, select Origin access control settings (recommended)

4. Click Create new OAC (or select an existing one).

5. Click Save changes.

Step 2: Update S3 Bucket Policy

After saving, CloudFront will show you a "Copy Policy" button. Click it, then:

1. Go to your S3 bucket > Permissions tab.

2. Scroll to Bucket policy and click Edit.

3. Paste the copied policy (it should look like this):

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowCloudFrontServicePrincipal",
            "Effect": "Allow",
            "Principal": {
                "Service": "cloudfront.amazonaws.com"
            },
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::YOUR-BUCKET-NAME/*",
            "Condition": {
                "StringEquals": {
                    "AWS:SourceArn": "arn:aws:cloudfront::YOUR-ACCOUNT-ID:distribution/YOUR-DISTRIBUTION-ID"
                }
            }
        }
    ]
}

4. Click Save changes.

Step 3: Set Default Root Object

1. Go back to CloudFront > Your Distribution > General tab.

2. Click Edit.

3. Set Default root object to index.html.

4. Save changes.

Now, try accessing the site again. It should work.

This brings us to the end of this tutorial. I hope you were able to learn a thing or two about building serverless systems :)

Conclusion

Congratulations! You've just built a production-ready serverless application from the ground up. You've successfully architected a complete CRUD system that automatically scales, stays secure with Cognito authentication, and costs you only what you actually use.

With a single PUT operation, you can actually upload an object of up to 5 GB. But, when it comes to uploading larger objects (above 5GB), using Amazon S3’s Multipart Upload feature is a better approach.

Multipart upload makes it easier for you to upload larger files and objects by segmenting them into smaller, independent chunks that upload separately and reassemble on S3.

In this guide, you’ll learn how to implement multipart uploads using AWS CLI.

Table of Contents

• Prerequisites

• How Multipart Uploads Work

• Getting started

  • Step 1: Download the AWS CLI

  • Step 2: Configure AWS IAM credentials

• Step 1: Split Object

• Step 2: Create an Amazon S3 bucket

• Step 3: Initiate Multipart Upload

• Step 4: Upload split files to S3 Bucket

• Step 5: Create a JSON File to Compile ETag Values

• Step 6: Complete Mulitipart Upload to S3

• Conclusion

Prerequisites

To follow this guide, you should have:

• An AWS account.

• Knowledge of AWS and the S3 service.

• AWS CLI is installed on your local machine.

How Multipart Uploads Work

In a multipart upload, large file transfers are segmented into smaller chunks that get uploaded separately to Amazon S3. After all segments complete their upload process, S3 reassembles them into the complete object.

For example, a 160GB file broken into 1GB segments generates 160 individual upload operations to S3. Each segment receives a distinct identifier while preserving sequence information to guarantee proper file reconstruction.

The system supports configurable retry logic for failed segments and allows upload suspension/resumption functionality. Here’s a diagram that shows what the multipart upload process looks like:

Getting Started

Before you get started with this guide, make sure that you have the AWS CLI installed on your machine. If you don’t already have that installed, follow the steps below.

Step 1: Download the AWS CLI

To download the CLI, visit the CLI download documentation. Then, download the CLI based on your operating system (Windows, Linux, macOS). Once the CLI is installed, the next step is to configure your AWS IAM credentials in your terminal.

Step 2: Configure AWS IAM credentials

To configure your AWS credentials, navigate to your terminal and run the command below:

aws configure

This command prompts you to paste in certain credentials, such as AWS Access Key ID and secret ID. To obtain these credentials, create a new IAM user in your AWS account. To do this, follow the steps below. (You can skip these steps if you already have an IAM user and security credentials.)

1. Sign in to your AWS dashboard.

2. Click on the search bar above your dashboard and search “IAM”.

3. Click on IAM.

4. In the left navigation pane, navigate to Access management > Users.

5. Click Create user.

6. During IAM user creation, attach a policy directly by selecting Attach policies directly in step 2: Set permissions.

7. Give the user admin access by searching “admin” in the permission policies search bar and selecting AdministratorAccess.

8. On the next page, click Create user.

9. Click on the created user in the Users section and navigate to Security credentials.

10. Scroll down and click Create access key.

11. Select the Command Line Interface (CLI) use case.

12. On the next page, click Create access key.

You will now see your access keys. Please keep these safe and do not expose them publicly or share them with anyone.

You can now copy these access keys into your terminal after running the aws configure command.

You will be prompted to include the following details:

• AWS Access Key ID: gotten from the created IAM user credentials. See steps above.

• AWS Secret Access Key: gotten from the created IAM user credentials. See steps above.

• Default region name: default AWS region name, for example, us-east-1.

• Default output format: None.

Now we’re done with the CLI configuration.

To confirm that you’ve successfully installed the CLI, run the command below:

aws --version

You should see the CLI version in your terminal as shown below:

Now, you are ready for the following main steps for multipart uploads :)

Step 1: Split Object

The first step is to split the object you intend to upload. For this guide, we’ll be splitting a 188MB video file into smaller chunks.

Note that this process also works for much larger files.

Next, locate the object you intend to upload in your system. You can use the cd command to locate the object in its stored folder using your terminal.

Then run the split command below:

split -b <SIZE>mb <filename>

Replace <SIZE> with your desired chunk size in megabytes (for example, 150, 100, 200).

For this use case, we’ll be splitting our 188mb video file into bytes. Here’s the command:

split -b 31457280 videoplayback.mp4

Next, run the ls -lh command on your terminal. You should get the output below:

Here, you can see that the 188MB file has been split into multiple parts (30MB and 7.9MB). When you go to the folder where the object is saved in your system files, you will see additional files with names that look like this:

• xaa

• xab

• xac

and so on. These files represent the different parts of your object. For example, xaa is the first part of your file, which will be uploaded first to S3. More on this later in the guide.

Step 2: Create an Amazon S3 Bucket

If you don’t already have an S3 bucket created, follow the steps in the AWS Get Started with Amazon S3 documentation to create one.

Step 3: Initiate Multipart Upload

The next step is to initiate a multipart upload. To do this, execute the command below:

aws s3api create-multipart-upload --bucket DOC-EXAMPLE-BUCKET --key large_test_file

In this command:

• DOC-EXAMPLE-BUCKET is your S3 bucket name.

• large_test_file is the name of the file, for example, videoplayback.mp4.

You’ll get a JSON response in your terminal, providing you with the UploadId. The response looks like this:

{
    "ServerSideEncryption": "AES345",
    "Bucket": "s3-multipart-uploads",
    "Key": "videoplayback.mp4",
    "UploadId": "************************************"
}

Keep the UploadId somewhere safe in your local machine, as you will need it for later steps.

Step 4: Upload Split Files to S3 Bucket

Remember those extra files saved as xaa, xab, and so on? Well, now it’s time to upload them to your S3 bucket. To do that, execute the command below:

aws s3api upload-part --bucket DOC-EXAMPLE-BUCKET --key large_test_file --part-number 1 --body large_test_file.001 --upload-id exampleTUVGeKAk3Ob7qMynRKqe3ROcavPRwg92eA6JPD4ybIGRxJx9R0VbgkrnOVphZFK59KCYJAO1PXlrBSW7vcH7ANHZwTTf0ovqe6XPYHwsSp7eTRnXB1qjx40Tk

• DOC-EXAMPLE-BUCKET is your S3 bucket name.

• large_test_file is the name of the file, for example, videoplayback.mp4

• large_test_file.001 is the name of the file part, for example, xaa.

• upload-id replaces the example ID with your saved UploadId.

The command returns a response that contains an ETag value for the part of the file that you uploaded.

{
    "ServerSideEncryption": "aws:kms",
    "ETag": "\"7f9b8c3e2a1d5f4e8c9b2a6d4e8f1c3a\"",
    "ChecksumCRC64NVME": "mK9xQpD2WnE="
}

Copy the ETag value and save it somewhere on your local machine, as you’ll need it later as a reference.

Continue uploading the remaining file parts by repeating the command above, incrementing both the part number and file name for each subsequent upload. For example: xaa becomes xab, and --part-number 1 becomes --part-number 2, and so forth.

Note that upload speed depends on how large the object is and how good your internet speed is.

To confirm that all the file parts have been uploaded successfully, run the command below:

aws s3api list-parts --bucket s3-multipart-uploads --key videoplayback.mp4 --upload-id p0NU3agC3C2tOi4oBmT8lHLebUYqYXmWhEYYt8gc8jXlCStEZYe1_kSx1GjON2ExY_0T.4N4E6pjzPlNcji7VDT6UomtNYUhFkyzpQ7IFKrtA5Dov8YdC20c7UE20Qf0

Replace the example upload ID with your actual upload ID.

You should get a JSON response like this:

{
    "Parts": [
        {
            "PartNumber": 1,
            "LastModified": "2025-07-27T14:22:18+00:00",
            "ETag": "\"f7b9c8e4d3a2f6e8c9b5a4d7e6f8c2b1\"",
            "Size": 26214400
        },
        {
            "PartNumber": 2,
            "LastModified": "2025-07-27T14:25:42+00:00",
            "ETag": "\"a8e5d2c7f9b4e6a3c8d5f2e9b7c4a6d3\"",
            "Size": 26214400
        },
        {
            "PartNumber": 3,
            "LastModified": "2025-07-27T14:28:15+00:00",
            "ETag": "\"c4f8e2b6d9a3c7e5f8b2d6a9c3e7f4b8\"",
            "Size": 26214400
        },
        {
            "PartNumber": 4,
            "LastModified": "2025-07-27T14:31:03+00:00",
            "ETag": "\"e9c3f7a5d8b4e6c9f2a7d4b8c6e3f9a2\"",
            "Size": 26214400
        },
        {
            "PartNumber": 5,
            "LastModified": "2025-07-27T14:33:47+00:00",
            "ETag": "\"b6d4a8c7f5e9b3d6a2c8f4e7b9c5d8a6\"",
            "Size": 26214400
        },
        {
            "PartNumber": 6,
            "LastModified": "2025-07-27T14:36:29+00:00",
            "ETag": "\"d7e3c9f6a4b8d2e5c7f9a3b6d4e8c2f5\"",
            "Size": 26214400
        },
        {
            "PartNumber": 7,
            "LastModified": "2025-07-27T14:38:52+00:00",
            "ETag": "\"f2a6d8c4e7b3f6a9c2d5e8b4c7f3a6d9\"",
            "Size": 15728640
        }
    ]
}

This is how you verify that all parts have been uploaded.

Step 5: Create a JSON File to Compile ETag Values

The document we are about to create helps AWS understand which parts the ETags represent. Gather the ETag values from each uploaded file part and organize them into a JSON structure.

Sample JSON format:

{
    "Parts": [{
        "ETag": "example8be9a0268ebfb8b115d4c1fd3",
        "PartNumber":1
    },

    ....

    {
        "ETag": "example246e31ab807da6f62802c1ae8",
        "PartNumber":4
    }]
}

Save the created JSON file in the same folder as your object and name it multipart.json. You can use any IDE of your choice to create and save this document.

Step 6: Complete Mulitipart Upload to S3

To complete the multipart upload, run the command below:

aws s3api complete-multipart-upload --multipart-upload file://fileparts.json --bucket DOC-EXAMPLE-BUCKET --key large_test_file --upload-id exampleTUVGeKAk3Ob7qMynRKqe3ROcavPRwg92eA6JPD4ybIGRxJx9R0VbgkrnOVphZFK59KCYJAO1PXlrBSW7vcH7ANHZwTTf0ovqe6XPYHwsSp7eTRnXB1qjx40Tk

Replace fileparts.json with multipart.json.

You should get an output like this:

{
    "ServerSideEncryption": "AES256",
    "Location": "https://s3-multipart-uploads.s3.eu-west-1.amazonaws.com/videoplayback.mp4",
    "Bucket": "s3-multipart-uploads",
    "Key": "videoplayback.mp4",
    "ETag": "\"78298db673a369adf33dd8054bb6bab7-7\"",
    "ChecksumCRC64NVME": "d1UPkm73mAE=",
    "ChecksumType": "FULL_OBJECT"
}

Now, when you go to your S3 bucket and hit refresh, you should see the uploaded object.

Here, you can see the complete file, file name, type, and size.

Conclusion

Multipart uploads transform large file transfers to Amazon S3 from fragile, all-or-nothing operations into robust, resumable processes. By segmenting files into manageable chunks, you gain retry capabilities, better performance, and the ability to handle objects exceeding S3's 5GB single-upload limit.

This approach is essential for production environments dealing with database backups, video files, or any large assets. With the AWS CLI techniques covered in this guide, you're now equipped to handle S3 transfers confidently, regardless of file size or network conditions.

Check out this documentation from the AWS knowledge center to learn more about multi-part uploads using AWS CLI.

This is why documentation tools like Docusaurus are great for helping you create visually stunning documentation sites in abo 5 minutes.

In this tutorial, I'll show you how to build a documentation site using React and Docusaurus.

If you are new to Docusaurus, you are probably wondering, “why React?, why not any other framework like Next.js?”, Don’t worry – I’ll also answer this question in this guide.

Table of Contents

• Prerequisites

• What is Docusaurus?

• Getting Started and Installation

  • Project structure

• How to Start Your Docusaurus Website

• How to Create Documentation (Overview)

• MDX and React Components

  • Tabs

  • Alerts or Admonitions

  • Code blocks

• Docusaurus Blog

• Custom Pages

• Styling in Docusaurus

• Deployment

• Conclusion

Prerequisites

To follow along with this guide, you should have:

• Node.js version 18.0 or above installed

• Basic knowledge of React and Markdown

• IDE (preferably VSCode)

What is Docusaurus?

Docusaurus was released by the Meta Open Source team in 2017 to help devs build, deploy, and maintain documentation websites easily and quickly. The project’s other goal was to improve the speed of both developers and end users using the PRPL pattern.

Some of its cool features include search and localization, powered by Algolia (search) and Crowdin (language support and internationalization).

Now, let’s talk about why we’re using React for this tutorial. Well, Docusaurus is built on top of React, which makes it easy to customize the website. Also, Docusaurus supports Markdown and MDX (which lets you use React JSX in your markdown content).

As a technical writer myself, I love that this tool supports Markdown, which I'm quite familiar with. It allows me to focus on creating helpful documentation without worrying about converting the text to other text formats.

Getting Started and Installation

Getting started with Docusaraus is pretty straightforward. The first thing you need to do is head over to your terminal and run the command below:

npx create-docusaurus@latest my-website classic

Note: The Docusaurus team recommends the classic template because it is easier to get started with fast. It also contains @docusaurus/preset-classic – which includes standard documentation, a blog, custom pages, and a CSS framework (with dark mode support).

Project structure

After installation, this is what your newly created Docusaurus project structure should look like:

📦my-website
┣ 📂blog
┃ ┣ 📂2021-08-26-welcome
┃ ┃ ┣ 📜docusaurus-plushie-banner.jpeg
┃ ┃ ┗ 📜index.md
┃ ┣ 📜2019-05-28-first-blog-post.md
┃ ┣ 📜2019-05-29-long-blog-post.md
┃ ┣ 📜2021-08-01-mdx-blog-post.mdx
┃ ┣ 📜authors.yml
┃ ┗ 📜tags.yml
┣ 📂docs
┃ ┣ 📂tutorial-basics
┃ ┃ ┣ 📜congratulations.md
┃ ┃ ┣ 📜create-a-blog-post.md
┃ ┃ ┣ 📜create-a-document.md
┃ ┃ ┣ 📜create-a-page.md
┃ ┃ ┣ 📜deploy-your-site.md
┃ ┃ ┣ 📜markdown-features.mdx
┃ ┃ ┗ 📜_category_.json
┃ ┣ 📂tutorial-extras
┃ ┃ ┣ 📂img
┃ ┃ ┃ ┣ 📜docsVersionDropdown.png
┃ ┃ ┃ ┗ 📜localeDropdown.png
┃ ┃ ┣ 📜manage-docs-versions.md
┃ ┃ ┣ 📜translate-your-site.md
┃ ┃ ┗ 📜_category_.json
┃ ┗ 📜intro.md
┣ 📂src
┃ ┣ 📂components
┃ ┃ ┗ 📂HomepageFeatures
┃ ┃ ┃ ┣ 📜index.js
┃ ┃ ┃ ┗ 📜styles.module.css
┃ ┣ 📂css
┃ ┃ ┗ 📜custom.css
┃ ┗ 📂pages
┃ ┃ ┣ 📜index.js
┃ ┃ ┣ 📜index.module.css
┃ ┃ ┗ 📜markdown-page.md
┣ 📂static
┃ ┣ 📂img
┃ ┃ ┣ 📜docusaurus-social-card.jpg
┃ ┃ ┣ 📜docusaurus.png
┃ ┃ ┣ 📜favicon.ico
┃ ┃ ┣ 📜logo.svg
┃ ┃ ┣ 📜undraw_docusaurus_mountain.svg
┃ ┃ ┣ 📜undraw_docusaurus_react.svg
┃ ┃ ┗ 📜undraw_docusaurus_tree.svg
┃ ┗ 📜.nojekyll
┣ 📜.gitignore
┣ 📜babel.config.js
┣ 📜docusaurus.config.js
┣ 📜package.json
┣ 📜README.md
┗ 📜sidebars.js

Now, let’s explore some of the main directories:

• blog/: This is where you store your blog posts

• docs/: As the name implies, this is where your documentation projects are kept

• src/: This directory allows you to customize your website further using React code.

• static: Here, you store static files like images, logos, favicons, and so on.

A very important file is the docusaurus.config.js file, which acts as the main configuration file for your website.

How to Start Your Docusaurus Website

To run your website locally, first open a new terminal on your IDE and run the following command below to start the development server:

cd my-website

npm i

npx docusaurus start

After running the above command, the browser compiles the React and Markdown files and starts a local development server at http://localhost:3000/. Docusaurus enables hot reload, so you can see changes made to your React, Markdown, and MDX files automatically – without reloading your entire app.

Here is what the site looks like on your browser:

In the image above, you are first welcomed to an intuitive and easily navigable website. At the top left corner of the website, you will see the “Tutorial” and “Blog” sections.

• Tutorial: This is where users can see the live version of your documentation.

• Blog: This is where users can see the live version of your blog.

The link to the Docusaurus Open Source GitHub repo and the icon for toggling your website between light and dark modes are at the top-right corner of the site.

Alternatively, you can use docusaurus.new to test Docusaurus quickly in a playground without having to go through the installation process. Here, you have an option to choose between CodeSandbox and StackBlitz.

How to Create Documentation (Overview)

Let’s take a closer look at our docs folder. If we head back to our local site and click on “Tutorial,” we will see some pre-built doc pages, as shown below:

These documentation pages are reflected in the docs folder located in your IDE. When we open the category.json page, we can adjust the name or position of each page. This means you don’t have to name the folders the same as the page name, since the name of the file will be the URL of the page.

To create our new documentation, let’s use the following steps:

1. Delete all the files in the docs folder. Your browser and terminal will typically display an error after this.

   

   This is because we need at least one page in the docs folder.

2. Create a new file inside the docs folder, which can be named anything you prefer, but in our case, I named it single-page.md. You should see this change immediately reflected when you go to your local website. This is what you will see in the documentation pages section:

   

Inside this newly created file, you can create your documentation seamlessly. The image above shows the little Markdown content I created saying “Single Page” in an H1 and “This is a single page” in plain text.

Let’s say you want to create a more organized content structure, but you don’t know how to get started. Here are a few simple steps on how to do that:

1. Create a new folder inside the docs folder, named “Getting Started”

2. Create new Markdown files inside the “Getting started” folder, and name them whatever you like. For the sake of this tutorial, let’s name it API-docs.md and Session-replay.md.

3. Write your documentation in Markdown

This is how the file structure should look like on your IDE:

📦docs
┣ 📂Getting started
┃ ┣ 📜Open-replay.md
┃ ┗ 📜Session-replay.md
┗ 📜single-page.md

Here is a simple GIF to demonstrate how this works on the local documentation website.

Now, let’s try to create a separate page in the doc folder. To do this, let’s create a category.json page in the Getting started folder. Inside the category.json file, we will include the following JSON text:

{
  "label": "Custom Title",
  "position": 2,
  "link": {
    "type": "generated-index",
    "description": "This is a custom description"
  }
}

• The link object creates a separate page for the folder.

• The type property is set to generated-index, which means it will generate the pages with all the sub-pages.

• The description property is a description of the page that will show up beneath the title.

When you check out your local hosted documentation site, you will see that the label has changed, and a separate page has been created for the folder.

In this section, I will show you an example of how headings and tables of content work in Docusaurus.

The first thing I did was create a markdown.md file. Then I pasted a couple of headings in Markdown text format right inside the file, like this:

---
title: Basic Markdown
sidebar_position: 1
---

# Heading 1

## Heading 2

### Heading 3

#### Heading 4

##### Heading 5

###### Heading 6

When we head back to our website, we can see that only headings level 2 and 3 are automatically added, just as shown below:

We can edit to ensure that all the headings show up. To do this, first create a table-of-contents.md, then paste in the following Markdown:

---
title: Table of Contents
sidebar_position: 2
toc_min_heading_level: 2
toc_max_heading_level: 6
---

import TOCInline from '@theme/TOCInline';

<TOCInline toc={toc} minHeadingLevel={2} maxHeadingLevel={6} />

## Heading 2

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed non risus. Suspendisse lectus tortor, dignissim sit amet, adipiscing nec, ultricies sed, dolor.

### Heading 3

Some content here.

#### Heading 4

Some content here.

##### Heading 5

Some content here.

###### Heading 6

Some content here.

## Heading 2

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed non risus. Suspendisse lectus tortor, dignissim sit amet, adipiscing nec, ultricies sed, dolor.

### Heading 3

Some content here.

#### Heading 4

Some content here.

##### Heading 5

Some content here.

###### Heading 6

Some content here.

## Heading 2

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed non risus. Suspendisse lectus tortor, dignissim sit amet, adipiscing nec, ultricies sed, dolor.

### Heading 3

Some content here.

#### Heading 4

Some content here.

##### Heading 5

Some content here.

###### Heading 6

Some content here.

I added a TOC property and set the minimum and maximum heading levels with toc_min_heading_level: 2 and toc_max_heading_level: 6. We also added an inline table of contents by first importing TOCInline from @theme/TOCInline. Then, we created a TOCInline component (which can be put anywhere you want your TOC to show up).

Now, all the headings show up in the table of contents part of the website:

Beautiful right?

MDX and React Components

Now, let’s talk about one of the most exciting features of Docusaurus: MDX and React components.

You might ask – how can Docusaurus use TOC or import in the Markdown file? Well, that’s because Docusaurus uses MDX, which is basically Markdown with JSX.

To demonstrate this, let’s create a new Markdown file inside our Getting started folder titled MDX.md , then we create a separate file inside the src > components folder and name the file Tag.js . Then we paste in the following code:

import React from 'react';

export default function Tag({ children, color }) {
  return (
    <span
      style={{
        backgroundColor: color,
        borderRadius: '4px',
        color: '#fff',
        padding: '0.2rem 0.5rem',
        fontWeight: 'bold',
      }}
    >
      {children}
    </span>
  );
}

Here, we first imported the core React library, and then we defined a functional component called Tag, which takes in two props as input: children and color. In our return statement, we included our CSS styles for the span element.

Inside the MDX.md file, paste in the below code:

---
title: MDX
sidebar_position: 3
---

import Tag from '@site/src/components/Tag';

<Tag color="#FF5733">Important</Tag> information: This is an <Tag color="#3399FF">Exciting</Tag> example of custom components!

I can write **Markdown** alongside my _JSX_!

Here, we import Tag from our components folder. This is what it looks like:

Note: Because we use MDX, Docusaurus comes with pre-built components like Tabs, alerts, code blocks, and more. Let’s check them out in the following subsections.

Tabs

In this subsection, we’ll talk about tabs as a pre-built component in Docusaurus. Let’s dive right in!

For a start, let’s create a new Markdown file called tabs.md and paste in the following code:

---
title: Tabs in Markdown
sidebar_position: 4
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="book" label="Book" default>
    Dive into the world of knowledge with a captivating book 📚
  </TabItem>
  <TabItem value="painting" label="Painting">
    Admire the strokes of artistry on a beautiful painting 🖼️
  </TabItem>
  <TabItem value="music" label="Music">
    Let the soothing melodies of music transport you 🎶
  </TabItem>
</Tabs>

I'm a text that doesn't belong to any tab. So I'm always visible.

We imported Tabs from @theme/Tabs and TabItem from @theme/TabItem. Then, we created a Tabs component, which is the container, and the TabItem component is the tab itself. The value property is the value of the tab, while the label property is the label of the tab. The default property defines which tab is open by default – in this case, the “Book” tab.

This is how it looks:

Each tab is clickable and transitions smoothly.

Alerts or Admonitions

Docusaurus comes with pre-built alerts or admonitions. To create an alert, you simply wrap the text with three colons and follow it with the type of alert you want the reader to have in mind.

Let’s create a new Markdown file called alerts.md and paste in the following Markdown:

---
title: Alerts or Admonitions
sidebar_position: 5
---

:::note

Here's some **information** with _Markdown_ styling.

:::

:::tip

Here's a **helpful tip** with _formatted text_.

:::

:::info

Here's some **useful info** presented in a clear way.

:::

:::caution

Please take **extra caution** with this important note.

:::

:::danger

This is a **dangerous situation** you need to be aware of.

:::

:::note This is a _custom title_

And you can add images as well.

![alt text](https://picsum.photos/600/400)

:::

The various types of alerts, as shown in the Markdown above, are:

• note

• tip

• info

• caution

• danger

Here’s what it looks like on the website:

Alerts and admonitions are pretty common in documentation sites. So, if you have ever wondered how it’s been done, well, this is it! It’s quite straightforward.

Code blocks

As we already know by now, Docusaurus supports MDX, which allows us to include code blocks in our files. Code blocks are text blocks wrapped around by strings of three backticks. You can add the name of the language after the last of the three backticks.

Let’s create a codeblocks.md file and paste the following JSX code:

---
title: Codeblocks
sidebar_position: 6
---

```jsx title="Codeblock"
function Greeting(props) {
  return <p>Welcome, {props.userName}!</p>;
}

export default Greeting;
```

```jsx title="Highlight Lines"
function HighlightText(highlight) {
  if (highlight) {
    // highlight-next-line
    return 'This text is highlighted!';
  }
  return 'Nothing highlighted';
}

function HighlightMoreText(highlight) {
  // highlight-start
  if (highlight) {
    return 'This range is highlighted!';
  }
  // highlight-end
  return 'Nothing highlighted';
}
```

```jsx title="Line Numbers" showLineNumbers
import React from 'react';

function UserProfile(props) {
  const { username, email, isAdmin } = props;

  return (
    <div>
      <h1>User Profile</h1>
      <p>Username: {username}</p>
      <p>Email: {email}</p>
      {isAdmin && <p>Admin User</p>}
    </div>
  );
}

export default UserProfile;
```

```jsx title="Line Numbers with Highlight" {4,9-11} showLineNumbers
import React from 'react';

function UserProfile(props) {
  const { username, email, isAdmin } = props;

  return (
    <div>
      <h1>User Profile</h1>
      <p>Username: {username}</p>
      <p>Email: {email}</p>
      {isAdmin && <p>Admin User</p>}
    </div>
  );
}

export default UserProfile;

This is what the code blocks look like:

You can easily copy the code by hovering your cursor over the code blocks and clicking on the copy icon on the top-right side of the code block.

Note: By default, Docusaurus uses Prism for syntax highlighting.

If you also want to highlight some lines of code, you can do that by adding a comment like this:

    // highlight-next-line
    return 'This text is highlighted!';
  }
  return 'Nothing highlighted';
}

function HighlightMoreText(highlight) {
  // highlight-start
  if (highlight) {
    return 'This range is highlighted!';
  }
  // highlight-end

• highlight-next-line: allows you to highlight a single line of code

• highlight-start and highlight-end: allows you to highlight a range of lines

Docusaurus Blog

The Docusaurus blog also comes by default with the classic template. If you don’t have a blog, you can add the following lines to your docusaurus.config.js file:

{
  label: 'Blog',
  to: '/blog',
}

Usually, this line should already be in your config file after installing Docusaurus for the first time.

The Docusaurus blog is very simple to understand. Navigate to the blog folder in the project explorer, and you’ll see all the blog posts, which are MDX files. The blog post date should be included on the file name as shown below:

When you open one of the blog posts, you see something like this:

---
slug: long-blog-post
title: Long Blog Post
authors: yangshun
tags: [hello, docusaurus]
---

This is the summary of a very long blog post,

Use a `<!--` `truncate` `-->` comment to limit blog post size in the list view.

<!-- truncate -->

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

• slug: You can add a slug to the URL of the blog post

• title: Title of the blog post

• authors: The authors of the blog post

• tags: Tags related to the blog post

In the blog post, we can also use all the Markdown features plus JSX as we have seen before.

Custom Pages

Technically, Docusaurus isn’t just a fancy documentation site generator with a blog. It’s a standard static site generator – which means you can create any page you want.

To see how creating a custom page in Docusaurus works, let’s create an about.js file in the src > pages folder and include the following code:

import React from 'react';
import Layout from '@theme/Layout';
import Head from '@docusaurus/Head';

export default function About() {
  return (
    <Layout>
      <Head>
        <title>About</title>
        <meta name="description" content="This is the about page" />
      </Head>

      <div>
        <h1 className="red-text">About</h1>
        <p>This is the about page.</p>
      </div>
    </Layout>
  );
}

When you go to http://localhost:3000/about, you should see something like this:

We can also add the page to the navbar by going to the docusaurus.config.js file and adding a new item to the navbar array. The item looks like this:

{to: 'about', label: 'About', position: 'left'},

It then appears on the homepage nav menu like this:

You can now style and customize the about.js file any way you’d prefer using React.

Styling in Docusaurus

Let’s look at how you can style your site in Docusaurus. The easiest way is to customize the custom.css file inside the css > custom.css file. This is what the file looks like:

Here, you can change the whole color schema of the site and different styling to this file.

You can read more about this in the Docusaurus styling and layout docs.

SEO in Docusaurus

Docusaurus takes SEO very seriously. By default, Docusaurus automatically adds a description title, canonical URL links, and other useful metadata to each page. This can be configured as shown below:

---
title: Our First Page
sidebar_position: 1

description: A short description of this page
image: ../static/img/docusaurus-social-card.jpg
keywords: [keywords, describing, the main topics]
---

# Single Page

This is a single page.

You can read more about this in the Docusaurus SEO docs.

Deployment

Deployment is pretty easy with Docusaurus. Since it’s a static site, you can deploy it to any static site hosting service. To do this, run the npm run build command on your CLI. This creates a build folder like the one below:

Then, you can upload the contents of the build folder to your hosting service.

Conclusion

In this article, we covered how to build documentation from scratch, how to create, customize, and style pages, and the awesome SEO power of Docusaurus.

Docusaurus is friendly to both developers and technical writers. As a developer, you can focus on customizing the site, while as a technical writer, you can focus on writing the documentation.

I will highly recommend this tool for both startups and established enterprises looking to build stunning documentation sites.

This guide is not exhaustive, but covers everything you need to know about the basics of building a documentation site with React and Docusaurus.

I hope you found it helpful :)

Here’s the link to my GitHub code for follow-up purposes.

And here’s the main Docusaurus documentation if you’d like to dive in deeper.