Front-End Web & Mobile

Unlocking deeper insights with enhanced monitoring in AWS AppSync

Sagar Suri — Thu, 09 Oct 2025 11:55:13 +0000

In today’s digital landscape, how well your APIs work is important for a good user experience. Monitoring your APIs isn’t just smart—it’s needed to keep your apps running well.

AWS AppSync, a managed GraphQL service, is a popular choice for developers building scalable, real-time applications. With the introduction of Enhanced Monitoring, AppSync now provides deeper insights and more detailed metrics. In this blog post, we’ll show how this feature can help you monitor and optimise your APIs more effectively. We’ll also compare it to current monitoring tools, guide you through a sample API implementation, and break down the associated costs.

AWS AppSync overview

AWS AppSync simplifies the process of building and deploying secure, high-performance APIs. It’s a managed service for GraphQL and Pub/Sub APIs that abstracts away the complexities of infrastructure, allowing you to focus on what matters—building innovative applications.

With AppSync, you can create a unified data graph that brings together data from multiple sources. Whether you’re synchronizing real-time data, enabling offline access, or managing conflict resolution, AppSync provides the tools to make it happen. Its built-in security features and serverless architecture mean you can deploy APIs that are both robust and secure, without worrying about the underlying infrastructure.

The importance of monitoring in API management

Monitoring is a critical aspect of API management. It ensures that APIs are performing optimally, meeting service level objectives, and maintaining security standards. By regularly keeping a close eye on key metrics, you ensure that your APIs meet your service-level objectives (SLOs) and comply with security standards, ensuring a smooth and reliable experience. When you monitor metrics like latency, error rates, and request counts, you can detect anomalies early, troubleshoot root causes, and prevent small issues from escalating into user-facing problems. This approach of using telemetry from metrics to take proactive action aligns with best practices like OPS09-BP03 and is essential for the long-term reliability and scalability of your APIs.

Understanding existing monitoring in AWS AppSync

Basic monitoring with AWS CloudWatch

AWS AppSync integrates with Amazon CloudWatch, providing essential metrics that offer a high-level overview of your API’s performance. These include request latency, counts and error rates and more.

AppSync’s real-time subscriptions are a powerful feature, enabling push notifications and live updates. To monitor these, Amazon CloudWatch offers metrics such as the number of active real-time subscriptions, number of messages sent via subscription and more.

Check the full list of built-in metrics to identify overall trends and spikes at a glance.

Introducing enhanced monitoring in AWS AppSync

As applications become more complex and user demands grow, there is a growing need for more granular insights. Developers increasingly require additional metrics to pinpoint the precise stages of request processing that might contribute to latency or errors.

For instance, understanding the performance at the resolver level or tracking how individual data sources perform under load can be critical for fine-tuning and optimizing API operations. These detailed metrics empower developers to not only detect issues but also to understand the root causes, enabling more targeted and effective optimizations.

On February 12, 2024, AWS announced Enhanced Monitoring for AWS AppSync, Enhanced Monitoring in AWS AppSync gives developers access to a more detailed view of their API’s performance. This feature provides real-time insights and granular metrics, allowing you to drill down into specific operations, resolvers, and data sources.

Key features of enhanced monitoring

Resolver-Level Metrics: Track the performance of individual resolvers to pinpoint latency and errors. This allows for targeted optimizations, ensuring your API performs efficiently at every stage.
Data Source Monitoring: Gain detailed insights into how your data sources—whether Amazon DynamoDB, Amazon RDS, or AWS Lambda—are performing. Identifying performance bottlenecks at the source level becomes easier, allowing you to take corrective action quickly.
Operational metrics: Get detailed metrics on GraphQL operation-level (Mutations & Queries) metrics.

In total, 10 new CloudWatch metrics were added under the “Enhanced metrics” section of the official documentation.

Sample API implementation with enhanced monitoring

To demonstrate the power of Enhanced Monitoring, let’s walk through a sample AWS AppSync API implementation. This API will include three queries and two mutations, connected to four different data sources: Amazon DynamoDB, AWS Lambda, and Amazon OpenSearch Service.

We will create an API that supports the following operations:

Queries:

getUser: Retrieve user details by ID.
listUsers: List all users.
searchUsers: Search users by a specific attribute.

Mutations:

createUser: Add a new user.
updateUser: Update existing user details.

Data Sources:

DynamoDB: To store user data.
AWS Lambda: For complex business logic processing (used for createUser and updateUser mutations).
Amazon OpenSearch Service: To enable search functionality.

Step-by-step setup

Prerequisites:

An active AWS account: If you don’t have one, you can create an AWS account to get started.
Valid AWS credentials: You need an IAM user with permissions to manage AWS AppSync APIs (create, update, delete, view) and to view related CloudWatch metrics and alarms. This can be granted by attaching the AWS managed policies AWSAppSyncAdministrator and CloudWatchReadOnlyAccess, or equivalent custom permissions. You will use these credentials to sign in to AWS Management Console.

Here’s how you can enable enhanced monitoring in AWS AppSync using different methods:

Method 1: Enabling enhanced monitoring via the AWS Management Console:

Navigate to the AppSync Console:
1. Sign in to the AWS Management Console.
2. Navigate to the AppSync service by searching for “AppSync” in the AWS services search bar.
Select Your GraphQL API:
1. In the AppSync console, click on the API for which you want to enable enhanced monitoring.
Go to the Settings:
1. Select “Settings” from the left-hand menu.
Enable Enhanced Monitoring:

Figure 1: AWS AppSync Console ‘Settings’ tab showing the toggles for Enhanced Monitoring
1. In the API Configuration section, you’ll see an option to enable Enhanced Monitoring.
2. Here you can either enable metrics for all resolvers and data sources or can choose to manually select them by choosing “PER_RESOLVER_METRICS” and “PER_DATA_SOURCE_METRICS”, respectively, as stated in the documentation.
3. For per-resolver and per-data source metrics, metrics need to be enabled individually on each resolver and data source.

Method 2: Enabling enhanced monitoring via the AWS CLI

aws appsync update-graphql-api \--api-id <API_ID> \--name "<API_NAME>" \--authentication-type API_KEY \--enhanced-metrics-config resolverLevelMetricsBehavior=FULL_REQUEST_RESOLVER_METRICS,dataSourceLevelMetricsBehavior=FULL_REQUEST_DATA_SOURCE_METRICS,operationLevelMetricsConfig=ENABLE

Method 3: Enabling enhanced monitoring via Terraform

Following the AWS Provider documentation, adding the block enhanced_metrics_configto an existing resource will enable enhanced monitoring, eg:

resource "aws_appsync_graphql_api" "api" {
  authentication_type = "API_KEY"
  name                = "<API_NAME>"
  enhanced_metrics_config {
    resolver_level_metrics_behavior     = "FULL_REQUEST_RESOLVER_METRICS"
    data_source_level_metrics_behavior  = "FULL_REQUEST_DATA_SOURCE_METRICS"
    operation_level_metrics_config      = "ENABLED"
  }
}

Metrics dashboard

With Enhanced Monitoring enabled, you can now observe detailed metrics in the Amazon CloudWatch dashboard. For example, if the SearchUsers query is experiencing high latency, you can quickly identify whether the issue lies with the Amazon OpenSearch Service data source or the Lambda resolver. The Amazon CloudWatch dashboard will display metrics such as resolver execution time and data source response time, allowing you to pinpoint the exact cause of any performance issues.

Additional API metrics in Amazon CloudWatch metrics

Useful dimensions and metrics include:

DataSource, GraphQLAPIId
API Metrics by Operation
GraphQLAPIId, Resolver

Figure 2: A screenshot of AWS AppSync API Metrics in Amazon CloudWatch

API Metrics per resolver

Figure 3: AWS AppSync API Metrics by Resolver

API Metrics per DataSource

Figure 4: AWS AppSync API Metrics by Datasource

API Metrics per Operation

Figure 5: AWS AppSync API Metrics by Operation

API metrics custom dashboard with enhanced metrics

With AWS AppSync’s enhanced monitoring metrics, you can create a custom CloudWatch dashboard to get a real-time view of your API’s performance and display key KPIs like resolver latency, error rates, throttling, and data source performance. This helps quickly identify bottlenecks, track usage patterns, and optimise API efficiency.

For example, you can set up widgets on your Amazon CloudWatch dashboard to monitor:

Resolver Request Count: This will provide insights into usage patterns, guiding the team to optimise the most frequently used data sources and resolvers.
Resolver Latency: Track the time taken by each resolver to process requests, helping you pinpoint areas that may require optimisation.
Data Source Performance: Visualise the interaction between your API and its data sources, such as DynamoDB or Lambda, to ensure they are performing within acceptable thresholds.
Error Rates: Display the number of errors encountered by each resolver or data source, enabling you to identify and address issues before they impact users.

By aggregating these metrics into a single dashboard, you gain a holistic view of your API’s health, enabling proactive management and optimisation to deliver a seamless user experience.

Figure 6: Custom Amazon CloudWatch dashboard to show API Metrics

Actionable insights from API monitoring

Using the insights from an API metrics dashboard with enhanced metrics like those provided by AWS AppSync, you can take several actions to improve your API’s performance and reliability. Here are some specific actions you can take based on the metrics you monitor:

High resolver request count

Enable AppSync Caching: Use AppSync’s built-in caching to store results of frequently requested resolvers, reducing load on data sources. Set an appropriate TTL (Time to Live) for optimal balance between freshness and performance.
Smaller Functional Units: Break down complex resolvers into smaller units. This improves visibility and makes it easier to identify and optimse specific tasks within your API.

High resolver latency

Implement AppSync Caching: Cache responses for expensive queries to reduce latency for repeated requests.
Optimise Resolvers: Refactor resolver logic to minimise processing time, such as reducing unnecessary computations or data transformations.
Optimise Data Fetching: Ensure efficient database queries. Use indexes in DynamoDB and optimise SQL queries with proper indexing.
Batch Operations: Use batch operations to minimise the number of data source calls. For example, use DynamoDB’s BatchGetItem for fetching multiple items in one request.

Poor data source performance

Optimise AWS Lambda Functions: Increase memory allocation or refactor code for more efficient execution. Use Lambda’s metrics to identify performance issues.
Use DynamoDB Accelerator (DAX): Integrate DAX to reduce read latency for high-traffic DynamoDB data sources by caching responses in-memory.
RDS Optimisation: Utilise RDS read replicas for distributing read load and optimise queries with proper indexing.

Increased error rates

Investigate and Resolve Issues: Use CloudWatch and AppSync logs to pinpoint and fix resolver or data source errors.
Implement Retry Mechanisms: Use retry logic for transient errors or AWS SDK’s automatic retries to handle network interruptions.
Improve Input Validation: Add validation to catch invalid or malformed requests early, preventing errors and providing informative messages to clients.

Frequent throttling occurrences

Increase Throttling Limits: Adjust throttling limits in AppSync (using AWS WAF) or data sources like DynamoDB for legitimate high traffic.
Optimise API Usage: Guide clients to reduce redundant requests and use efficient query structures.
Implement Rate Limiting and Backoff: Apply rate limiting and exponential backoff on the client side to manage request rates and prevent hitting throttling limits.

Cost considerations

Enhanced Monitoring emits additional metrics that incur charges in Amazon CloudWatch. Here’s a breakdown based on the sample API:

Calculating costs — Example estimation using the sample API

Example calculation:

Total no. of new metrics = 5 (3 queries + 2 mutations) * 5 (additional enhanced metrics) + 4 (No. of Data sources) * 3 (additional enhanced metrics) = 37

Monthly Amazon CloudWatch Metrics Charges @ $0.30 per custom metric = 37 * $0.30 = $11.10

Note: Once you exceed 10,000 total metrics then volume pricing tiers will apply – To see the detailed pricing table, click the Metrics tab on the Amazon CloudWatch pricing page.

Reviewing costs

Using AWS Data Exports you can get an approximate cost breakdown of an existing AWS AppSync API by following these steps:

Enable the enhanced monitoring temporarily on an AppSync API as seen above.
Execute queries or mutations against the AppSync API.
Setup Cost Data Export
Use Amazon Athena to process Data Exports using the Crawlers.
Run the Crawler (see Crawler docs), and wait until it completes its run.
Replace with the Crawler’s target table.
Replace placeholders in the query below:
1. <glue table>: Crawler’s target Glue table
2. <account>: AWS account where AppSync is set up
3. <region>: Region where AppSync is set up
Query Athena with the SQL query below by adjusting line_item_usage_start_date, line_item_usage_end_date to compare the following datasets:
1. During a timeframe when enhanced metrics were not yet used.
2. During a timeframe when enhanced metrics were already active.

Sample Athena SQL (adjust placeholders):

SELECT
line_item_operation,
SUM(CAST(line_item_unblended_cost AS decimal(16,8))) AS TotalSpend
FROM ''
WHERE
product_product_name = 'AmazonCloudWatch'
AND line_item_usage_account_id = ''
AND product_region = ''
AND line_item_operation in ('MetricStorage:AWS/AppSync', 'GetMetricData', 'ListMetrics', 'GetMetricStatistics', 'PutMetricData')
AND line_item_line_item_type NOT IN ('Tax','Credit','Refund','EdpDiscount','Fee','RIFee')
AND line_item_usage_start_date > DATE('2024-07-20')
AND line_item_usage_end_date < DATE('2024-07-30')
GROUP BY line_item_operation
ORDER BY TotalSpend DESC;

Example output:

# line_item_operation TotalSpend
1 GetMetricData 59.11682000
2 MetricStorage:AWS/AppSync 0.56626344
3 PutMetricData 0.42279000
4 ListMetrics 0.00248000
5 GetMetricStatistics 0.00028000

You can extract other details out of the data export by reviewing the Line item details and Usage types.

Metrics retention

CloudWatch retains metrics data as follows:

Data points with a period of less than 60 seconds are available for 3 hours. These data points are high-resolution custom metrics.

Data points with a period of 60 seconds (1 minute) are available for 15 days
Data points with a period of 300 seconds (5 minutes) are available for 63 days
Data points with a period of 3600 seconds (1 hour) are available for 455 days (15 months)

Data points that are initially published with a shorter period are aggregated together for long-term storage. For example, if you collect data using a period of 1 minute, the data remains available for 15 days with 1-minute resolution. After 15 days this data is still available, but is aggregated and is retrievable only with a resolution of 5 minutes. After 63 days, the data is further aggregated and is available with a resolution of 1 hour.

Conclusion

AWS AppSync’s Enhanced Monitoring is a powerful tool that provides deeper insights into your API’s performance, delivering granular visibility to accelerate issue detection and remediation and reduce mean time to resolution. While there is an associated cost, the value it brings in terms of operational efficiency and improved user experience is substantial. By leveraging Enhanced Monitoring, you can ensure that your AWS AppSync APIs are optimised, reliable, and scalable.

Monitoring provides valuable data that empowers you to make informed decisions and drive your business forward. Ready to take your API performance to the next level? Activate Enhanced Monitoring in AWS AppSync for the detailed insights you need to keep your APIs running smoothly.

Offline caching with AWS Amplify, Tanstack, AppSync and MongoDB Atlas

Dan Kiuna — Thu, 19 Jun 2025 20:59:54 +0000

In this blog we demonstrate how to create an offline-first application with optimistic UI using AWS Amplify, AWS AppSync, and MongoDB Atlas. Developers design offline first applications to work without requiring an active internet connection. Optimistic UI then builds on top of the offline first approach by updating the UI with expected data changes, without depending on a response from the server. This approach typically utilizes a local cache strategy.

Applications that use offline first with optimistic UI provide a number of improvements for users. These include reducing the need to implement loading screens, better performance due to faster data access, reliability of data when an application is offline, and cost efficiency. While implementing offline capabilities manually can take sizable effort, you can use tools that simplify the process.

We provide a sample to-do application that renders results of MongoDB Atlas CRUD operations immediately on the UI before the request roundtrip has completed, improving the user experience. In other words, we implement optimistic UI that makes it easy to render loading and error states, while allowing developers to rollback changes on the UI when API calls are unsuccessful. The implementation leverages TanStack Query to handle the optimistic UI updates along with AWS Amplify. The diagram in Figure 1 illustrates the interaction between the UI and the backend.

TanStack Query is an asynchronous state management library for TypeScript/JavaScript, React, Solid, Vue, Svelte, and Angular. It simplifies fetching, caching, synchronizing, and updating server state in web applications. By leveraging TanStack Query’s caching mechanisms, the app ensures data availability even without an active network connection. AWS Amplify streamlines the development process, while AWS AppSync provides a robust GraphQL API layer, and MongoDB Atlas offers a scalable database solution. This integration showcases how TanStack Query’s offline caching can be effectively utilized within a full-stack application architecture.

Figure 1. Interaction Diagram

The sample application implements a classic to-do functionality and the exact app architecture is shown in Figure 2. The stack consists of:

MongoDB Atlas for database services.
AWS Amplify the full-stack application framework.
AWS AppSync for GraphQL API management.
AWS Lambda Resolver for serverless computing.
Amazon Cognito for user management and authentication.

Figure 2. Architecture

Deploy the Application

To deploy the app in your AWS account, follow the steps below. Once deployed you can create a user, authenticate yourself, and create to-do entries – see Figure 8.

Set up the MongoDB Atlas cluster

Follow the link to the setup the MongoDB Atlas cluster, Database , User and Network access
Set up the user
1. Configure User

Clone the GitHub Repository

Clone the sample application with the following command

git clone https://github.com/mongodb-partners/amplify-mongodb-tanstack-offline

Setup the AWS CLI credentials (optional if you need to debug your application locally)

If you would like to test the application locally using a sandbox environment, you can setup temporary AWS credentials locally:

export AWS_ACCESS_KEY_ID=
export AWS_SECRET_ACCESS_KEY=
export AWS_SESSION_TOKEN=

Deploy the Todo Application in AWS Amplify

Open the AWS Amplify console and Select the Github Option

Figure 3. Select Github option

2. Configure the GitHub Repository

Figure 4. Configure repository permissions

3. Select the GitHub Repository and click Next

Figure 5. Select repository and branch

4. Set all other options to default and deploy

Figure 6. Deploy application

Configure the Environment Variables

Configure the Environment variables after the successful deployment

Figure 7. Configure environment variables

Open the application and test

Open the application through the URL provided and test the application.

Figure 8. Sample todo entries

MongoDB Atlas Output

Figure 9. Data in Mongo

Review the Application

Now that the application is deployed, let’s discuss what happens under the hood and what was configured for us. We utilized Amplify’s git-based workflow to host our full-stack, serverless web application with continuous deployment. Amplify supports various frameworks, including server side rendered (SSR) frameworks like Next.js and Nuxt, single page application (SPA) frameworks like React and Angular, and static site generators (SSG) like Gatsby and Hugo. In this case, we deployed a SPA React based application. We can include feature branches, custom domains, pull request previews, end-to-end testing, and redirects/rewrites. Amplify Hosting provides a Git-based workflow enables atomic deployments ensuring that updates are only applied after the entire deployment is complete.

To deploy our application we used AWS Amplify Gen 2, which is a tool designed to simplify the development and deployment of full-stack applications using TypeScript. It leverages the AWS Cloud Development Kit (CDK) to manage cloud resources, ensuring scalability and ease of use.

Before we conclude, it is important to understand our application’s updates concurrency. We implemented a simple optimistic first-come first-served conflict resolution mechanism. The MongoDB Atlas cluster persists updates in the order it receives them. In case of conflicting updates, the latest arriving update will override previous updates. This mechanism works well in applications where update conflicts are rare. It is important to evaluate how this may or may not suit your production needs, requiring more sophisticated approaches. TanStack provides capabilities for more complex mechanisms to handle various connectivity scenarios. By default, TanStack Query provides an “online” network mode, where Queries and Mutations will not be triggered unless you have network connection. If a query runs because you are online, but you go offline while the fetch is still happening, TanStack Query will also pause the retry mechanism. Paused queries will then continue to run once you re-gain network connection. In order to optimistically update the UI with new or changed values, we can also update the local cache with what we expect the response to be. This is approach works well together with TanStack’s “online” network mode, where if the application has no network connectivity, the mutations will not fire, but will be added to the queue, but our local cache can be used to update the UI. Below is a key example of how our sample application optimistically updates the UI with the expected mutation.

const createMutation = useMutation({
    mutationFn: async (input: { content: string }) => {
    // Use the Amplify client to make the request to AppSync
      const { data } = await amplifyClient.mutations.addTodo(input);
      return data;
    },
    // When mutate is called:
    onMutate: async (newTodo) => {
      // Cancel any outgoing refetches
      // so they don't overwrite our optimistic update
      await tanstackClient.cancelQueries({ queryKey: ["listTodo"] });

      // Snapshot the previous value
      const previousTodoList = tanstackClient.getQueryData(["listTodo"]);

      // Optimistically update to the new value
      if (previousTodoList) {
        tanstackClient.setQueryData(["listTodo"], (old: Todo[]) => [
          ...old,
          newTodo,
        ]);
      }

      // Return a context object with the snapshotted value
      return { previousTodoList };
    },
    // If the mutation fails,
    // use the context returned from onMutate to rollback
    onError: (err, newTodo, context) => {
      console.error("Error saving record:", err, newTodo);
      if (context?.previousTodoList) {
        tanstackClient.setQueryData(["listTodo"], context.previousTodoList);
      }
    },
    // Always refetch after error or success:
    onSettled: () => {
      tanstackClient.invalidateQueries({ queryKey: ["listTodo"] });
    },
    onSuccess: () => {
      tanstackClient.invalidateQueries({ queryKey: ["listTodo"] });
    },
  });

We welcome any PRs implementing additional conflict resolution strategies.

Try out MongoDB Atlas on AWS MarketPlace
Get familiar with AWS Amplify, Amplify Gen2 and AppSync
For detailed instructions on deploying the application, refer to the deployment section of our documentation
Submit a PR with your enhancements

Introducing Upgraded Build Instances on Amplify Hosting

Matt Auerbach — Thu, 29 May 2025 18:14:26 +0000

AWS Amplify Hosting has built web applications using a fixed instance environment. As applications grow more complex and require intensive build processes for dependency management, asset optimization, and comprehensive testing, developers need more powerful build environments to maintain productivity and deployment speed.

Today, we’re excited to introduce customizable build instances for Amplify Hosting. This update adds two new instance sizes: Large and XLarge, both offering increased memory and CPU resources. Development teams can now scale their build resources to match their specific needs. This is especially useful when handling large dependency trees, processing numerous static assets, or running memory-intensive operations like TypeScript compilation and parallel testing frameworks.

Challenges with Fixed Size Build Instance

Customers building large applications and running heavier workloads experience increased build times, slow CI/CD and build failures due to memory errors. As development teams adopt Amplify Hosting, they expect scalable build environments that can match a variety of workloads. While build time optimizations exist, applications cannot grow within a fixed instance size container configuration of 8GiB memory and 4 vCPUs. Virtual memory (swap space) introduces significant performance penalties compared to physical memory, and no effective alternatives exist for expanding compute capacity or storage within a fixed environment. These hardware limitations create fundamental barriers that software optimizations alone cannot overcome.

Build Instance Specifications

Build Instance	vCPUs	Memory	Disk space
Standard	4	8 GiB	128 GB
Large	8	16 GiB	128 GB
XLarge	36	72 GiB	256 GB

Introducing Customizable Build Instances

Amplify Hosting’s new customizable build instances allow developers to select the computing resources that best match their application needs. This allows achieving predictable build performance by eliminating resource constrains. In addition to our Standard build instance, we are introducing Large and XLarge instances. The following table summarizes the specifications of all of Amplify Hosting’s build instance offerings:

You can configure build instances at the application level either during the app creation or later udpating your existing applications. Updated configuration will extend to all of your app’s branches and change an app’s build instance size across builds. Any build running for the app, irrespective of the branch, will use the build instance size that you configured at the app level when you triggered the build. You can configure build instance size when creating a new app or updating an existing app.

To customize build instance size for a new app via Amplify console: During the App Settings step, scroll down and click on Advanced settings. From the drop down list, select the Build Instance type you would like to configure for your app.

Figure 1 – Configure build instance size for a new app

To customize build instance size for an existing app via Amplify console: Navigate to your app, open the Hosting tab, and select Build Settings. Scroll down to Advanced settings and click Edit. From the drop down, select the Build Instance type you would like to update your app with.

Figure 2 – Modify build instance for an existing app

Note: Build instance allocation process can require additional provisioning time before your build starts. For larger instances, especially XLarge, your build might experience latency before the build starts, due to this overhead time. However, you are billed only for the actual build time, not the overhead time.

Performance Testing Explanation

Now we will demonstrate the value of more powerful instances by using a Next.js application that generates more than 100 static pages. We will walk you through the deployment of this app on Amplify Hosting, show you how to debug memory-related build failures, and teach you how to upgrade the build instance to meet your application’s memory needs.

Deploying an application to Amplify HostingWe will first deploy the static app using the default settings:

Figure 3 – Review and create an app page

Once the deployment starts, Amplify Hosting provision the resources and carry the deployment further:

Figure 4 – Deployment in progress

Configuring app to use large memory

After deployment starts, our app will fail its first build due to JavaScript heap out of memory issue. The runtime environment requests the heap memory, and the host operating system should allocate it. The JavaScript Node.js V8 runtime environment enforces a default heap size limit, which depends on several factors including the host memory size. That is why Standard and Large build instances use a default Node.js heap size of 2096 MB, while the XLarge instance uses a default heap size of 4144 MB.

Figure 5 – Deployment 1 failed due to heap size memory limit

We can solve the conservative Node.js default heap memory limit issue by increasing the heap size. Since the app is using Standard build instance with 8 GiB memory, we will need to increase the heap size to 7000 MB which is ~7 GB. This leaves approximately 1 GB memory for operating system to use for other processes and avoids unintended behavior.

Next, we will modify the build specification with the following command to increase Node.js heap memory limit.

export NODE_OPTIONS='--max-old-space-size=7000'

Alternately, NODE_OPTIONS can also be set as an environment variable in our app. Refer documentation for more details.

We will also update the build spec file as following to accommodate these changes in our build flow:

version: 1
frontend:
  phases:
    preBuild:
      commands:
        # Set the heap size to 7000 MB
        - export NODE_OPTIONS='--max-old-space-size=7000'
        # To check the heap size memory limit in MB
        - node -e "console.log('Total available heap size (MB):', v8.getHeapStatistics().heap_size_limit / 1024 / 1024)"
        - npm ci --cache .npm --prefer-offline
    build:
      commands:
        - npm run build
  artifacts:
    baseDirectory: .next
    files:
      - '**/*'
  cache:
    paths:
      - .next/cache/**/*
      - .npm/**/*

We will trigger a new deployment with the modified heap size by going to the Deployments page and clicking on Redeploy this version button

However, the app still fails to build. This time, we see a log stating “Total available heap size (MB): 7048” that confirms our increased heap size. Interestingly, we also see a SIGKILL directive that indicates the operating system forcefully terminated the build process. This indicates another out of memory error.

Figure 6 – Deployment 2 failed due to out of memory

Upgrading build instance

Standard instance has a memory limit of 8 GiB and despite increasing the heap size close to this limit. Because of that, we are still running out of memory. We can solve this issue by upgrading our build instance to Large. This way we will allocate more memory to our build process.

We will update the build spec file as following to deploy on Large instance:

version: 1
frontend:
  phases:
    preBuild:
      commands:
        # Set the heap size to 14000 MB
        - export NODE_OPTIONS='--max-old-space-size=14000'
        # To check the heap size memory limit in MB
        - node -e "console.log('Total available heap size (MB):', v8.getHeapStatistics().heap_size_limit / 1024 / 1024)"
        - npm ci --cache .npm --prefer-offline
    build:
      commands:
        - npm run build
  artifacts:
    baseDirectory: .next
    files:
      - '**/*'
  cache:
    paths:
      - .next/cache/**/*
      - .npm/**/*

We will update the build instance by opening the Hosting tab, and selecting Build settings. Afterwards, scroll down to Advanced settings and clicking on Edit. From the drop down, select the Build instance type as Large.

Figure 7 – Update build instance size to Large

Next, on the Deployments page, we will click on Redeploy this version to create a new deployment with Large instance. We also notice the first log line in build logs showing the build instance specifications.

Figure 8 – Deployment 3 in progress on Large build instance

We can see that our app is deployed successfully.

Figure 10 – App is deployed

Conclusion

In this blog, we have explored how you can create and update app workflows for configuring build instance sizes and demonstrated how you can solve memory issues in your projects hosted by Amplify Hosting. To explore further about build instance sizes and learn more about this feature, check out the Amplify Hosting documentation. For information on pricing for build instances, you can check our pricing page.

About the Authors

Sohaib Uddin Syed, Software Engineer, Amplify Hosting

Sohaib Uddin Syed is a Software Development Engineer at AWS Amplify Hosting. Sohaib builds software that enables customers to build their front-end web applications using the scalability of AWS. In his free time, Sohaib enjoys watching football (soccer), cooking and spending time with family and friends.

Angela Zheng, Software Engineer, Amplify Hosting

Angela Zheng is a Software Development Engineer at AWS Amplify Hosting. She works on creating features that make hosting front-end web applications accessible and straightforward for developers at any scale. In her free time, she enjoys dancing, playing a game of volleyball, experimenting with recipes in the kitchen, and traveling.

Matt Auerbach, Sr Product Manager, Amplify Hosting

Matt Auerbach is a NYC-based Product Manager on the AWS Amplify Team. He educates developers regarding products and offerings, and acts as the primary point of contact for assistance and feedback. Matt is a mild-mannered programmer who enjoys using technology to solve problems and making people’s lives easier. B night, however…well he does pretty much the same thing. You can find Matt on X @mauerbac. He previously worked at Twitch, Optimizely & Twilio.

Simplify AWS AppSync Events integration with Powertools for AWS Lambda

Ana Falcao — Wed, 14 May 2025 12:27:22 +0000

Real-time capabilities have become essential in modern applications, where users expect immediate updates and interactive experiences. Whether you’re building chat applications, live dashboards, gaming leaderboards, or IoT systems, AWS AppSync Events enables these real-time features through WebSocket APIs, allowing you to build scalable and performant real-time applications, without worrying about scale or connection management.

Powertools for AWS Lambda is a developer toolkit that includes observability, batch processing, AWS Systems Manager Parameter Store integration, idempotency, feature flags, Amazon CloudWatch Metrics, structured logging, and more. Powertools for AWS now supports AppSync Events through the new AppSyncEventsResolver, available in Python, TypeScript, and .NET. This new feature enhances the development experience with capabilities designed to help you focus on your business logic. The AppSyncEventsResolver provides a simple and consistent interface for processing events, with built-in support for common patterns such as filtering, transforming, and routing events.

In this post, you will see examples in TypeScript, but you can use the same functionality in Python and .NET functions using Powertools for AWS (Python) and Powertools for AWS (.NET).

Figure 1 Real-time event handling architecture using AWS AppSync, Lambda, and Powertools

In this post, you’ll learn how to:

Set up event handlers using the AppSyncEventsResolver
Implement different event processing patterns for optimal performance
Use pattern-based routing to organize your event handlers
Leverage built-in features for common use cases

Getting Started

The AppSyncEventsResolver provides a simple, declarative way to handle AppSync Events in your AWS Lambda functions. The event resolver allows you to listen for PUBLISH and SUBSCRIBE events. PUBLISH events occur when clients send messages to a channel, while SUBSCRIBE events happen when clients attempt to subscribe to a channel. You can register handlers for different namespaces and channels to manage your event-driven communications.

Let’s explore how to get started and the core features that will enhance your development experience. Here’s a basic example of how to set up the AppSyncEventsResolver:

import {
  AppSyncEventsResolver,
  UnauthorizedException,
} from '@aws-lambda-powertools/event-handler/appsync-events';

// Types for our message handling
type ChatMessage = {
    userId: string;
    content: string;
}

// Simple authorization check
const isAuthorized = (path: string, userId?: string): boolean => {
    // check against your authorization system
    if (path.startsWith('/chat/private') && !userId) {
        return false;
    }
    return true;
};

// Message processing logic
const processMessage = async (payload: ChatMessage) => {
    // - Validate message content
    // - Store in database
    // - Enrich with additional data
    return {
        ...payload,
        timestamp: new Date().toISOString()
    };
};

const app = new AppSyncEventsResolver();

// Handle publish events for a specific channel
app.onPublish('/chat/general', async (payload: ChatMessage) => {
    // Process and return the message
    return processMessage(payload);
});

// Handle subscription events for all channels
app.onSubscribe('/*', async (info) => {
    const {
        channel: { path },
        request,
    } = info;

    // Perform access control checks
    if (!isAuthorized(path, userId)) {
        throw new UnauthorizedException(`not allowed to subscribe to ${path}`);
    }

    return true;
});

export const handler = async (event, context) =>
  app.resolve(event, context);

The AppSyncEventsResolver class takes care of parsing the incoming event data and invoking the appropriate handler method based on the event type. Let’s break down what’s happening:

Pattern-based Routing

The AppSyncEventsResolver uses an intuitive pattern-based routing system that allows you to organize your event handlers based on channel paths. You can:

Handle specific channels (/chat/general)
Use wildcards for namespaces (/chat/*)
Create global catch-all handlers (/*)

import { AppSyncEventsResolver } from '@aws-lambda-powertools/event-handler/appsync-events';

const app = new AppSyncEventsResolver();

// Specific channel handler
app.onPublish('/notifications/alerts', async (payload) => {
    // your logic here
});

// Handle all channels in the notifications namespace
app.onPublish('/notifications/*', async (payload) => {
    // your logic here
});

// Global catch-all for unhandled channels
app.onPublish('/*', async (payload) => {
    // your logic here
});

export const handler = async (event, context) =>
  app.resolve(event, context);

The most general catch-all handler is /*, which will match any namespace and channel, while /default/* will match any channel in the default namespace. When multiple handlers match the same event, the library will call the most specific handler and ignore the less specific ones. For example, if a handler is registered for /default/channel1 and another one for /default/*, Powertools will call the first handler for events that match /default/channel1 and ignore the second one. This provides you control over how events are handled and to avoid unnecessary processing. If an event that does not match any handler, by default Powertools will return the events as is and log a warning. This means that the events will be passed through without any modifications. This approach is helpful for gradually adopting the library, allowing you to handle specific events with custom logic while others are processed by the default behavior.

Subscription Handling

Powertools also provides a simple way to handle subscription events. It will automatically parse the incoming event and call the appropriate handler based on the event type. By default, AppSync allows the subscription unless your Lambda handler either throws an error or explicitly rejects the request. When a subscription is rejected, AppSync will return a 4xx response to the client and prevent the subscription from being established.

import { AppSyncEventsResolver } from '@aws-lambda-powertools/event-handler/appsync-events';
import { Metrics, MetricUnit } from '@aws-lambda-powertools/metrics';
import type { Context } from 'aws-lambda';

const metrics = new Metrics({
  namespace: 'serverlessAirline',
  serviceName: 'chat',
  singleMetric: true,
});
const app = new AppSyncEventsResolver();

app.onSubscribe('/default/foo', (event) => {
  metrics.addDimension('channel', event.info.channel.path);
  metrics.addMetric('connections', MetricUnit.Count, 1);
});

export const handler = async (event: unknown, context: Context) =>
  app.resolve(event, context);

The library calls the appropriate handler and passes the event object as the first argument when a subscription event arrives. You can take any necessary actions based on the subscription event, such as running access control checks:

app.onSubscribe('/private/*', async (info) => {
  const userGroups =
    info.identity?.groups && Array.isArray(info.identity?.groups)
      ? info.identity?.groups
      : [];
  const channelGroup = 'premium-users';

  if (!userGroups.includes(channelGroup)) {
    throw new UnauthorizedException(
      `Subscription requires ${channelGroup} group membership`
    );
  }
})

Subscription events follow the same matching rules and provide the same access to the full event and context. You can register catch-all handlers for any namespace or channel by using the wildcard * character, and also access the full event and context objects in your handlers.

Access full event and context

While the resolver simplifies event handling, you still have full access to the event and context objects when needed. This is helpful in scenarios where you need additional information, such as request headers or the remaining execution time from the Lambda context, to implement custom logic.

The resolver passes the full event and context to each handler as the second and third arguments. This lets you access all relevant information without changing your existing code.

import { AppSyncEventsResolver } from '@aws-lambda-powertools/event-handler/appsync-events';
import { Logger } from '@aws-lambda-powertools/logger';

const logger = new Logger({
  logLeveL: 'INFO',
  serviceName: 'serverlessAirline'
});
const app = new AppSyncEventsResolver({ logger});

app.onPublish('/orders/process', async (payload, event, context) => {
    // Access request headers
    const { headers } = event.request;
    
    // Access Lambda context
    const { getRemainingTimeInMillis } = context;

    logger.info('Processing event details', {
        headers,
        remainingTime: getRemainingTimeInMillis()
    });

    return payload;
});

export const handler = async (event, context) =>
  app.resolve(event, context);

Error handling

The AppSyncEventsResolver offers built-in error handling that prevents Lambda function failures while ensuring errors are properly communicated to AppSync, which then propagates them to the clients. When an error occurs in your handler, instead of failing the entire Lambda invocation, the resolver captures the error and includes it in the response payload for the specific event that failed.

This approach ensures the Lambda function continues execution while providing properly formatted error messages to AppSync. When processing multiple events, if one event fails, the others continue processing normally. This is particularly useful in parallel processing scenarios where you want to ensure that an error in one event doesn’t affect the processing of other events.

import { AppSyncEventsResolver } from '@aws-lambda-powertools/event-handler/appsync-events';

const app = new AppSyncEventsResolver();

app.onPublish('/messages', async (payload) => {
    // If message contains "error", throw an exception
    if (payload.message === "error") {
        throw new Error("Invalid message");
    }
    return payload;
});

export const handler = async (event, context) =>
  app.resolve(event, context);

// When processing this event:
// {
//     "id": "123",
//     "payload": {
//         "message": "error"
//     }
// }

// The resolver will return:
// {
//     "id": "123",
//     "error": "Error - Invalid message"
// }

Advanced Patterns and Best Practices

The AppSyncEventsResolver has additional advanced features that help you build robust and maintainable real-time applications. Let’s explore these capabilities and how to use them effectively.

On publish processing

By default, we call your route handler once per message. This allows you to focus on your business logic and avoid writing boilerplate code while Powertools handles message iteration and converts the event and response format. You only need to return the value you want to use as payload, or throw an error for that message. The library will then correlate the payload with the correct event id.

import { AppSyncEventsResolver } from '@aws-lambda-powertools/event-handler/appsync-events';
import { Metrics, MetricUnit } from '@aws-lambda-powertools/metrics';

type SensorReading = {
    deviceId: string;
    temperature: number;
    humidity: number;
    timestamp: string;
}

const app = new AppSyncEventsResolver();
const metrics = new Metrics({ namespace: 'SensorReadings' });

app.onPublish('/sensors/readings', async (payload: SensorReading) => {
    // Process each sensor reading independently
    if (payload.temperature > 100) {
        metrics.addDimension('alertType', 'highTemperature');
        metrics.addMetric('HighTemperature', MetricUnit.Count, 1);
        throw new Error('Temperature reading too high');
    }

    // Enrich the payload with processing timestamp
    return {
        ...payload,
        processed: true,
        processedAt: new Date().toISOString()
    };
});

export const handler = async (event, context) =>
  app.resolve(event, context);

This pattern simplifies development by letting you write only the logic for a single event, Powertools handles the rest automatically.

Aggregate Processing

The aggregate mode lets you to process multiple events as a single batch, rather than handling them individually. This is particularly useful when you want to optimize resource usage, such as sending multiple queries to a database in a single operation, or to analyze multiple events together before processing them. While both modes give you full control over event processing, aggregate mode provides access to the entire list of events at once.

To achieve this, you can set the aggregate option to true. When using this mode, the resolver sends the entire list of events to your handler in a single call, letting you process them as a batch.

import { AppSyncEventsResolver } from '@aws-lambda-powertools/event-handler/appsync-events';

const app = new AppSyncEventsResolver();

app.onPublish('/default/*', async (events) => {
  const results = [];
  for (const event of events) {
    try {
      results.push(await handleDefaultNamespaceCatchAll(event));
    } catch (error) {
      results.push({
        error: {
          errorType: 'Error',
          message: error.message,
        },
        id: event.id,
      });
    }
  }

  return results;
}, {
  aggregate: true,
});

export const handler = async (event, context) =>
  app.resolve(event, context);

Note that the aggregate option is only available for publish events, and that when using this option, you are responsible for handling the events and returning the appropriate response. Powertools will still take care of routing the events to the correct handler, but you have full control over how the events are processed.

Event Filtering

To filter out an event, throw an error in the channel handler. If a handler throws an error for a specific event, the library catches it and adds an error object to the response list at the same index. This signals that the corresponding message should be dropped. This allows you to either silently filter events or provide meaningful error feedback to your subscribers.

import { AppSyncEventsResolver } from '@aws-lambda-powertools/event-handler/appsync-events';

app.onPublish('/moderation/*', async (payload) => {
    // Filter out inappropriate content
    if (await containsInappropriateContent(payload)) {
        throw new CustomError('Content violates guidelines');
    }

    // Process valid content
    return await processContent(payload);
});

export const handler = async (event, context) =>
  app.resolve(event, context);

Conclusion

The AppSyncEventsResolver in Powertools for AWS enhances your development experience with AppSync Events by providing a simple and consistent interface for processing real-time events. By reducing boilerplate code and offering built-in support for common patterns, you can focus on your business logic rather than infrastructure code.

To learn more:

Explore the Powertools for AWS documentation for detailed information
Check out the AppSync Events documentation to learn more about the service
Visit our GitHub repository to contribute or report issues

We’re excited to see what you build with these new capabilities. Share your feedback and let us know how you’re using AppSyncEventsResolver in your applications!

From Build to Embed: Creating and Embedding GenAI Apps with AWS Amplify, CDK, and Amazon Q Business

Ben-Amin York Jr. — Tue, 06 May 2025 21:41:20 +0000

In a enterprise landscape, custom applications play a critical role in improving operations, enhancing productivity, and centralizing knowledge within the organization. However, these tools often lack intelligent, conversational interfaces that help users access relevant information faster and more intuitively. Traditional dashboards and search bars fall short when it comes to interpreting complex queries or surfacing contextual insights from vast organizational data.

Generative AI offers a powerful solution to this challenge. By embedding conversational experiences directly into developer-controlled applications, organizations can enable users to ask questions in natural language and receive precise, actionable responses. Amazon Q Business delivers this capability via a secure, embeddable HTML inline frame (iframe)—without the burden of managing large language model infrastructure.

This blog is aimed at developers building custom or enterprise-owned applications—whether knowledge portals, support dashboards, or internal web tools. It shows how to embed a generative AI-powered conversational experience using Amazon Q Business, AWS Amplify Gen 2, and the AWS Cloud Development Kit (CDK). Embedding Amazon Q Business into applications requires access to the application’s source code and is not supported in third-party SaaS platforms where embedding custom code is not possible.

The presented approach enables:

Conversational access to internal documents and knowledge bases.
Secure integration with enterprise identity management systems.
Scalable, AI-driven search without complex backend implementations.
Rapid deployment using AWS Amplify’s capabilities for frontend and backend development.

With Amazon Q Business and AWS Amplify, you can quickly add generative AI to your apps—to boost productivity, reduce manual effort, and accelerate decision-making.

Figure 1 Submitting a prompt to Amazon Q Business iframe.

To embed a generative AI assistant into your internal application, you’ll leverage the following AWS services:

AWS Amplify: A comprehensive set of tools and services that help developers build, deploy, and manage secure full-stack applications. It simplifies frontend and backend development by integrating tightly with services like Amazon Cognito for authentication, Amazon S3 for storage, and the CDK for building additional AWS infrastructure.
Amazon Cognito: A managed service for adding authentication and authorization to your app. Cognito supports user sign-up, sign-in, and access control, and can be federated through an external identity provider (IdP) for enterprise access management.
AWS IAM Identity Center: IAM Identity Center allows secure, centralized access management for your internal users. It supports identity federation with enterprise providers like Okta, Microsoft Entra ID, Ping Identity, and others. This enables your organization to enforce unified authentication policies and ensure only authorized users can interact with the embedded AI assistant.
Amazon Q Business: A managed generative AI service that can be embedded via iframe into internal applications. Q Business connects to enterprise data sources, such as Amazon S3, and enables natural language querying through an intelligent assistant interface. It supports secure access and integrates with IAM Identity Center for federated enterprise use.
Amazon Simple Storage Service (S3): A durable and scalable object storage service used to store internal documents, PDFs, manuals, or any unstructured content. These files act as the knowledge base that powers the Amazon Q Business assistant, enabling contextual responses to employee queries.

Figure 2 From Build to Embed Architecture Diagram

Prerequisites

An AWS account: Note that AWS Amplify is part of the AWS Free Tier.
Install: npm (v9 or later), and git (v2.14.1 or later).
A Text Editor: For this guide we will use VSCode, but you can use your preferred IDE.
Sample Dataset: Upload any PDF or explore sample data sets available on Kaggle.
IAM Identity Center: You must enable an IAM Identity Center instance and add a user to your Identity Center directory.

Cloning the Repo

Step 1: Navigate to the repository on AWS Samples and fork it to your GitHub repositories.

Step 2: Clone the app by running the command below in your terminal.

git clone https://github.com/<YOUR_GITHUB_USERNAME>/sample-build-and-embed-genai-apps.git

Step 3: Access the newly cloned repository in VSCode by executing the commands below in your terminal.

cd sample-build-and-embed-genai-apps 
code . -r

VSCode will open the repository folder, including the Amplify folder, which contains the app code that you’ll review in the next section.

Figure 3 Opening code in VSCode.

Step 4: Install the required packages, including the Amplify Gen 2 packages, by running the following command:

npm install

The Amplify Backend

In the final app (as seen in the gif at the beginning of the post), users log into the application, click the chatbot icon, authenticate with federated access (via the iframe to access Q Business web experience), and finally are able to begin asking questions to Amazon Q Business. The code for this is in the repository you cloned. Here, you’ll go over the key steps for creating your Amplify-developed and hosted search engine app.

Figure 4 Amplify Gen 2 Project Folder Structure.

In the amplify/auth/resource.ts file (Figure 5), authentication is configured to require users to log in with their email to access the application and upload files. By enabling email-based login, you ensure only verified users can interact with sensitive data and functionalities.

import { defineAuth } from '@aws-amplify/backend';
 
export const auth = defineAuth({
    loginWith: {
        email: true,
    },
});

Figure 5 defineAuth in amplify/auth/resource.ts

In the amplify/storage/resource.ts file (Figure 6), Amplify storage is configured to enable secure, user-scoped file management. The defineStorage function instantiates the storage resource with a user-friendly name q-datasource-bucket and applies access control to the protected/{entity_id}/* path. This configuration allows authenticated users to read files within their own scoped directory, while granting the file owner permissions to read, write, and delete their content.

import { defineStorage } from "@aws-amplify/backend";
 
export const storage = defineStorage({
    name: "q-datasource-bucket",
    access: (allow) => ({
        'protected/{entity_id}/*': [
            allow.authenticated.to(['read']),
            allow.entity('identity').to(['read', 'write', 'delete'])
        ]
    })
});

Figure 6 defineStorage in amplify/storage/resource.ts

In the amplify/backend.ts (Figure 7) file, you import the CDK libraries to configure key aspects of your application. The aws-iam module is used to manage permissions, aws-kms handles encryption and key management, and aws-qbusiness integrates Amazon Q Business into your stack. Each library plays a specific role in ensuring your application is secure and properly integrated with AWS services.

import * as iam from 'aws-cdk-lib/aws-iam';
import * as kms from 'aws-cdk-lib/aws-kms';
import * as q from 'aws-cdk-lib/aws-qbusiness';

Figure 7 import CDK libraries in amplify/backend.ts

Next, use the backend.createStack() (Figure 8) method to direct the backend to generate a new CloudFormation Stack to house custom resources. With AWS Amplify Gen 2, you can create custom resources using the CDK, enabling the use of services beyond the Amplify library, with stacks backed by CloudFormation templates for scalability. For example, you could create a Generative AI stack for AI-related services, ensuring logical organization before adding custom AWS resources. Now, you can begin defining custom AWS resources!

export const customResource = backend.createStack("CustomResourceStack");

Figure 8 define backend stack for custom resources in amplify/backend.ts

During the CustomResourceStack deployment, you’ll see several IAM roles, trust policies, and inline access policies being created—all of which are critical for enabling Amazon Q Business to function securely and interact with other AWS services. These include:

Service Access Role (QApplicationServiceAccessRole) for Amazon Q Business to emit logs and metrics via CloudWatch.
Web Experience Roles (QWebExperienceRole and QWebExperienceRole) for enabling the embedded assistant to function with full application context and user interactions.
Data Source Role (QBusinessS3Role) specifically for allowing Amazon Q Business to read documents from the S3 bucket provisioned by Amplify Storage.

Each role includes a trust policy defining who can assume the role, and a series of fine-grained permissions granting access to specific actions and resources. You can view the full required policy structure for Amazon Q Business data sources in the IAM roles documentation for Amazon Q Business connectors.

Setting Up Amazon Q Business

With all foundational IAM roles and policies in place, you’re ready to define the Amazon Q Business application, the core component that powers the embedded generative AI assistant. In your amplify/backend.ts (Figure 9) file, using the CDK, you can instantiate it declaratively with the necessary configuration, subscription plan, and IAM integration:

export const qapp = new q.CfnApplication(customResource, "Qapp", {
  displayName: "Qapp",
  description: "CDK instantiated Amazon Q Business App",
  autoSubscriptionConfiguration: {
    autoSubscribe: "ENABLED",
    defaultSubscriptionType: "Q_LITE"
  },
  identityType: "AWS_IAM_IDC",
  roleArn: `arn:aws:iam::${customResource.account}:role/aws-service-role/qbusiness.amazonaws.com/AWSServiceRoleForQBusiness`,
  /* REPLACE WITH YOUR IAM IDENTITY CENTER ARN */
  // identityCenterInstanceArn: "arn:aws:sso:::instance/",
});

Figure 9 defining Q Business Application in amplify/backend.ts

This step formally creates the Q Business application and associates it with the service-linked role (AWSServiceRoleForQBusiness). Be sure to substitute your IAM Identity Center ARN before deployment to enable federated access for users.

Creating an Index

Indexes in Amazon Q Business are used to store, organize, and retrieve enterprise data efficiently. You need an index to enable structured querying of stored documents, allowing the chatbot to retrieve relevant responses based on user queries. The following CDK code in your amplify/backend.ts (Figure 10) sets up an index within your Amazon Q Business application:

export const qIndex = new q.CfnIndex(customResource, "QIndex", {
  displayName: "QIndex",
  description: "CDK instantiated Amazon Q Business App index",
  applicationId: qapp.attrApplicationId,
  capacityConfiguration: {
    units: 1,
  },
  type: "STARTER",
});

Figure 10 defining Q Business Index in amplify/backend.ts

Here, the STARTER index type is selected, which is a basic configuration suitable for testing and small-scale deployments. For production use, a higher tier like ENTERPRISE would be necessary to ensure scalability, availability, and support for advanced features—see the Amazon Q Business pricing and tiers for guidance.

Creating a Retriever

Retrievers enhance the search capabilities by fetching relevant documents from the index. In Amazon Q Business, a retriever connects to the index and ensures that queries return meaningful responses. The following CDK code in your amplify/backend.ts (Figure 11) sets up a retriever within your Amazon Q Business application:

export const qRetriever = new q.CfnRetriever(customResource, "QRetriever", {
  displayName: "QRetriever",
  applicationId: qapp.attrApplicationId,
  type: "NATIVE_INDEX",
  configuration: {
    nativeIndexConfiguration: {
      indexId: qIndex.attrIndexId,
    },
  }
});

Figure 11 defining Q Business Retriever in amplify/backend.ts

This retriever is configured to work with the previously created qIndex, ensuring efficient retrieval of indexed content for Amazon Q Business.

Defining a Data Source

A data source is where the Amazon Q Business application retrieves data for its knowledge base. In this case, the data source is an Amazon S3 bucket defined earlier in the Amplify Storage configuration amplify/storage/resource.ts and referenced in the amplify/backend.ts (Figure 12) file. This bucket stores documents that Amazon Q Business will index and analyze.

export const qDataSource = new q.CfnDataSource(customResource, "QDataSource", {
  displayName: `${backend.storage.resources.bucket.bucketName}`,
  applicationId: qapp.attrApplicationId,
  indexId: qIndex.attrIndexId,
  configuration: {
    type: "S3",
    syncMode: "FULL_CRAWL",
    connectionConfiguration: {
      repositoryEndpointMetadata: {
        BucketName: backend.storage.resources.bucket.bucketName
      }
    },
    repositoryConfigurations: {
      document: {
        fieldMappings: [
          {
            indexFieldName: "s3_document_id",
            indexFieldType: "STRING",
            dataSourceFieldName: "s3_document_id"
          }
        ]
      }
    },
  },
  roleArn: qBusinessS3Role.roleArn
});

Figure 12 defining Q Business Data Source in amplify/backend.ts

The key elements in this setup:

syncMode: “FULL_CRAWL” ensures that all documents in the S3 bucket are indexed.
Field mappings define how document metadata is structured for indexing.

Creating the Amazon Q Business Web Experience

The Web Experience in amazon Q business is a frontend that allows users to interact with Amazon Q Business embedded in a customized chatbot. This component is defined in your amplify/backend.ts (Figure 13) file and defines how the chatbot interface appears and functions, including allowed website origins, branding, and authentication.

export const qWebExperience = new q.CfnWebExperience(customResource, "QWebExperience", {
  applicationId: qapp.attrApplicationId,
  origins: [
    /* REPLACE WITH YOUR AMPLIFY DOMAIN URL */
    "https://main..amplifyapp.com",
  ],
  samplePromptsControlMode: "ENABLED",
  subtitle: "AnyCompany Generative AI Assistant",
  title: "AnyCompany Q App",
  welcomeMessage: "Welcome to your Amazon Q Business Application!",
  roleArn: qWebExperienceRole.roleArn
});

Figure 13 defining Q Business Web Experience in amplify/backend.ts

Web Experience Configuration

Origins: Specifies the website domains permitted to embed the chatbot via an <iframe>. Ensure that your Amplify app’s deployed URL is correctly listed here.
samplePromptsControlMode: Enables storing predefined sample prompts within the chatbot UI.
title & subtitle: Sets the chatbot’s display name and additional descriptions.
welcomeMessage: The first message users see when they open the chat window.

Amazon Q Business and Frontend Integration

After configuring the web experience, you can now embed your Amazon Q Business web experience using an iframe. In src/components/qframe.tsx (Figure 14), the src is dynamically populated from the amplify_outputs.json file, which contains the deployed URL of your Q Web Experience exported by the backend. Users are prompted to authenticate in a new browser tab, after which the chat session continues within the embedded iframe.

import React from 'react';
import rawOutputs from '../../amplify_outputs.json';
 
const outputs = rawOutputs as unknown as {
    custom: {
        q_business_url: string;
    };
};
 
const QFrame: React.FC = () => {
    const qBusinessDeployedURL = outputs.custom.q_business_url;
 
    return (
        <iframe
            src={qBusinessDeployedURL}
            title="Chatbot"
            className="QFrame"
        />
    );
};
 
export default QFrame;

Figure 14 Embeds Amazon Q Business via iframe using config URL.

Running the App

Step 1: Amplify provides each developer with a personal cloud sandbox environment, offering isolated development spaces for rapid building, testing, and iteration. To initiate a cloud sandbox environment, open a new terminal window and execute the following command:

npx ampx sandbox

Step 2: Execute the following command to start a localhost development server.

npm run dev

After running the previous command to start the application, use the ‘Create Account‘ feature of the Amplify Authenticator component, and provide an email address and password. After finalizing user setup via a confirmation email, log in to gain access to the application. (Figure 15)

Figure 15 Logging in using the Amplify Authenticator component during local development testing.

After interacting with the app on the development server, stop the sandbox environment by pressing Ctrl + C in the terminal. Then enter “npx ampx sandbox delete” and confirm by entering ‘Y‘ when prompted to delete resources in the sandbox environment. (Figure 16)

Figure 16 Deleting all resources in the Amplify sandbox environment

Deploying backend resources

With the app functioning as expected, deploy your backend resources by following the steps in “Getting Started with Deploying an App to Amplify Hosting“. Ensure that GitHub is selected as the repository for deployment.

Update Amplify Domain Endpoint

In your backend CDK code, navigate to amplify/backend.ts and replace the placeholder in the origins field with your actual Amplify domain. You can find this domain in the Amplify console under the app name you created in the previous section. (Figure 17)

origins: [
  "https://main.<AMPLIFY_APP_ID>.amplifyapp.com",
],

Figure 17 Updating the origins field in the CDK backend code with your Amplify app’s deployed domain.

Upload Sample Data

After deploying and signing into the application, upload sample data by accessing the app domain URL generated by Amplify. After uploading files, confirm the upload by checking the public/ folder within the Storage section of the AWS Amplify console. (Figure 18)

Figure 18 Uploading sample data in deployed app.

Configure User Access to Q Business Web Experience

Next, for your Qapp, you need to assign a user who can log in to the embedded web experience. This user should have been created during the prerequisites using IAM Identity Center. To add a new or existing user, in the Amazon Q Business console, select your Qapp, then navigate to the User access section and click Manage user access, followed by Add groups and users. (Figure 19)

Figure 19 Assigning user access via IAM Identity Center.

If the user already exists, choose Assign existing users and groups and search for the user you want to assign. Once added, confirm your selection to grant access to the Amazon Q Business web experience. (Figure 20)

Figure 20 Granting access to existing IAM Identity Center users.

Sync S3 Data to Q Business Index

After uploading your sample document, sync the Amazon S3 bucket with the Amazon Q Business index to store and retrieve your data. From the Amazon Q Business console, navigate to Data Sources, select amplify-your-unique-bucket-name. Then, select Sync now (Figure 21).

Figure 21 Syncing uploaded S3 data to Q Business index.

Once the data source sync completes and the last sync status shows “completed“, you’re almost ready to begin using your Amazon Q Business web experience. Before proceeding, make sure to sign in. After a successful sign-in, you’ll see a “Sign in Complete” message. At that point, you can return to your application—authentication is now complete. (Figure 22)

Figure 22 Confirming sign-in completion for authentication.

Now that you are signed in, start querying your Amazon Q Business web experience directly through your application! (Figure 23)

Figure 23 Querying Amazon Q Business in your application.

Cleaning Up

To remove the AWS Identity Center console instance, go to “Settings“, and open the “Management” tab. Under the “Delete IAM Identity Center instance” section, select “Delete” to remove it.

Lastly, within the AWS Amplify console, select “View app” for the application you created following this blog. Then, select “App Settings” followed by “General Settings.” Finally, select “Delete app” to remove the application and associated backend resources. Note, Amplify will delete all backend resources created as a part of your project.

Conclusion

In this blog, we explained the key steps for integrating Amazon Q Business into a custom application: setting up the frontend with AWS Amplify, configuring the Q Business application using the CDK, and embedding the chatbot via an iframe. By leveraging these AWS Services and tools, you can create an AI-powered search experience that improves user interaction and knowledge accessibility.

Now it’s your turn! Embed conversational AI into your applications and unlock new levels of productivity and decision-making with Amazon Q Business. Then, supercharge your development workflow with Amazon Q Developer. Harness the power of generative AI and cloud computing to accelerate your development and quickly build modern applications that drive innovation.

New features and developer experience with enhanced Amazon Location Service

Zach Elliott — Wed, 02 Apr 2025 18:23:48 +0000

This blog post was written by Yasunori Kirimoto – CEO of MIERUNE

Building geospatial applications requires expertise in handling geospatial data, as well as designing and developing systems. It also requires skills in collecting and managing vast amounts of geospatial data and using it effectively within the application. This process can be very labor intensive, but its complexity can be greatly reduced by leveraging Amazon Location Service.

With Amazon Location Service, highly accurate geospatial data can be quickly obtained from APIs, allowing developers to focus on building applications. In addition, Amazon Location Service has been updated, adding new features in addition to its previous functionality. We’ll introduce the new features of Amazon Location Service and demonstrate how to leverage them in your application.

New features released from Amazon Location Service

The biggest change is that resource creation is no longer required. This means users no longer need to create individual resources (such as Place Indexes, Maps, and Route Calculators), but can set up an API key and immediately start using Amazon Location Service.

In addition, significant enhancements and new features have been added to the Maps, Places, and Routes APIs. The Maps API has been updated with additional styles, as well as the new static map capability. The Places API has been enhanced with new search and geocoding capabilities. Finally, the Routes API has been updated with new features such as Snap to Road, Waypoint Optimization, and additional travel modes.

Creating API Keys

In order to create an API Key, we can utilize the AWS Management Console, or the AWS Cloud Control API. For this example, we will use the console. Navigate to the Amazon Location Service Console, and select API keys under Manage resources. Select Create API key

Figure 1 – The Amazon Location Service Console – API keys console

For the purposes of our demonstration, we will name the API Key LasVegasMaps and select the following actions:

– GetStaticMap
– GetTile
– Geocode
– GetPlace
– SearchNearby
– SearchText
– CalculateIsolines
– SnapToRoads

Figure 2 – Selecting API Key actions

Scrolling down, we have additional options including the ability to set an Expire time, and Referers. These are optional, but we highly recommend them for production applications. NOTE: For the purposes of this demonstration we are leaving these as Default.

Figure 3 –Additional API Key options

Select Create API key.

Now with the API Key created, we need to retrieve the value to use in our application. Select Show API key value and copy the value into a safe location.

Figure 4 – API Key Console showing API Key Value

New Maps API features

First, we will highlight and introduce the GetStyleDescriptor and GetStaticMap functions.

Building the foundation for a map application with GetStyleDescriptor

The GetStyleDescriptor function allows you to retrieve map style information and quickly build the foundation for your map application. This feature could be used for various geospatial solutions and application foundations. The new version offers expanded map styles, purpose-built for different applications—offering dark and light mode with varying levels of map detail.

We will demonstrate how to take advantage of these map styles using MapLibre GL JS. We’ll create a very straightforward HTML page using MapLibre GL JS and Amazon Location Service API Keys.

Begin by creating a blank HTML page, naming it simpleMap.html, and copying the following code into the page:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Amazon Location Service Map</title>

    <!-- MapLibre GL CSS -->
    <link href="https://unpkg.com/maplibre-gl@3.x/dist/maplibre-gl.css" rel="stylesheet" />

    <style>
        body {
            margin: 0;
        }
        #map {
            height: 100vh; /* Full viewport height */
        }
    </style>
</head>

<body>
    <!-- Map container -->
    <div id="map"></div>

    <!-- JavaScript dependencies -->
    <script src="https://unpkg.com/maplibre-gl@3.x/dist/maplibre-gl.js"></script>

    <script>
        // Configuration
        const region = "<AWS Region>"; // Replace with your AWS region
        const mapApiKey = "<Your API Key>"; // Replace with your Amazon Location Service API key

        async function initializeMap() {
            // Initialize the map
            const map = new maplibregl.Map({
                container: "map", // HTML element ID where the map will be rendered
                center: [-115.1473824627421, 36.17071351509272], // Initial map center coordinates (Las Vegas)
                zoom: 12, // Initial zoom level
                style: `https://maps.geo.${region}.amazonaws.com/v2/styles/Standard/descriptor?&color-scheme=Light&variant=Default&key=${mapApiKey}`, // Map style URL
            });

            // Add navigation controls to the map
            map.addControl(new maplibregl.NavigationControl(), "top-left");
        }

        // Call the function to initialize the map
        initializeMap();
    </script>
</body>
</html>

Now open this HTML page in a browser. You should see a map of Las Vegas, NV. The key to this map is the style URL we set previously in our code. In this URL, we’ve requested that we use the Standard style map in a light color scheme. We can add additional parameters such as political views as well.

Figure 5 – Map centered on Las Vegas, NV

Creating a static map image with GetStaticMap

The GetStaticMap feature allows you to create a static map image based on the coordinates, zoom level, and image size you specify. This feature helps include map images in printed materials and media posts. There are various parameters for this feature, including the ability to overlay other data (such as points, lines and polygons). We’ve provided a basic example. Be certain to edit the URL for your AWS Region and your newly created API Key. Paste the following URL into the address bar of your web browser to display a static map image of the specified location:

https://maps.geo.<Your AWS Region>.amazonaws.com/v2/static/map?center=-115.170,36.122&zoom=15&width=1024&height=1024&key=<Your API Key>

Figure 6 –Static map image showing the Las Vegas strip

New Places API features

Next, we will highlight and introduce the SearchText and SearchNearby features.

Searching for specified POI data with SearchText

The SearchText feature allows users to search for and present specified points of interest (POI) data. This feature is designed for users to quickly search for a specific location or facility. Users can send a POST request with the specified parameters and receive a response containing candidate point data. We will demonstrate an example of visualizing that data on a map.

Create a new HTML file named searchText.html and paste the following contents into the file:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Amazon Location Service – Search Text</title>

    <link href="https://unpkg.com/maplibre-gl@3.x/dist/maplibre-gl.css" rel="stylesheet" />
    <style>
      body {
        margin: 0;
      }
      #map {
        height: 100vh;
      }
    </style>
  </head>

  <body>
    <!-- map container -->
    <div id="map"></div>
    <!-- JavaScript dependencies -->
    <script src="https://unpkg.com/maplibre-gl@3.x/dist/maplibre-gl.js"></script>
    <!-- Import the Amazon Location Client -->
    <script src="https://cdn.jsdelivr.net/npm/@aws/amazon-location-client@1"></script>
    <!-- Import the utility library -->
    <script src="https://cdn.jsdelivr.net/npm/@aws/amazon-location-utilities-datatypes@1"></script>
    <script>
      // Configuration
      // Set the AWS region for Amazon Location Service
      const region = "<AWS Region>";
      // API key for authenticating requests
      const mapApiKey = "<Amazon Location Service API Key>";
    
      async function initializeMap() {
        // Create an authentication helper using the API key
        const authHelper = await amazonLocationClient.withAPIKey(mapApiKey, region);
        
        // Initialize the Amazon Location Service Places client
        const client = new amazonLocationClient.places.GeoPlacesClient(
          authHelper.getClientConfig()
        );
    
        // Define search parameters for coffee shops
        const SearchTextInput = {
          BiasPosition: [-115.170, 36.122], // Las Vegas coordinates
          MaxResults: 25,
          QueryText: "Coffee Shops"
        }
    
        // Perform the search using Amazon Location Service
        const searchResults = await client.send(
          new amazonLocationClient.places.SearchTextCommand(SearchTextInput)
        )
    
        // Initialize the map
        const map = new maplibregl.Map({
          container: "map",
          center: [-115.170, 36.122], // Las Vegas coordinates
          zoom: 14,
          style: `https://maps.geo.${region}.amazonaws.com/v2/styles/Standard/descriptor?&color-scheme=Light&variant=Default&key=${mapApiKey}`,
        });
    
        // Add navigation controls to the map
        map.addControl(new maplibregl.NavigationControl(), "top-left");
    
        // When the map is loaded, add search results as a layer
        map.on("load", () => {
          // Convert search results into a GeoJSON FeatureCollection
          const featureCollection = amazonLocationDataConverter.searchTextResponseToFeatureCollection(searchResults);
    
          // Add a data source containing GeoJSON from the search results
          map.addSource("place-index-results", {
            type: "geojson",
            data: featureCollection,
          });
    
          // Add a new layer to visualize the points
          map.addLayer({
            id: "place-index-results",
            type: "circle",
            source: "place-index-results",
            paint: {
              "circle-radius": 8,
              "circle-color": "#0080ff",
            },
          });
    
          // Add click event listener for the search result points
          map.on('click', 'place-index-results', (e) => {
            if (e.features.length > 0) {
              const feature = e.features[0];
              const coordinates = feature.geometry.coordinates.slice();
              
              // Create a formatted HTML string with the feature's properties
              const properties = feature.properties;
              let description = '<h3>' + (properties['Title'] || 'Unnamed Location') + '</h3>';
              description += '<p>Address: ' + (properties['Address.Label'] || 'N/A') + '</p>';
    
              // Create and display a popup with the location information
              new maplibregl.Popup()
                .setLngLat(coordinates)
                .setHTML(description)
                .addTo(map);
            }
          });
          map.on('mouseenter', 'place-index-results', () => {
            map.getCanvas().style.cursor = 'pointer';
          });
          map.on('mouseleave', 'place-index-results', () => {
            map.getCanvas().style.cursor = '';
          });
        });
      }
    
      // Call the function to initialize the map
      initializeMap();
    </script>
  </body>
</html>

Opening the HTML file in a browser will show the following map with coffee shops centered around the Venetian Resort in Las Vegas, NV (Figure 7).

Figure 7 – Map showing the results of the SearchText API

Searching to retrieve POI data around a specified location with SearchNearby

The SearchNearby function allows you to retrieve POI data near a specified location. This feature is handy for users to search for nearby stores and attractions. Users can send a POST request with the specified parameters and receive a response containing candidate point data. We will demonstrate an example of visualizing that data on a map.

Create a new HTML file named searchNearby.html and paste the following contents into the file:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Amazon Location Service – Search Nearby</title>

    <link href="https://unpkg.com/maplibre-gl@3.x/dist/maplibre-gl.css" rel="stylesheet" />
    <style>
      body {
        margin: 0;
      }
      #map {
        height: 100vh;
      }
    </style>
  </head>

  <body>
    <!-- map container -->
    <div id="map"></div>
    <!-- JavaScript dependencies -->
    <script src="https://unpkg.com/maplibre-gl@3.x/dist/maplibre-gl.js"></script>
    <!-- Import the Amazon Location Client -->
    <script src="https://cdn.jsdelivr.net/npm/@aws/amazon-location-client@1"></script>
    <!-- Import the utility library -->
    <script src="https://cdn.jsdelivr.net/npm/@aws/amazon-location-utilities-datatypes@1"></script>
    <script>
      // Configuration
      
      // Set the AWS region for Amazon Location Service
      const region = "<AWS Region>";
      // API key for authenticating map requests
      const mapApiKey = "<Amazon Location Service API Key>";
    
      async function initializeMap() {
        // Create an authentication helper using the API key
        const authHelper = await amazonLocationClient.withAPIKey(mapApiKey, region);
        
        // Initialize the Amazon Location Service Places client
        const client = new amazonLocationClient.places.GeoPlacesClient(
          authHelper.getClientConfig()
        );
    
        // Define search parameters for nearby casinos and hotels
        const SearchNearbyInput = {
          QueryPosition: [-115.170, 36.122], // Las Vegas coordinates
          MaxResults: 25,
          Filter: {
            IncludeCategories: [
              "casino",
              "hotel"
            ]
          }
        }
    
        // Perform the nearby search using Amazon Location Service
        const searchResults = await client.send(
          new amazonLocationClient.places.SearchNearbyCommand(SearchNearbyInput)
        )
    
        // Initialize the map
        const map = new maplibregl.Map({
          container: "map",
          center: [-115.170, 36.122], // Las Vegas coordinates
          zoom: 15,
          style: `https://maps.geo.${region}.amazonaws.com/v2/styles/Standard/descriptor?&color-scheme=Light&variant=Default&key=${mapApiKey}`,
        });
    
        // Add navigation controls to the map
        map.addControl(new maplibregl.NavigationControl(), "top-left");
    
        // When the map is loaded, add search results as a layer
        map.on("load", () => {
          // Convert search results into a GeoJSON FeatureCollection
          const featureCollection = amazonLocationDataConverter.searchNearbyResponseToFeatureCollection(searchResults);
    
          // Add a data source containing GeoJSON from the search results
          map.addSource("place-index-results", {
            type: "geojson",
            data: featureCollection,
          });
        
          // Add a new layer to visualize the points
          map.addLayer({
            id: "place-index-results",
            type: "circle",
            source: "place-index-results",
            paint: {
              "circle-radius": 8,
              "circle-color": "#0080ff",
            },
          });
    
          // Add click event listener for the search result points
          map.on('click', 'place-index-results', (e) => {
            if (e.features.length > 0) {
              const feature = e.features[0];
              const coordinates = feature.geometry.coordinates.slice();
              
              // Create a formatted HTML string with the feature's properties
              const properties = feature.properties;
              let description = '<h3>' + (properties['Title'] || 'Unnamed Location') + '</h3>';
              description += '<p>Address: ' + (properties['Address.Label'] || 'N/A') + '</p>';
    
              // Create and display a popup with the location information
              new maplibregl.Popup()
                .setLngLat(coordinates)
                .setHTML(description)
                .addTo(map);
            }
          });
          map.on('mouseenter', 'place-index-results', () => {
            map.getCanvas().style.cursor = 'pointer';
          });
          map.on('mouseleave', 'place-index-results', () => {
            map.getCanvas().style.cursor = '';
          });
        });
      }
    
      // Call the function to initialize the map
      initializeMap();
    </script>
  </body>
</html>

Opening the HTML file in a browser will show the following map showing hotel and casino locations centered around the Venetian Resort in Las Vegas, NV (Figure 8).

Figure 8 – Map showing results of the SearchNearby API

New Routes API features

Finally, we will discuss the new CalculateIsolines and SnapToRoads functions.

Find the reachable range from a specified location with CalculateIsolines

The CalculateIsolines function can retrieve the reachable range from a specified point. Some use cases for Isolines include identifying deliverable areas and evaluating property locations. Users can send a POST request with the specified parameters and receive a response containing polygon data indicating the reachable area. We will demonstrate an example of visualizing that data on a map.

Create a new HTML file and name it calculateIsolines.html and paste the following contents into the file:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Amazon Location Service - Isolines</title>

    <link href="https://unpkg.com/maplibre-gl@3.x/dist/maplibre-gl.css" rel="stylesheet" />
    <style>
      body {
        margin: 0;
      }
      #map {
        height: 100vh;
      }
    </style>
  </head>

  <body>
    <!-- map container -->
    <div id="map"></div>
    <!-- JavaScript dependencies -->
    <script src="https://unpkg.com/maplibre-gl@3.x/dist/maplibre-gl.js"></script>
    <!-- Import the Amazon Location Client -->
    <script src="https://cdn.jsdelivr.net/npm/@aws/amazon-location-client@1"></script>
    <!-- Import the utility library -->
    <script src="https://cdn.jsdelivr.net/npm/@aws/amazon-location-utilities-datatypes@1"></script>
    <script>
      // Configuration
      
      // Set the AWS region for the Amazon Location Service
      const region = "<AWS Region>";
      // API key for authenticating map requests
      const mapApiKey = "<Amazon Location Service API Key";
    
      async function initializeMap() {
        // Create an authentication helper using the API key
        const authHelper = await amazonLocationClient.withAPIKey(mapApiKey, region);
        
        // Initialize the Amazon Location Service Routes client
        const client = new amazonLocationClient.routes.GeoRoutesClient(
          authHelper.getClientConfig()
        );
    
        // Define parameters for calculating isolines
        const IsolinesInput = {
          Origin: [-115.17015436843275, 36.12122662193694], // Starting point coordinates
          Thresholds: {
            Time: [
              300, 600, 900 // Time thresholds in seconds
            ]
          },
          TravelMode: "Pedestrian" // Travel mode for isoline calculation
        }
    
        // Calculate isolines using Amazon Location Service
        const routeResults = await client.send(
          new amazonLocationClient.routes.CalculateIsolinesCommand(IsolinesInput)
        )
    
        // Initialize the map
        const map = new maplibregl.Map({
          container: "map",
          center: [-115.16766776735061, 36.12177195550658], // Map center coordinates
          zoom: 15,
          style: `https://maps.geo.${region}.amazonaws.com/v2/styles/Standard/descriptor?&color-scheme=Light&variant=Default&key=${mapApiKey}`,
        });
    
        // Add navigation controls to the map
        map.addControl(new maplibregl.NavigationControl(), "top-left");
    
        // Add a marker at the origin point
        const marker = new maplibregl.Marker()
          .setLngLat([-115.17015436843275, 36.12122662193694])
          .addTo(map)
    
        // When the map is loaded, add isolines as layers
        map.on("load", () => {
          // Convert isoline results into a GeoJSON FeatureCollection
          const featureCollection = amazonLocationDataConverter.calculateIsolinesResponseToFeatureCollection(routeResults);
    
          // Add a data source containing GeoJSON from the isoline results
          map.addSource("isolines", {
            type: "geojson",
            data: featureCollection
          });
    
          // Add a fill layer to visualize the isoline areas
          map.addLayer({
            'id': 'isolines-fill-900',
            'type': 'fill',
            'source': 'isolines',
            'filter': ['==', ['get', 'TimeThreshold'], 900],
            'paint': {
              'fill-color': '#0000ff',
              'fill-opacity': 0.5
            }
          });

          // Add a layer for 600m (10)
          map.addLayer({
            'id': 'isolines-fill-600',
            'type': 'fill',
            'source': 'isolines',
            'filter': ['==', ['get', 'TimeThreshold'], 600],
            'paint': {
              'fill-color': '#00ff00',
              'fill-opacity': .5
            }
          });

          // Add a layer for 300m (5)
          map.addLayer({
            'id': 'isolines-fill-300',
            'type': 'fill',
            'source': 'isolines',
            'filter': ['==', ['get', 'TimeThreshold'], 300],
            'paint': {
              'fill-color': '#f10000',
              'fill-opacity': 0.5
            }
          });
    
          // Add an outline layer to highlight the isoline boundaries
          map.addLayer({
            'id': 'isolines-outline',
            'type': 'line',
            'source': 'isolines',
            'paint': {
              'line-color': '#000000',
              'line-width': 2
            }
          });
        });
      }
    
      // Call the function to initialize the map
      initializeMap();
    </script>
  </body>
</html>

Opening the HTML file in a browser will show the following map (Figure 9). This map shows walkable distances from the Venetian Resort in 5-, 15-, and 30-minute timeframes.

Figure 9 – Map showing walking distances from the Venetian resort

Obtaining location-corrected route data with SnapToRoads

The SnapToRoads function allows you to snap GPS data and other location data to the nearest road and obtain line data after location correction. This feature is very useful in improving the accuracy of vehicle tracking and traffic analysis. Users can send a POST request with specified parameters and receive a response containing position-corrected line data. We will demonstrate an example of visualizing the data before and after processing on a map.

Create a new HTML file named snapToRoad.html and paste the following contents into the file:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Amazon Location Service - Snap to Roads</title>

    <!-- MapLibre GL CSS -->
    <link href="https://unpkg.com/maplibre-gl@3.x/dist/maplibre-gl.css" rel="stylesheet" />

    <style>
        body {
            margin: 0;
        }
        #map {
            height: 100vh; /* Full viewport height */
        }
    </style>
</head>

<body>
    <!-- Map container -->
    <div id="map"></div>

    <!-- JavaScript dependencies -->
    <script src="https://unpkg.com/maplibre-gl@3.x/dist/maplibre-gl.js"></script>
    <!-- Amazon Location Client -->
    <script src="https://cdn.jsdelivr.net/npm/@aws/amazon-location-client@1"></script>
    <!-- Amazon Location utility library -->
    <script src="https://cdn.jsdelivr.net/npm/@aws/amazon-location-utilities-datatypes@1"></script>

    <script>
        // Configuration
        const region = "<AWS Region>"; // Replace with your AWS region
        const mapApiKey = "<Amazon Location Service API Key>"; // Replace with your API key

        async function initializeMap() {
            // Create authentication helper
            const authHelper = await amazonLocationClient.withAPIKey(mapApiKey, region);
            // Initialize Amazon Location Service Routes client
            const client = new amazonLocationClient.routes.GeoRoutesClient(
                authHelper.getClientConfig()
            );

            // GPS trace coordinates
            const gpsTraceCoordinates = [
                [-115.14564318728544, 36.09359703860663],
                [-115.14522142988834, 36.09368914760097],
                [-115.14477687479442, 36.09345887491297],
                [-115.14452610012599, 36.093560194978636],
                [-115.14432092085157, 36.09364309311755],
                [-115.14383077036334, 36.09360624951118],
                [-115.14303285096376, 36.09360624951118],
                [-115.14273648090104, 36.09375362383305],
                [-115.14218933616989, 36.09353256224662],
                [-115.14163079259018, 36.0936154604141],
                [-115.14126602943631, 36.093633882217304],
                [-115.14136861907319, 36.09338518751021],
                [-115.14126602943631, 36.093035171404196],
                [-115.14093546282783, 36.092906217708844],
                [-115.140479508885, 36.09289700672278],
                [-115.14033132385379, 36.09270357576062],
                [-115.13951060675709, 36.09278647480254],
                [-115.13900905742025, 36.09291542869438],
                [-115.13839351959763, 36.09298911653757],
                [-115.1378349760179, 36.092906217708844],
                [-115.13733342668108, 36.09301674946067],
                [-115.13703705661834, 36.09286016276663]
             ];

            // Format trace points for Snap to Roads API
            const tracePoints = gpsTraceCoordinates.map(coord => ({
                Position: coord,
            }));    

            // Snap to Roads API input
            const SnapInput = {
                TracePoints: tracePoints
            };

            // Call Snap to Roads API
            const snapResults = await client.send(
                new amazonLocationClient.routes.SnapToRoadsCommand(SnapInput)
            );

            // Initialize the map
            const map = new maplibregl.Map({
                container: "map",
                center: [-115.14127503567818, 36.09249839687936], // Las Vegas area
                zoom: 16,
                style: `https://maps.geo.${region}.amazonaws.com/v2/styles/Standard/descriptor?&color-scheme=Light&variant=Default&key=${mapApiKey}`,
            });

            // Add navigation controls
            map.addControl(new maplibregl.NavigationControl(), "top-left");

            // When the map is loaded, add the GPS trace and snapped route
            map.on("load", () => {
                // Convert snap results to GeoJSON
                const featureCollection = amazonLocationDataConverter.snapToRoadsResponseToFeatureCollection(snapResults);

                // Add GPS trace source
                map.addSource("gpsTrace", {
                    type: "geojson",
                    data: {
                        type: "Feature",
                        geometry: {
                            type: "LineString",
                            coordinates: gpsTraceCoordinates
                        }
                    }
                });

                // Add snapped trace source
                map.addSource("snappedTrace", {
                    type: "geojson",
                    data: featureCollection
                });

                // Add GPS trace layer
                map.addLayer({
                    'id': 'gpsTrace',
                    'type': 'line',
                    'source': 'gpsTrace',
                    layout: {
                        "line-join": "round",
                        "line-cap": "round",
                    },
                    paint: {
                        "line-color": "#00b0ff",
                        "line-width": 8,
                    }
                });

                // Add snapped trace layer
                map.addLayer({
                    'id': 'snappedTrace',
                    'type': 'line',
                    'source': 'snappedTrace',
                    layout: {
                        "line-join": "round",
                        "line-cap": "round",
                    },
                    paint: {
                        "line-color": "#d59a9a",
                        "line-width": 8,
                    }
                });
            });
        }

        // Initialize the map
        initializeMap();
    </script>
</body>
</html>

Opening the HTML file in a browser will show the following map (Figure 10), with the blue line representing a GPS trace, and the red line representing a version that is snapped to roads.

Figure 10 – Map showing a corrected route based on a GPS trace

Cleanup

The only Amazon Location Service resources created during this demonstration was an API Key. To delete the API Key, navigate to the Amazon Location Service Console, select the API Key we created, and select Deactivate. Confirm your decision to deactivate the key, then select Delete. Also select that you would like to bypass the standard 90-day deactivation period.

Conclusion

Amazon Location Service now offers even greater flexibility with the new features. With this update, the previously required resource creation procedure is no longer necessary, and various APIs can be used by setting an API key. This allows users to quickly and smoothly build geospatial applications.

Notable new features include GetStyleDescriptor and GetStaticMap in the Maps API, SearchText and SearchNearby in the Places API, and CalculateIsolines and SnapToRoads in the Routes API.

In the Maps API, GetStyleDescriptor can be used to retrieve various map styles and apply them to your application, and GetStaticMap can generate static map images based on the coordinates and zoom levels you specify. The Places API allows you to search POI data using SearchText, and SearchNearby will enable you to find POIs around a specific location. The Routes API can use CalculateIsolines to calculate reachability from a specified point and SnapToRoads to correct GPS data to obtain accurate route data.

These new features allow application developers to more effectively utilize geospatial data and significantly improve the user experience. Contact an AWS Representative for more information about how we can help accelerate your business.

Building real-time apps with AWS AppSync Events’ WebSocket publishing

Brice Pellé — Thu, 13 Mar 2025 21:04:20 +0000

Real-time features have become essential in modern applications. Whether you’re building collaborative tools, live dashboards, or interactive games, users have come to expect instant and seamless updates as they interact with apps. AWS AppSync Events, a fully-managed service for serverless WebSocket APIs, has been helping developers add real-time capabilities to their applications, enabling them to build responsive and engaging experiences at scale.

Today, I’m excited to announce an enhancement to AWS AppSync Events: the ability to publish messages directly over WebSocket connections, in addition to publishing over the API’s HTTP endpoint. This update allows developers to use a single WebSocket connection for both publishing and receiving events, streamlining the development of real-time features and reducing implementation complexity. This is particularly beneficial for chatty applications that previously faced the overhead of establishing new HTTP connections for each message publication. Developers now have more flexibility: they can publish over HTTP endpoint, e.g.: for publishing from a backend, or publish over WebSocket which might be preferred for web and mobile application clients. In this post, I’ll go over the new enhancement, and show you how you can start integrating publishing over WebSocket in your apps.

Getting started

As I mentioned in my Announcing AWS AppSync Events post, getting started with AppSync Events is simple, and you can now publish over WebSocket or HTTP directly from the console. From the AppSync console, you can create an API and automatically get a default channel namespace along with an API key. on the Pub/Sub Editor, you can immediately try out your API. As shown in the image below, choose the “Publish” button, and in the dropdown, choose “WebSocket”. Your events are published over the WebSocket. You receive a publish_success message confirming the request.

Publishing over WebSocket in the AppSync’s console Pub/Sub editor

Message format

AppSync now supports a new “publish” WebSocket operation to publish events. After connecting to the WebSocket, your client can start publishing events to channels in configured channel namespaces. Note that you do not need to subscribe to a channel before publishing to it. To publish events, you simply create a data message, specify an id that uniquely identifies the message, the channel you are sending the message to, the list of events your are sending (up to 5), and the authorization headers to allow the request. You can find more information about the authorization headers format in the documentation. Each event in the events array must be a valid JSON string. Here’s an example.

{
  "type": "publish",
  "id": "an-identifier-for-this-request",
  "channel": "/namespace/my/path",
  "events": [ "{ \"msg\": \"Hello World!\" }" ],
  "authorization": {
    "x-api-key": "da2-12345678901234567890123456-example",
   }
}

After publishing, you receive a “publish_success” response with details on each event sent, or a “publish_error” response if the operation was not successful.

Integrate with your application

In the previous post, I showed you how to implement a simple client that uses the browser’s Web API WebSocket. I’ll do this again to connect and publish on an Event API WebSocket endpoint. In this example, I’ll build a real-time demo chat application where clients can send and receive messages instantly over WebSocket. Messages are published to the /default/messages channel, and clients subscribe to /default/* to receive all messages in the default namespace.

A demo chat application

I’ll use the new AWS Cloud Development Kit (CDK) L2 constructs for AppSync Events to configure and deploy an AppSync Event API, with a single channel namespace named “default”, and a single API key. Learn more about getting started with AWS CDK. If needed, use the Node Package Manager to install the CDK CLI.

$ npm install -g aws-cdk

I start by initializing a new folder structure and create my CDK application.

$ mkdir -p events-app/cdk-events-publish
$ cd events-app/cdk-events-publish
$ cdk init app --language javascript

Next, I update the lib/cdk-events-publish-stack.js file with this code:

const { Stack, CfnOutput } = require('aws-cdk-lib');
const { EventApi, AppSyncAuthorizationType } = require('aws-cdk-lib/aws-appsync');

class CdkEventsPublishStack extends Stack {
  constructor(scope, id, props) {
    super(scope, id, props);
    const apiKeyProvider = { authorizationType: AppSyncAuthorizationType.API_KEY };

    // create an API called `my-event-api` that uses API Key authorization
    const api = new EventApi(this, 'api', {
      apiName: 'my-event-api',
      authorizationConfig: { authProviders: [apiKeyProvider] }
    });

    // add a channel namespace called `default`
    api.addChannelNamespace('default');

    // output configuration properties
    new CfnOutput(this, 'apiKey', { value: api.apiKeys['Default'].attrApiKey });
    new CfnOutput(this, 'httpDomain', { value: api.httpDns });
    new CfnOutput(this, 'realtimeDomain', { value: api.realtimeDns });
  }
}

module.exports = { CdkEventsPublishStack }

I then deploy the stack and save the output to a JSON file.

$ npm run cdk deploy -- -O output.json

I get output that looks like this:

Outputs:
CdkStack.apiKey = da2-12345678901234567890123456-example
CdkStack.httpDomain = a12345678901234567890123456.appsync-api.us-east-2.amazonaws.com
CdkStack.realtimeDomain = a12345678901234567890123456.appsync-realtime-api.us-east-2.amazonaws.com

Next, I create the web app using vite (a frontend build tool), and vite’s vanilla javascript template. From the events-app folder, I run:

$ npm create vite@latest app -- --template vanilla
$ cd app
$ npm install
$ ln -s ../../cdk-events-publish/output.json src

This creates a link to the output.json file that I can refer to in the app. In the new app folder, I replace src/main.js with the code below. Note that the code uses the CDK output in output.json.

import './style.css'
import output from './output.json'

// use the output from the CDK stack deployment
const HTTP_DOMAIN = output.CdkEventsPublishStack.httpDomain
const REALTIME_DOMAIN = output.CdkEventsPublishStack.realtimeDomain
const API_KEY = output.CdkEventsPublishStack.apiKey 
     
const authorization = { 'x-api-key': API_KEY, host: HTTP_DOMAIN }

document.querySelector('#app').innerHTML = `
    <style>
      #top{width: calc(100vw - 8rem); max-width: 1280px; background: oklch(0.977 0.013 236.62); margin: 2rem 0; height: calc(100vh - 8rem); box-shadow: inset 0 0 20px rgba(0,0,0,0.1); position: relative; margin-inline: auto;}
      #container{display: flex;flex-direction: column;height: calc(100% - 6.5rem);}
      h2{color: oklch(0.3 0.013 236.62); margin-bottom: 1.5em; font-size: 1.8rem;}
      #messages{display: flex; flex-direction: column-reverse; gap: 1em; max-height: calc(100vh - 200px); flex: 1; min-height: 0; overflow-y: auto; text-align: left;}
      form{position: absolute; bottom: 2rem; left: 2rem; right: 2rem; padding: 1rem 0;}
      input{width: 90%; padding: 0.8em 1.2em; border: 1px solid oklch(0.8 0.013 236.62); border-radius: 25px; font-size: 1rem; outline: none; transition: all 0.2s ease; box-shadow: 0 2px 5px rgba(0,0,0,0.05);}
      .msg{padding: 0 1rem; font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace;}
    </style>
    <div id="top">
      <div id="container"><h2>Messages</h2><div id="messages"></div></div>
      <form id="form"> <input id="messageInput" name="message" type="text" autocomplete="off" /></form>
    </div>`

// construct the protocol header for the connection
function getAuthProtocol() {
  const header = btoa(JSON.stringify(authorization))
    .replace(/\+/g, '-') // Convert '+' to '-'
    .replace(/\//g, '_') // Convert '/' to '_'
    .replace(/=+$/, '') // Remove padding `=`
  return `header-${header}`
}

const socket = await new Promise((resolve, reject) => {
  const socket = new WebSocket(`wss://${REALTIME_DOMAIN}/event/realtime`, [
    'aws-appsync-event-ws',
    getAuthProtocol(),
  ])
  socket.onopen = () => resolve(socket)
  socket.onclose = (event) => reject(new Error(event.reason))
  socket.onmessage = (_evt) => {
    const data = JSON.parse(_evt.data)
    // if this is a `data` event, add the content to the list of messages
    if (data.type === 'data') {
      const event = JSON.parse(data.event)
      const div = document.createElement('div')
      div.className = 'msg'
      div.innerHTML = `↑ ${event.time} | ↓ ${new Date().toISOString().split('T')[1]} | ${event.message}`
      messages.prepend(div)
    }
  }
})

// subscribe to `/default/*`
socket.send(
  JSON.stringify({
    type: 'subscribe',
    id: crypto.randomUUID(),
    channel: '/default/*',
    authorization,
  }),
)

const form = document.querySelector('#form')
const messageInput = document.querySelector('#messageInput')
const messages = document.querySelector('#messages')

// when the form is submitted, send an event to `/default/messages`
form.addEventListener('submit', (e) => {
  e.preventDefault()
  const message = new FormData(e.currentTarget).get('message')
  messageInput.value = ''
  socket.send(
    JSON.stringify({
      type: 'publish',
      id: crypto.randomUUID(),
      channel: '/default/messages',
      events: [JSON.stringify({ message, time: new Date().toISOString().split('T')[1] })],
      authorization,
    }),
  )
})

Now in the app directory, I start the web server:

$ npm run dev

I can open the website at the provided address on multiple browsers to send and receive messages.

Cleaning up

When done with the example, I can remove the resources I deployed with CDK.

$ cd ../cdk-events-publish
$ npm run cdk destroy

Conclusion

In this post, I went over the new Publish over WebSocket feature for AWS AppSync Events, and showed how to get started with the feature. This enhancement offers several benefits:

Simplified implementation with a single connection for publishing and subscribing
Reduced connection overhead for chatty applications
Flexibility to choose between WebSocket and HTTP publishing based on your use case

Publishing over WebSocket is now available in all regions where AppSync is available. Clients can publish at a rate of 25 requests per second per client WebSocket connection. You can continue using your API’s HTTP endpoint to publish at higher rates (adjustable default of 10,000 events per second). Visit AppSync’s endpoints and quotas page for more details. We’re excited to see what you build with this new capability. Get started today by trying out the example in this post or by adding WebSocket publishing to your existing AppSync Events applications. To learn more about AppSync Events, visit the documentation.

Amplify Hosting Announces Skew Protection Support

Matt Auerbach — Thu, 13 Mar 2025 19:38:18 +0000

A common challenge in web application development and deployment is version skew between client and server resources. Today, we’re excited to announce deployment skew protection for applications deployed to AWS Amplify Hosting. This feature helps verifies end users have a seamless experience during application deployments.

The Challenge

Modern web applications are complex systems comprising numerous static assets and server-side components that must all work together. In a world where its common to have multiple deployments occur hourly, version compatibility becomes a critical concern. When new deployments occur, users with cached versions of your application may attempt to fetch resources from the updated deployment, potentially resulting in 404 errors and broken functionality.

This challenge is compounded by client-server version skew, which manifests in two common scenarios. First, users often keep browser tabs open for extended periods, continuing to run older versions of your application while attempting to interact with updated backend services. Second, in mobile applications, users with disabled auto-updates may continue using outdated versions indefinitely, requiring backend services to maintain compatibility with multiple client versions simultaneously.

These version management challenges can significantly impact user experience and application reliability if not properly addressed. Consider the scenario:

A user loads your application (version A)
You deploy a new version (version B)
The user’s cached JavaScript tries to load assets that only existed in version A
Result: broken functionality and poor user experience

How skew protection works

Amplify Hosting now intelligently coordinates request resolution across multiple client sessions, ensuring precise routing to intended deployment versions.

1. Smart asset routing

When a request comes in, Amplify Hosting now:

Identifies the deployment version that originated the request
Routes and resolves the request to the identified version of the asset
A hard refresh will always serve the latest deployment assets in a user session

2. Consistent version serving

The system confirms that:

All assets from a single user session come from the same deployment
New user sessions always get the latest version
Existing sessions continue working with their original version until refresh

Advantages to skew protection

Here are some of the advantages of having skew protection:

Zero Configuration: Works out of the box with popular frameworks
Reliable Deployments: Eliminate 404 errors due to deployment skew
Performance Optimized: Minimal impact on response times

Best practices

While skew protection handles most scenarios automatically, we recommend:

Using atomic deployments
Testing your deployment process in a staging environment

Enabling Skew Protection

Skew protection must be enabled for each Amplify app. This is done at the branch level for every Amplify Hosting app. You can read the full Amplify Hosting documentation here.

1. To enable a branch, click on App Settings, then click Branch Settings. Next, select the branch you want to enable followed by the Actions tab.

FIGURE 1 – Amplify Hosting Branch Settings

2. For skew protection to take effect, you must deploy the application once.

Note: Skew protection will not be available to customers using our legacy SSRv1/WEB_DYNAMIC applications.

Pricing: There is no additional cost for this feature and it is available to all Amplify Hosting regions.

Tutorial

To get started, follow these steps to create a Next.js application and enable skew protection on it.

Prerequisites

Before you begin, make sure you have the following installed:

Node.js (v18.x or later)
npm or npx (v10.x or later)
Git (v2.39.5 or later)

Create a Next.js app

Let’s create a Next.js app to see skew protection in action.

Create a new Next.js 15 app with Typescript and Tailwind CSS

$ npx create-next-app@latest skew-protection-demo --typescript --tailwind --eslint
$ cd skew-protection-demo

2. Create a SkewProtectionDemo component that lists fingerprinted assets with deployment IDs. Use the following code to create the component.

Note: Amplify will automatically tag the fingerprinted assets of a NextJS app with a dpl query parameter set to a UUID. This UUID is also available during the build via the AWS_AMPLIFY_DEPLOYMENT_ID environment variable for other frameworks.

// app/components/SkewProtectionDemo.tsx

"use client";

import { useState, useEffect } from "react";
import DeploymentTester from "./DeploymentTester";

interface Asset {
  type: string;
  url: string;
  dpl: string;
}

export default function SkewProtectionDemo() {
  const [fingerprintedAssets, setFingerprintedAssets] = useState<Asset[]>([]);
  const [deploymentId, setDeploymentId] = useState<string>("Unknown");

  // Detect all assets with dpl parameters on initial load
  useEffect(() => {
    detectFingerprintedAssets();
  }, []);

  // Function to detect all assets with dpl parameters
  const detectFingerprintedAssets = () => {
    // Find all assets with dpl parameter (CSS and JS)
    const allElements = [
      ...Array.from(document.querySelectorAll('link[rel="stylesheet"]')),
      ...Array.from(document.querySelectorAll("script[src]"))
    ];
    
    const assets = allElements
      .map(element => {
        const url = element.getAttribute(element.tagName.toLowerCase() === "link" ? "href" : "src");
        if (!url || !url.includes("?dpl=")) return null;

        // Extract the dpl parameter
        let dplParam = "unknown";
        try {
          const urlObj = new URL(url, window.location.origin);
          dplParam = urlObj.searchParams.get("dpl") || "unknown";
        } catch (e) {
          console.error("Error parsing URL:", e);
        }

        return {
          type: element.tagName.toLowerCase() === "link" ? "css" : "js",
          url: url,
          dpl: dplParam,
        };
      })
      .filter(asset => asset !== null);

    setFingerprintedAssets(assets);
    
    // Set deployment ID if assets were found
    if (assets.length > 0) {
      setDeploymentId(assets[0]?.dpl || "Unknown");
    }
  };

  // Function to format URL to highlight the dpl parameter
  const formatUrl = (url: string) => {
    if (!url.includes("?dpl=")) return url;
    
    const [baseUrl, params] = url.split("?");
    const dplParam = params.split("&").find(p => p.startsWith("dpl="));
    
    if (!dplParam) return url;
    
    const otherParams = params.split("&").filter(p => !p.startsWith("dpl=")).join("&");
    
    return (
      <>
        <span className="text-gray-400">{baseUrl}?</span>
        {otherParams && <span className="text-gray-400">{otherParams}&</span>}
        <span className="text-yellow-300 font-bold">{dplParam}</span>
      </>
    );
  };

  return (
    <main className="min-h-screen p-6 bg-white">
      <div className="w-full max-w-2xl mx-auto">
        <h1 className="text-2xl font-bold text-gray-900 mb-6">
          Amplify Skew Protection Demo
        </h1>

        <div className="grid grid-cols-1 gap-4 mb-6">
          <div className="flex items-center p-4 bg-white text-gray-800 rounded-md border border-gray-200 hover:bg-gray-50 transition-colors">
            <div className="w-10 h-10 flex items-center justify-center bg-gray-100 rounded-lg mr-3">
              <span className="text-lg">?</span>
            </div>
            <div>
              <p className="font-medium">Zero-Downtime Deployments</p>
              <p className="text-xs text-gray-600">Assets and API routes remain accessible during deployments using deployment ID-based routing</p>
            </div>
          </div>
          
          <div className="flex items-center p-4 bg-white text-gray-800 rounded-md border border-gray-200 hover:bg-gray-50 transition-colors">
            <div className="w-10 h-10 flex items-center justify-center bg-gray-100 rounded-lg mr-3">
              <span className="text-lg">⚡</span>
            </div>
            <div>
              <p className="font-medium">Built-in Next.js Support</p>
              <p className="text-xs text-gray-600">Automatic asset fingerprinting and deployment ID injection for Next.js applications</p>
            </div>
          </div>
          
          <div className="flex items-center p-4 bg-white text-gray-800 rounded-md border border-gray-200 hover:bg-gray-50 transition-colors">
            <div className="w-10 h-10 flex items-center justify-center bg-gray-100 rounded-lg mr-3">
              <span className="text-lg">?</span>
            </div>
            <div>
              <p className="font-medium">Advanced Security</p>
              <p className="text-xs text-gray-600">Protect against compromised builds by calling the delete-job API to remove affected deployments</p>
            </div>
          </div>
        </div>

        <div className="bg-gradient-to-r from-blue-900 to-purple-900 p-4 rounded-md mb-6">
          <h2 className="text-sm font-medium text-blue-200 mb-1">
            Current Deployment ID
          </h2>
          <div className="p-2 bg-black bg-opacity-30 rounded-md font-mono text-lg text-center text-yellow-300">
            {deploymentId}
          </div>
        </div>

        {fingerprintedAssets.length > 0 ? (
          <>
            <h2 className="text-xl font-bold text-gray-900 mb-6">
              Fingerprinted Assets
            </h2>
            <div className="border border-gray-200 rounded-md overflow-hidden mb-6 bg-white">
              <div className="max-h-48 overflow-y-auto">
                <table className="min-w-full divide-y divide-gray-200">
                  <thead className="bg-gray-50">
                    <tr>
                      <th className="px-3 py-2 text-left text-xs font-medium text-gray-900 uppercase tracking-wider w-16">
                        Type
                      </th>
                      <th className="px-3 py-2 text-left text-xs font-medium text-gray-900 uppercase tracking-wider">
                        URL
                      </th>
                    </tr>
                  </thead>
                  <tbody className="divide-y divide-gray-200">
                    {fingerprintedAssets.map((asset, index) => (
                      <tr key={index} className="bg-white hover:bg-gray-50">
                        <td className="px-3 py-2 text-sm text-gray-900">
                          <span
                            className={`inline-block px-2 py-0.5 rounded-full text-xs ${
                              asset.type === "css"
                                ? "bg-blue-100 text-blue-800"
                                : "bg-yellow-100 text-yellow-800"
                            }`}
                          >
                            {asset.type}
                          </span>
                        </td>
                        <td className="px-3 py-2 text-xs font-mono break-all text-gray-900">
                          {formatUrl(asset.url)}
                        </td>
                      </tr>
                    ))}
                  </tbody>
                </table>
              </div>
            </div>
            
            <h2 className="text-xl font-bold text-gray-900 mb-6">
              Test Deployment Routing
            </h2>
            <DeploymentTester />
          </>
        ) : (
          <div className="p-6 text-center text-gray-600 border border-gray-200 rounded-md">
            <p>No fingerprinted assets detected</p>
            <p className="text-sm mt-2">
              Deploy to Amplify Hosting to see skew protection in action
            </p>
          </div>
        )}
      </div>
    </main>
  );
}

3. Next, create a DeploymentTester component that demonstrates how API requests maintain deployment consistency by sending the X-Amplify-Dpl header with each request, allowing Amplify to route to the correct API version. Use the following code to create the component.

// app/components/DeploymentTester.tsx

'use client';

import { useState } from 'react';

interface ApiResponse {
  message: string;
  timestamp: string;
  version: string;
  deploymentId: string;
}

export default function DeploymentTester() {
  const [testInProgress, setTestInProgress] = useState(false);
  const [testOutput, setTestOutput] = useState<ApiResponse | null>(null);
  const [callCount, setCallCount] = useState(0);

  const runApiTest = async () => {
    setTestInProgress(true);
    setCallCount(prev => prev + 1);
    
    try {
      const response = await fetch('/api/skew-protection', {
        headers: {
        // Amplify provides the deployment ID as an environment variable during build time
          'X-Amplify-Dpl': process.env.AWS_AMPLIFY_DEPLOYMENT_ID || '',
        }
      });
      
      if (!response.ok) {
        throw new Error(`API returned ${response.status}`);
      }
      const data = await response.json();
      setTestOutput(data);
    } catch (error) {
      console.error("API call failed", error);
      setTestOutput({
        message: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`,
        timestamp: new Date().toISOString(),
        version: 'error',
        deploymentId: 'error'
      });
    } finally {
      setTestInProgress(false);
    }
  };

  return (
    <div className="border border-gray-200 rounded-md overflow-hidden bg-white">
      <div className="bg-gray-50 px-4 py-3 flex justify-between items-center border-b border-gray-200">
        <span className="font-medium text-gray-800">Test Deployment Routing</span>
        <button
          onClick={runApiTest}
          disabled={testInProgress}
          className={`px-3 py-1 rounded text-sm ${
            testInProgress
              ? 'bg-gray-200 text-gray-500 cursor-not-allowed'
              : 'bg-blue-600 hover:bg-blue-700 text-white'
          }`}
        >
          {testInProgress ? "Testing..." : "Test Route"}
        </button>
      </div>
      
      <div className="p-4">
        {testOutput ? (
          <div className="p-3 bg-gray-50 rounded border border-gray-200 font-mono text-sm">
            <div className="text-green-600 mb-2">{testOutput.message}</div>
            <div className="text-gray-600 text-xs space-y-1">
              <div>API Version: <span className="text-blue-600 font-medium">{testOutput.version}</span></div>
              <div>Deployment ID: <span className="text-purple-600 font-medium">{testOutput.deploymentId}</span></div>
              <div>Call #: {callCount}</div>
              <div>Time: {new Date(testOutput.timestamp).toLocaleTimeString()}</div>
            </div>
          </div>
        ) : testInProgress ? (
          <div className="p-3 bg-gray-50 rounded border border-gray-200 text-sm text-gray-600">
            Testing deployment routing...
          </div>
        ) : (
          <div className="p-3 bg-gray-50 rounded border border-gray-200 text-sm text-gray-600">
            Click &quot;Test Route&quot; to verify how requests are routed to the correct deployment version
          </div>
        )}
      </div>
    </div>
  );
}

4. Now create an API route that uses the X-Amplify-Dpl header to identify which deployment the request is coming from, simulating how Amplify routes API requests to maintain version consistency during deployments. Use the following code to create the API route:

// app/api/skew-protection/route.ts
import { NextResponse } from 'next/server';
import { type NextRequest } from 'next/server';

// This version identifier can be changed between deployments to demonstrate skew protection
const CURRENT_API_VERSION = "v2.0";

export async function GET(request: NextRequest) {
  // Get the deployment ID from the X-Amplify-Dpl header
  // This is how Amplify routes API requests to the correct deployment version
  const deploymentId = request.headers.get('x-amplify-dpl') || '';
  
  // Determine which version to serve based on deployment ID
  const apiVersion = CURRENT_API_VERSION;
  const message = `Hello from API ${apiVersion}! ?`;
  
  // Return the response with deployment information
  return NextResponse.json({
    message,
    version: apiVersion,
    deploymentId: deploymentId || 'none',
    timestamp: new Date().toISOString()
  });
}

5. Add the Amplify deployment ID environment variable to make it accessible to client code

// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  env: {
    AWS_AMPLIFY_DEPLOYMENT_ID: process.env.AWS_AMPLIFY_DEPLOYMENT_ID || '',
  }
};
export default nextConfig;

6. Push the changes to a GitHub repository

Create a new GitHub repository
Add and commit the changes to the Git branch
Add remote origin and push the changes upstream

git add .
git commit -m "initial commit"
git remote add origin https://github.com/<OWNER>/amplify-skew-protection-demo.git
git push -u origin main

Deploy the application to Amplify Hosting

Use the following steps to deploy your newly constructed application to AWS Amplify Hosting:

Sign in to the AWS Amplify console.
Choose Create new app and select GitHub as the repository source
Authorize Amplify to access your GitHub account
Choose the repository and branch you created
Review the App settings and then choose Next
Review the overall settings and choose Save and deploy

Enable skew protection

In the Amplify console, navigate to App settings and then Branch settings. Select the Branch, and from the Actions dropdown menu choose Enable skew protection.

FIGURE 2 – Amplify Hosting Branch Settings

Next, navigate to the deployments page and redeploy your application. When skew protection is enabled for an application, AWS Amplify must update its CDN cache conﬁguration. Therefore, you should expect your ﬁrst deployment after enabling skew protection to take up to ten minutes.

FIGURE 3 – Amplify Hosting App Deployments

Access the deployed Next.js app

Navigate to the Overview tab in the Amplify console and open the default Amplify generated URL in the browser. You should now observe a list of fingerprinted assets for your app along with the deployment ID.

FIGURE 4 – Amplify Hosting App Settings – Branch level

FIGURE 5 – Demo App Homepage

Testing skew protection

When you deploy your Next.js application to Amplify, each deployment gets assigned a unique deployment ID. This ID is automatically injected into your static assets (JS, CSS) and API routes to ensure version consistency. Let’s see it in action:

Asset Fingerprinting: Notice how each static asset URL includes a ?dpl= parameter with your current deployment ID. This ensures browsers always fetch the correct version of your assets.
API Routing: The Test Route button demonstrates how Amplify routes API requests. When clicked, it makes a request to the /api/skew-protection endpoint. Since the request utilizes the X-Amplify-Dpl header to match your current deployment ID, it ensures routing to the correct API version.

This means that even during deployments, your users won’t experience version mismatches and each user’s session stays consistent with the version they initially loaded, preventing bugs that could occur when client and server versions don’t match.

Try it yourself

Keep your current browser tab open and click Test Route to see the API version and deployment ID match.
Deploy a new version with a different CURRENT_API_VERSION in api/skew-protection/route.ts
Open your application in a new incognito window
1. Compare the behavior:
  - - Your original tab will maintain the old version
    - The new incognito window will show the new version
    - Each tab’s assets and API calls will consistently match their respective versions
    - Try clicking Test Route repeatedly in both windows – each will consistently route to its respective version, demonstrating how Amplify maintains session consistency even when multiple versions are live

FIGURE 6 -Side by Side Comparison of Skew Protection Behavior

This demonstrates how Amplify maintains version consistency for each user session, even when multiple versions of your application are running during deployments.

Congratulations, you’ve successfully created and verified skew protection on your Next.js application deployments on Amplify Hosting.

Cleanup

Delete the AWS Amplify app by navigating to App settings, next go to General settings, then choose Delete app.

Next Steps

Enable Skew Protection for your application.
Read our documentation to learn more about this feature!

About the Authors

Matt Auerbach, Senior Product Manager, Amplify Hosting

Jay Raval, Solutions Architect, Amplify Hosting

Jay Raval is a Solutions Architect on the AWS Amplify team. He’s passionate about solving complex customer problems in the front-end, web and mobile domain and addresses real-world architecture problems for development using front-end technologies and AWS. In his free time, he enjoys traveling and sports. You can find Jay on X @_Jay_Raval_

Simplifying Multi-App Management in AWS Amplify Hosting

Matt Auerbach — Mon, 10 Mar 2025 20:09:13 +0000

AWS Amplify Hosting has now made it possible to connect many more Amplify apps to a single repository. This change improves the way developers can integrate with Git providers which is especially beneficial for monorepo architectures. Amplify now uses a single webhook per repository for all associated apps, streamlining the development workflow. For specific limit details, please refer to our documentation.

Previously, Amplify users were constrained by the webhook limits provided by Git providers. As Amplify created a new webhook for each app associated with a repository, users with multiple Amplify apps linked to a single repository could reach these limits quickily, preventing them from adding more apps. This was particularly challenging for teams working with monorepos, where multiple projects (and thus, multiple Amplify apps) exist within a single repository.

While the specific number of webhooks allowed varies by Git provider, these limits presented an obstacle for teams looking to scale their projects or work with complex repository structures.

GitHub has a webhook limit of 20
GitLab has webhook limit of 100
BitBucket has webhook limit of 50

Unified Webhooks

Unified webhooks solve this pain point by consolidating all Amplify-related webhooks into a single, comprehensive webhook for your repository. This approach simplifies repository management while ensuring that all associated Amplify apps receive updates and triggers without being constrained by webhook restrictions.

Key Benefits

Overcome Git Provider Limitations: Remove current webhook constraints, allowing you to connect as many Amplify apps as needed to a single repository.
Enhanced Monorepo Support: Gain more flexibility and efficiency when working with monorepo structures, where multiple projects share a single repository.
Simplified Management: Manage multiple Amplify apps with a single repository webhook, reducing complexity and potential points of failure.
Improved Workflow Integration: Free up webhook slots for other essential workflows in your development process.

Getting Started with Unified Webhooks

For New Apps
Deploy a web app with Amplify Hosting. The unified webhook feature will be automatically implemented for your repository.

For Existing Amplify Users
To take advantage of this new feature, you’ll need to reconnect your repository to your Amplify app. Here’s how:

Navigate to your Amplify app in the AWS Management Console.
Locate the repository settings for your app.
Click on the “Reconnect” button next to your repository information.
Confirm the action to replace existing webhooks with the new unified webhook.

Walkthrough

Here is an example of a current repository with two Amplify apps switching to use the new unified webhook.

Each webhook looks like

Then go to your Amplify Console, find the Reconnect Repository button in App settings → Branch settings

Click the Configure GitHub App and Complete installation

After a few moments, you will see the repository is switched to the unified webhook.

You are all set now. Any new amplify app connected to this repository will use the same unified webhook here.

Important Considerations

Webhook Limit During Migration: If you’ve already reached the maximum number of webhooks allowed by your Git provider, the automatic migration may not work. In this case, you might need to manually remove at least one existing webhook before reconnecting.

Regional Operations: All operations, including the webhook migration, are region-based. This means the migration will only occur for the regional webhooks where you reconnect your Amplify app.

Conclusion

The introduction of unified webhooks in AWS Amplify Hosting simplifies repository management and enhances support for complex project structures like monorepos. By reducing webhook overhead and streamlining the connection between your git repository and Amplify apps, we’re enabling developers to focus more on building great applications and less on managing infrastructure limitations.

We’re excited to see how this feature will improve your development workflow, especially for those working with large, complex repositories. Deploy your Next.js, Nuxt, React, Angular, Vue, or other frontend apps in the Amplify Console, and join our community on Discord to share your thoughts and experiences!

About the Authors

Matt Auerbach, Senior Product Manager, Amplify Hosting

Matt Auerbach is a NYC-based Product Manager on the AWS Amplify Team. He educates developers regarding products and offerings, and acts as the primary point of contact for assistance and feedback. Matt is a mild-mannered programmer who enjoys using technology to solve problems and making people’s lives easier. B night, however…well he does pretty much the same thing. You can find Matt on Twitter @mauerbac. He previously worked in Developer Relations at Twitch, Optimizely & Twilio.

Linsong Wang, Software Development Engineer, Amplify Hosting

Linsong builds features that make it easier for customers to host front-end web applications backed by the reliability and convenience of AWS. In his free time, Linsong enjoys exploring cooking recipes, playing piano, and building life improvement prototype

IAM Compute Roles for Server-Side Rendering with AWS Amplify Hosting

Jay Raval — Tue, 18 Feb 2025 21:17:34 +0000

Today, AWS Amplify Hosting is introducing compute roles for AWS Amplify applications, enabling you to extend server-side rendering capabilities with secure access to AWS services from the compute runtime. With compute roles, developers can attach specific permissions to their server-side rendered apps, allowing Amplify to make authorized calls to other AWS services. This new capability helps streamline the development process while maintaining security best practices for your applications.

Key capabilities

With compute roles, you can now:

Access sensitive configuration data at runtime within Next.js API routes using AWS Secrets Manager and AWS Systems Manager Parameter Store
Connect your SSR apps directly to databases like Amazon RDS, Amazon DynamoDB. and other AWS databases
Define fine-grained permissions for your compute environment using AWS Identity and Access Management (IAM) policies
Make secure, authenticated calls to any AWS service from your server-side code

Tutorial

To get started, follow these steps to create an IAM compute role and associate it with an Amplify Next.js application:

Prerequisites

Before you begin, make sure you have the following installed:

Node.js (v18.x or later)
npm or npx (v10.x or later)
git (v2.39.5 or later)
AWS CLI

Create an IAM compute role

Let’s create an IAM role that allows Amplify Hosting’s SSR compute service to securely access AWS resources based on the role’s permission and trust relationship. In our example, we’ll securely access an Amazon Simple Storage Service (Amazon S3) bucket.

Sign in to the AWS Management console and navigate to the IAM console
Under the Access Management tab, choose Roles, then select Create role
Select Custom trust policy and enter the following policy to allow Amplify to assume the role:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": [
                    "amplify.amazonaws.com"
                ]
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

Add the AWS managed AmazonS3ReadOnlyAccess permission policy to the role and choose Next
Name the role amplify-compute-role and choose Create role

You have successfully created a compute role that Amplify can assume to connect to other AWS services.

Security Best Practice: Implement the principle of least privilege by granting only essential permissions for your specific use case.

Create an Amazon S3 bucket

We will now setup a private Amazon S3 bucket that the Next.js app can securely access using the compute role. Instead of exposing Amazon S3 objects publicly or managing access keys, we’ll use Amplify Hosting’s compute role to securely retrieve private content from Amazon S3.

Sign in to the AWS Management console and navigate to the Amazon S3 console
Choose Create bucket and enter a unique bucket name
Keep ACLs disabled and Block all public access enabled

Keep the default settings and choose Create bucket
Navigate to the bucket and choose Upload
Upload an image (e.g. amplify-logo.png)

Security Verification: To confirm that your S3 bucket is completely locked down, run the following get-public-access-block AWS CLI command:

// Note: Replace amplify-compute-role-demo with your specific bucket name
aws s3api get-public-access-block --bucket amplify-compute-role-demo

The expected output should show:

{
    "PublicAccessBlockConfiguration": {
        "BlockPublicAcls": true,
        "IgnorePublicAcls": true,
        "BlockPublicPolicy": true,
        "RestrictPublicBuckets": true
    }
}

These settings ensure:

No public ACLs can be created
Existing public ACLs are ignored
Public bucket policies are blocked
Public access to the bucket is restricted

Create a Next.js app

Next, we will create a Next.js app to securely access private content (an image) from an Amazon S3 bucket using an API route.

Create a new Next.js 15 app with Typescript and Tailwind CSS

npx create-next-app@latest compute-role-demo --typescript --tailwind --eslint
cd compute-role-demo

Install the AWS SDK for JavaScript S3 Client package:

npm install @aws-sdk/client-s3

Create an Amazon S3 Image API route:

// app/api/image/route.ts

import { S3Client, GetObjectCommand, S3ServiceException } from "@aws-sdk/client-s3";
import { NextResponse } from 'next/server';

const BUCKET_NAME = 'amplify-compute-role-demo';
const IMAGE_KEY = 'amplify-logo.png';

export async function GET() {
  console.log(`[S3 Image Request] Starting - Bucket: ${BUCKET_NAME}, Key: ${IMAGE_KEY}`);
  const s3Client = new S3Client({});
  
  try {
    console.log('[S3 Image Request] Creating GetObjectCommand...');
    const command = new GetObjectCommand({
      Bucket: BUCKET_NAME,
      Key: IMAGE_KEY
    });

    console.log('[S3 Image Request] Sending request to S3...');
    const response = await s3Client.send(command);
    console.log('[S3 Image Request] Received S3 response:', {
      contentType: response.ContentType,
      contentLength: response.ContentLength,
      metadata: response.Metadata
    });

    console.log('[S3 Image Request] Converting response to byte array...');
    const buffer = await response.Body?.transformToByteArray();

    if (!buffer) {
      console.error('[S3 Image Request] No buffer received from S3');
      throw new Error('No image data received from S3');
    }

    console.log('[S3 Image Request] Successfully processed image:', {
      bufferSize: buffer.length,
      contentType: response.ContentType
    });

    return new NextResponse(buffer, {
      headers: {
        'Content-Type': response.ContentType || 'image/png',
        'Cache-Control': 'public, max-age=31536000, immutable'
      }
    });

  } catch (error) {
    if (error instanceof S3ServiceException) {
      console.error('[S3 Image Request] AWS S3 Error:', {
        message: error.message,
        code: error.name,
        requestId: error.$metadata?.requestId,
        statusCode: error.$metadata?.httpStatusCode
      });
    } else {
      console.error('[S3 Image Request] Unexpected error:', error);
    }

    return NextResponse.json({
      success: false,
      error: 'Failed to load content'
    }, { 
      status: 500 
    });
  } finally {
    console.log('[S3 Image Request] Request completed');
  }
}

Create a client component:

// app/components/S3Component.tsx

'use client';

import { useState } from 'react';
import Image from 'next/image';

export default function S3Component() {
  const [imageError, setImageError] = useState(false);
  const [isRevealed, setIsRevealed] = useState(false);

  return (
    <div className="absolute inset-0 top-[88px] flex items-center justify-center">
      <div className="w-full max-w-2xl rounded-2xl mx-4">
        <div className="flex flex-col items-center justify-center min-h-[400px] p-8">
          {!isRevealed ? (
            <button
              onClick={() => setIsRevealed(true)}
              className="px-8 py-4 bg-[rgb(117,81,194)] text-white text-lg rounded-xl 
                       hover:bg-[rgb(107,71,184)] transition-colors"
            >
              <span className="flex items-center gap-2">
                Access Private S3 Bucket
                <span className="text-xl">⚡</span>
              </span>
            </button>
          ) : (
            <div className="space-y-8 w-full">              
              {!imageError && (
                <div className="relative h-64 w-full">
                  <Image 
                    src="/api/image"
                    alt="Amplify Logo"
                    fill
                    unoptimized
                    priority
                    onError={() => setImageError(true)}
                    className="object-contain"
                    sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
                  />
                </div>
              )}
              
              <div className="text-center">
                <p className="text-gray-400 text-sm">
                  This content is securely served from S3 using an IAM Compute Role.
                </p>
              </div>
            </div>
          )}
        </div>
      </div>
    </div>
  );
}

Update the home page to render the client component:

import S3Component from './components/S3Component';

export default function HomePage() {
  return (
    <div className="relative min-h-screen bg-[rgb(0,0,0)]">
      <h1 className="text-2xl font-bold text-white py-8 text-center relative z-10">
        Amplify Hosting Compute Role Demo
      </h1>
      <S3Component />
    </div>
  );
}

Push the changes to a git repository:
1. Create a new GitHub repository
2. Add and commit the changes to the git branch
3. Add remote origin and push the changes upstream

git add .
git commit -m "initial commit"
git remote add origin https://github.com/<OWNER>/amplify-compute-role-demo.git
git push -u origin main

Deploy the application to Amplify Hosting

Sign in to the AWS Management Console and navigate to the Amplify console
Choose Create new app and select GitHub as the repository source
Authorize Amplify to access your GitHub account
Choose the repository and branch you created
Review the App settings and then choose Next
Review the overall settings and choose Save and deploy

Attaching the IAM compute role to an Amplify app

In the Amplify console, select your app and navigate to App settings > IAM roles

Choose Edit in the compute role section

From the role menu, select the amplify-compute-role and choose Save
You can also add branch overrides to use a unique compute role per branch. This can particularly be helpful across different git environments such as dev, staging, or production.

Access the deployed Next.js app

Navigate to the app’s Overview tab in the Amplify console and open the default Amplify generated URL in the browser.

Next, choose the Access Private S3 button. You should now observe the image that was uploaded to the Amazon S3 bucket.

Review the hosting compute logs

From the App home page, navigate to Hosting > Monitoring and then choose the Hosting compute logs tab.

Navigate to the Amazon CloudWatch log streams URL and review the latest log stream. The logs should contain the Amazon S3 image requests:

Congratulations! You’ve successfully created and attached an IAM compute role to your Next.js SSR application on Amplify Hosting, enabling secure content retrieval from your private Amazon S3 bucket! ?

Cleanup

Delete the AWS Amplify app by navigating to App settings > General settings, then choose Delete app.
Delete the Amazon S3 bucket by navigating to S3 console > Select bucket > Select Delete > Enter the bucket name to confirm deletion
Delete the IAM role by navigating to IAM console > Select Roles > Find the amplify-compute-role name > Select Delete > Enter the role name to confirm deletion

Summary

AWS Amplify Hosting now offers compute roles for server-side rendered (SSR) applications, solving the challenge of securely accessing AWS services. Previously, developers manually managed credentials through environment variables. Now, with compute roles, developers can directly attach IAM permissions to their SSR apps, simplifying service integration and enhancing security.

Add compute roles to your SSR apps today by checking out the Amplify documentation.

About the Authors

Build a Scalable Search Solution with AWS Amplify and OpenSearch Serverless

Anil Maktala — Fri, 31 Jan 2025 21:40:00 +0000

Introduction

In today’s data-driven digital ecosystem, building scalable search solutions has become essential for organizations managing large, complex datasets across industries. Whether it’s a streaming platform, an e-commerce marketplace, or a research database, the ability to efficiently search through structured and unstructured data is key to delivering a seamless user experience. Traditional search solutions often involve complex data transformation processes and managing dedicated search clusters, which can increase operational costs and complexity.

By leveraging AWS Amplify, Amazon OpenSearch, and Amazon DynamoDB with Zero ETL, you can build scalable, cost-effective, and serverless search solutions. This approach simplifies infrastructure management, reduces costs, and ensures a seamless user experience even under fluctuating traffic.

In this post, we’ll demonstrate how to create a movie search solution using AWS Amplify and Amazon OpenSearch. This solution will provide search capabilities, allowing users to quickly find relevant movie information. We’ll use AWS Amplify’s streamlined development experience and Amazon OpenSearch’s to build this solution.

Figure 1: Movie Search Solution

Prerequisites

AWS account: Required to access and deploy AWS services. Note that Amplify is part of the AWS Free Tier.
Node.js v18.17+ and npm v9+.
Git v2.14.1+: For version control and repository management.
Text Editor (VSCode recommended): Provides an integrated development environment.

High Level Architecture

Our serverless search solution combines several AWS services:

AWS Amplify: Provides a modern development framework for building cloud-based applications.
Amazon OpenSearch: Service: Powers the search functionality with advanced search capabilities.
Amazon DynamoDB: Acts as the primary data store for the application.
Amazon DynamoDB Zero ETL: Streamlines the data ingestion process from DynamoDB to OpenSearch Service.
Amazon S3: The S3 bucket will be used for the initial export, which OpenSearch Ingestion will retrieve data from at the beginning.

High-level architecture diagram showing the integration of AWS Amplify, Amazon DynamoDB, Amazon OpenSearch Serverless, and Amazon S3 in a serverless search solution. The diagram illustrates data flow between services, highlighting how DynamoDB Zero ETL synchronizes data with OpenSearch through an S3 staging area.

Figure 2: Architecture Diagram of the Movie Search Solution

How It Works:

Use the AWS Amplify-powered frontend to submit search queries, which Amazon OpenSearch processes against pre-indexed data. Amazon DynamoDB serves as the primary data store, capturing and updating application data in real time. The Zero ETL feature automatically synchronizes this data with OpenSearch, enabling instant indexing of your latest information.
Amazon S3 serves as an initial staging area during the first data transfer between Dynamo db and OpenSearch. This architecture ensures a responsive, low-latency search experience, providing users with accurate and relevant results while maintaining high scalability and performance.

Implementation Steps

Step 1: Repository Setup

Navigate to the amplify-opensearch-serverless-integration repository on AWS Samples and fork it to your GitHub repositories.

Clone the app by running the command below in your terminal

git clone https://github.com/<YOUR_GITHUB>/amplify-opensearch-serverless-integration.git

Access the newly cloned repository in VSCode by executing the commands below in your terminal.
```
cd amplify-opensearch-serverless-integration
code .
```
VSCode will open the repository folder, including the Amplify folder, which contains the backend details that we’ll discuss in the next section.
1. Project Structure Overview: The structure includes folders like amplify, backend, data, and storage, with key configuration files like backend.ts, resource.ts, and searchMovieResolver.js visible.
  
  Figure 3: Project Structure Overview in Visual Studio Code
Run the following command at the project root in the terminal to install the necessary packages, including the Amplify packages.

npm install

Step 2: Amplify Backend Configuration

In the final application, users can search for movies by entering a title and clicking the search button to retrieve results from Amazon OpenSearch. The code for this functionality is included in the repository you cloned. In this section, we’ll walk through the key steps to integrate your Amplify app with Amazon OpenSearch.

2.1 Define Data Model

Firstly, go to the amplify/data/resource.ts file and add the Movie model to your schema.


import { type ClientSchema, a, defineData } from "@aws-amplify/backend";

const schema = a.schema({
  Movie: a.model({
    title: a.string().required(),
    description: a.string(),
    releaseYear: a.integer(),
    director: a.string(),
    actors: a.string().array(),
    genre: a.string(),
    rating: a.float(),
  }).authorization((allow)=>[allow.owner(), allow.publicApiKey()]),
});

export type Schema = ClientSchema<typeof schema>;

export const data = defineData({
  schema,
  authorizationModes: {
    defaultAuthorizationMode: "userPool",
  },
});

Important considerations:

To ensure smooth data integration between Amazon DynamoDB and Amazon OpenSearch, you’ll need to configure two critical features:

Point-in-Time Recovery (PITR) PITR allows you to:
1. Restore your table to any point in the last 35 days.
2. Capture continuous backups of your data.
3. Enable reliable data recovery and synchronization.
DynamoDB Streams DynamoDB Streams provide:
1. Real-time tracking of data modifications.
2. Capture of all item-level changes.
3. Essential support for streaming data to OpenSearch.

Navigate to your amplify/backend.ts file and add the following configuration:

// amplify/backend.ts
import * as dynamodb from "aws-cdk-lib/aws-dynamodb";
import { defineBackend } from "@aws-amplify/backend";
import { auth } from "./auth/resource";
import { data } from "./data/resource";


const backend = defineBackend({
  auth,
  data,
});

// Get reference to the Movie table from Amplify resources
const movieTable =
  backend.data.resources.cfnResources.amplifyDynamoDbTables["Movie"];
// Enable Point-in-Time Recovery (PITR)  
movieTable.pointInTimeRecoveryEnabled = true;
// Configure DynamoDB Streams
movieTable.streamSpecification = {
  streamViewType: dynamodb.StreamViewType.NEW_IMAGE,
};

Step 3: OpenSearch Serverless collection Setup

In your code go to amplify/backend.ts file, create an Amazon OpenSearch serverless collection.

// amplify/backend.ts
import * as oss from "aws-cdk-lib/aws-opensearchserverless";
import { RemovalPolicy,Stack } from "aws-cdk-lib";

// Get the data stack
const openSearchStack = Stack.of(backend.data);
const region = openSearchStack.region;
const collectionName = "dynamodb-etl-collection";
const openSearchServerlessCollection = new oss.CfnCollection(
  openSearchStack,
  "OpenSearchServerlessCollection",
  {
    name: collectionName,
    description: "DynamoDB to OpenSearch Pipeline ETL Integration.",
    type: "SEARCH",
  }
);
// set removalPolicy to DESTROY to make sure the OpenSearch collection is deleted on stack deletion.
openSearchServerlessCollection.applyRemovalPolicy(RemovalPolicy.DESTROY);

3.1 Add OpenSearch as HttpDatasource to backend

To add the OpenSearch data source, add this code to amplify/backend.ts.

// amplify/backend.ts
/**
 * Create OpenSearch Serverless Data Source
 * This configures the OpenSearch endpoint as an HTTP data source for API operations
 */
const openSearchDataSource = backend.data.addHttpDataSource(
  "OpenSearchServerlessDataSource",
  openSearchServerlessCollection.attrCollectionEndpoint,
  {
    authorizationConfig: {
      // Region where the OpenSearch collection exists
      signingRegion: region,
      
      // Service name for request signing (aoss = Amazon OpenSearch Serverless)
      signingServiceName: "aoss",
    },
  }
);

/**
 * Configure Data Source IAM Permissions
 * Grants necessary permissions for OpenSearch operations using IAM policies
 */
openSearchDataSource.grantPrincipal.addToPrincipalPolicy(
  new iam.PolicyStatement({
    effect: iam.Effect.ALLOW,
    actions: ["aoss:APIAccessAll"],
    resources: [
      // Grant access to the specific collection
      openSearchServerlessCollection.attrArn,
      // Grant access to all indices within the collection
      `${openSearchServerlessCollection.attrArn}/*`,
    ],
  })
);

const httpDataSourceRole = openSearchDataSource.grantPrincipal as iam.Role;
const httpDataSourceRoleArn = httpDataSourceRole.roleArn;

Step 4: Zero ETL Integration

4.1 Storage Configuration

Establish Storage to back up raw events consumed by the Amazon OpenSearch pipeline. Generate a file named amplify/storage/resource.ts and insert the provided content to set up a storage resource. Tailor your storage configurations to regulate access to different paths within your storage bucket.

// amplify/storage/resource.ts 
import { defineStorage } from "@aws-amplify/backend";

export const storage = defineStorage({
  name: "opensearchserverless",
});

In your amplify/backend.ts file, get the s3BucketArn value from storage resource as shown below. Additionally, configure an IAM role for the pipeline and assign the roles as indicated below. For further information on the required IAM roles, please refer to the Setting up roles and users documentation.

// amplify/backend.ts
import { storage } from "./storage/resource";

//Update backend variable by passing storage
const backend = defineBackend({
  auth,
  data,
  storage,
});

// Get the S3Bucket ARN
const s3BucketArn = backend.storage.resources.bucket.bucketArn;

For the Amazon S3 bucket, adhere to standard security practices: block public access, encrypt data at rest, and enable versioning. Note that versioning is enabled by default in Amplify.

4.2 IAM Role Configuration

Understanding IAM Role Setup

In this section, you’ll configure the security permissions that allow your OpenSearch Ingestion Service (OSIS) to securely access and transfer data between different AWS services. Navigate to your amplify/backend.ts file and add the following configuration:

Key Security Objectives:

Grant precise access to OpenSearch.
Secure DynamoDB and S3 data transfers.
Follow the principle of least privilege.

4.2.1 DynamoDB Policies

4.2.1.1 Export Job Policy

Grants permissions to describe tables, check backups, and initiate exports.

// amplify/backend.ts
const tableName = backend.data.resources.tables["Movie"].tableName;
const tableArn = backend.data.resources.tables["Movie"].tableArn;

// Create base role with OpenSearch Ingestion managed policy
const openSearchIntegrationPipelineRole = new iam.Role(
  openSearchStack,
  "OpenSearchIntegrationPipelineRole",
  {
    assumedBy: new iam.ServicePrincipal("osis-pipelines.amazonaws.com"),
    managedPolicies: [
      iam.ManagedPolicy.fromAwsManagedPolicyName(
        "AmazonOpenSearchIngestionFullAccess"
      ),
    ],
  }
);

/**
 * Policy for DynamoDB export operations
 * Allows:
 * - Describing table configuration
 * - Checking backup capabilities
 * - Initiating table exports
 */
const dynamoDBExportJobPolicy = new iam.PolicyStatement({
  sid: "allowRunExportJob",
  effect: iam.Effect.ALLOW,
  actions: [
    // Required for getting table metadata before export
    "dynamodb:DescribeTable",
    // Required for verifying point-in-time recovery status
    "dynamodb:DescribeContinuousBackups",
    // Required for initiating table export operation
    "dynamodb:ExportTableToPointInTime",
  ],
  resources: [tableArn],
});

openSearchIntegrationPipelineRole.addToPolicy(dynamoDBExportJobPolicy);

4.2.1.2 Export Job Monitoring Policy

Allows tracking of export job status using wildcard permissions for dynamic export IDs.

// amplify/backend.ts
import * as iam from "aws-cdk-lib/aws-iam";

/**
 * Policy for monitoring export job status
 * Allows:
 * - Checking status of ongoing export operations
 * - Monitoring export progress
 * Note: Uses wildcard for export operations as export IDs are dynamically generated
 */
const dynamoDBExportCheckPolicy = new iam.PolicyStatement({
  sid: "allowCheckExportjob",
  effect: iam.Effect.ALLOW,
  actions: ["dynamodb:DescribeExport"],
  resources: [`${tableArn}/export/*`],
});

openSearchIntegrationPipelineRole.addToPolicy(dynamoDBExportCheckPolicy);

4.2.1.3 Stream Access Policy

Provides real-time synchronization by granting permissions to read stream data and manage iterators.

// amplify/backend.ts
/**
 * Policy for DynamoDB Stream operations
 * Allows:
 * - Reading stream metadata
 * - Accessing stream records
 * - Managing stream iterators
 * Required for real-time data synchronization
 */
const dynamoDBStreamPolicy = new iam.PolicyStatement({
  sid: "allowReadFromStream",
  effect: iam.Effect.ALLOW,
  actions: [
    // Required for getting stream metadata
    "dynamodb:DescribeStream",
    // Required for reading actual records from the stream
    "dynamodb:GetRecords",
    // Required for managing stream position
    "dynamodb:GetShardIterator",
  ],
  resources: [`${tableArn}/stream/*`],
});

openSearchIntegrationPipelineRole.addToPolicy(dynamoDBStreamPolicy);

4.2.2 S3 Policy for Export Operations

Grants permissions for reading and writing data to an S3 bucket during DynamoDB exports.

// amplify/backend.ts
/**
 * Policy for S3 operations during export
 * Allows:
 * - Reading exported data
 * - Writing export files
 * - Managing multipart uploads
 * - Setting object ACLs
 * Scoped to specific export path for security
 */
const s3ExportPolicy = new iam.PolicyStatement({
  sid: "allowReadAndWriteToS3ForExport",
  effect: iam.Effect.ALLOW,
  actions: [
    // Required for reading exported data
    "s3:GetObject",
    // Required for handling failed uploads
    "s3:AbortMultipartUpload",
    // Required for writing export files
    "s3:PutObject",
    // Required for setting object permissions
    "s3:PutObjectAcl",
  ],
  resources: [`${s3BucketArn}`,`${s3BucketArn}/${tableName}/*`],
});
openSearchIntegrationPipelineRole.addToPolicy(s3ExportPolicy);

4.2.3 OpenSearch Policies

4.2.3.1 OpenSearch Collection Policy

Enables indexing, querying, and managing OpenSearch collections.

// amplify/backend.ts
/**
 * Policy for OpenSearch domain access
 * Allows:
 * - HTTP operations for indexing and querying
 * - Domain management operations
 * Includes permissions for both domain-level and index-level operations
 */
const openSearchCollectionPolicy = new iam.PolicyStatement({
  sid: "allowOpenSearchAccess",
  effect: iam.Effect.ALLOW,
  actions: [
    // Allows batch retrieval of collection information
    "aoss:BatchGetCollection",
    // Required for search, index, and administrative operations
    "aoss:APIAccessAll",
    // Needed for encryption and network policy validation
    "aoss:GetSecurityPolicy",
    // Required for initial setup and scaling operations
    "aoss:CreateCollection",
    // Needed for collection discovery and management
    "aoss:ListCollections",
    // Required for updating collection settings and configurations
    "aoss:UpdateCollection",
    // Needed for cleanup and resource management
    "aoss:DeleteCollection",
  ],
  resources: [
    openSearchServerlessCollection.attrArn,
    `${openSearchServerlessCollection.attrArn}/*`,
    `arn:aws:aoss:${region}:${openSearchStack.account}:collection/*`,
  ],
});
openSearchIntegrationPipelineRole.addToPolicy(openSearchCollectionPolicy);

4.2.3.2 Encryption Policy

Defines encryption settings for OpenSearch Serverless collections.

// amplify/backend.ts

import * as oss from "aws-cdk-lib/aws-opensearchserverless";

/**
 * Create Encryption Policy for OpenSearch Serverless
 * This policy defines how data is encrypted at rest within the collection
 */
const encryptionPolicy = new oss.CfnSecurityPolicy(
  openSearchStack,
  "EncryptionPolicy",
  {
    // Unique identifier for the encryption policy
    name: "ddb-etl-encryption-serverless",
    
    // Policy type - 'encryption' handles data encryption at rest
    type: "encryption",
    
    // Human-readable description for the policy
    description: `Encryption policy for ${collectionName} collection`,
    
    // Policy configuration
    policy: JSON.stringify({
      Rules: [{
        // Specify resource type this encryption applies to
        ResourceType: "collection",
        
        // Define which collections this policy affects
        Resource: [`collection/${collectionName}*`]
      }],
      // Use AWS owned KMS key for encryption
      // Alternative: Set to false and specify 'KmsKeyId' for customer managed key
      AWSOwnedKey: true
      
      /* Example of customer managed key configuration:
      AWSOwnedKey: false,
      KmsKeyId: 'arn:aws:kms:region:account:key/key-id'
      */
    })
  }
);

openSearchServerlessCollection.addDependency(encryptionPolicy);

4.2.3.3. Network Policy

Controls network access to the OpenSearch collection.

// amplify/backend.ts
/**
 * Create Network Policy for OpenSearch Serverless
 * This policy controls network access to the OpenSearch collection
 */
const networkPolicy = new oss.CfnSecurityPolicy(
  openSearchStack,
  "NetworkPolicy",
  {
    // Unique identifier for the network policy
    name: "ddb-etl-network-serverless",
    
    // Policy type - 'network' controls access patterns
    type: "network",
    
    // Human-readable description for the policy
    description: `Network policy for ${collectionName} collection`,
    
    // Network access rules
    policy: JSON.stringify([{
      Rules: [{
        // Specify resource type this network policy applies to
        ResourceType: "collection",
        
        // Define which collections this policy affects
        Resource: [`collection/${collectionName}`]
      }],
      // Allow public access to the collection
      // WARNING: For production, consider restricting access:
      AllowFromPublic: true

    }])
  }
);
// Add policy dependencies

openSearchServerlessCollection.addDependency(networkPolicy);

4.2.3.4 Data Access Policy

Grants permissions for creating, updating, and querying data in OpenSearch collections and indexes.

// amplify/backend.ts
/**
 * Creates a data access policy for OpenSearch Serverless
 * This policy defines who can access what within the collection and its indexes
 */
const dataAccessPolicy = new oss.CfnAccessPolicy(
  openSearchStack,
  "DataAccessPolicy",
  {
    name: `ddb-etl-access-policy`,
    type: "data",
    description: `Data access policy for ${collectionName} collection`,
    policy: JSON.stringify([
      {
        /**
         * Collection Level Permissions
         * - CreateCollectionItems: Required for adding new documents
         * - DeleteCollectionItems: Required for removing documents
         * - UpdateCollectionItems: Required for modifying documents
         * - DescribeCollectionItems: Required for reading documents
         */
        Rules: [
          {
            ResourceType: "collection",
            Resource: [`collection/${collectionName}`],
            Permission: [
              "aoss:CreateCollectionItems",
              "aoss:DeleteCollectionItems",
              "aoss:UpdateCollectionItems",
              "aoss:DescribeCollectionItems",
            ],
          },
          /**
           * Index Level Permissions
           * - ReadDocument: Required for search operations
           * - WriteDocument: Required for document updates
           * - CreateIndex: Required for index initialization
           * - DeleteIndex: Required for index cleanup
           * - UpdateIndex: Required for index modifications
           * - DescribeIndex: Required for index metadata
           */
          {
            ResourceType: "index",
            Resource: [`index/${collectionName}/*`],
            Permission: [
              "aoss:ReadDocument",
              "aoss:WriteDocument",
              "aoss:CreateIndex",
              "aoss:DeleteIndex",
              "aoss:UpdateIndex",
              "aoss:DescribeIndex",
            ],
          },
        ],
        Principal: [
          // ETL Pipeline role
          openSearchIntegrationPipelineRole.roleArn,
         
          // AppSync HTTPDataSource role
          httpDataSourceRoleArn,
        ],
      },
    ]),
  }
);

4.3 Create OpenSearch Service Pipeline

When using OpenSearch, defining an index template or mapping in advance provides powerful capabilities for precise data ingestion and search. This approach you can:

Set specific data types for each document field
Optimize search performance
Ensure consistent data structure.

The configuration is a data-prepper feature of OpenSearch. For specific documentation on DynamoDB configuration, refer to OpenSearch data-prepper documentation.

// amplify/backend.ts
// OpenSearch template definition  
interface OpenSearchConfig {
  tableArn: string;
  bucketName: string;
  region: string;
  tableName: string;
  pipelineRoleArn: string;
  openSearchEndpoint: string;
}

function createOpenSearchTemplate(config: OpenSearchConfig): string {
  const template = {
    version: "2",
    "dynamodb-pipeline": {
      source: {
        dynamodb: {
          acknowledgments: true,
          tables: [
            {
              table_arn: config.tableArn,
              stream: { start_position: "LATEST" },
              export: {
                s3_bucket: config.bucketName,
                s3_region: config.region,
                s3_prefix: `${config.tableName}/`,
              },
            },
          ],
          aws: { sts_role_arn: config.pipelineRoleArn, region: config.region },
        },
      },
      sink: [
        {
          opensearch: {
            hosts: [config.openSearchEndpoint],
            index: "movie",
            index_type: "custom",
            document_id: '${getMetadata("primary_key")}',
            action: '${getMetadata("opensearch_action")}',
            document_version: '${getMetadata("document_version")}',
            document_version_type: "external",
            flush_timeout: -1,
            aws: {
              sts_role_arn: config.pipelineRoleArn,
              region: config.region,
              serverless: true,
            },
          },
        },
      ],
    },
  };
  return YAML.stringify(template);
}


const openSearchTemplate = createOpenSearchTemplate({
  tableArn: tableArn,
  bucketName: backend.storage.resources.bucket.bucketName,
  region: region,
  tableName: tableName,
  pipelineRoleArn: openSearchIntegrationPipelineRole.roleArn,
  openSearchEndpoint: openSearchServerlessCollection.attrCollectionEndpoint,
});

Pipeline Configuration Breakdown

Source Configuration

Specifies DynamoDB as the data source
Defines target table for ingestion
Sets stream starting point
Configures S3 backup bucket
Assigns IAM role for pipeline permissions

Sink Configuration

Specifies OpenSearch domain cluster
Sets index name and type
Defines index mapping template
Configures document metadata handling
Sets bulk request size
Assigns IAM role for sink operations

Advanced Configuration Options

Sink configuration supports multiple indexes
Multiple tables can be configured through separate pipelines

For further guidance, please consult the pipeline section of the OpenSearch documentation.

Now, create the OSIS pipeline resource:

// amplify/backend.ts
import * as osis from "aws-cdk-lib/aws-osis";
import { LogGroup } from "aws-cdk-lib/aws-logs";

// Create a CloudWatch log group
const logGroup = new LogGroup(openSearchStack, "LogGroup", {
  logGroupName: "/aws/vendedlogs/OpenSearchServerlessService/pipelines/dev",
  removalPolicy: RemovalPolicy.DESTROY,
});


// Create an OpenSearch Integration Service pipeline
const cfnPipeline = new osis.CfnPipeline(
  openSearchStack,
  "OpenSearchIntegrationPipeline",
  {
    maxUnits: 4,
    minUnits: 1,
    pipelineConfigurationBody: openSearchTemplate,
    pipelineName: "dynamodb-integration",
    logPublishingOptions: {
      isLoggingEnabled: true,
      cloudWatchLogDestination: {
        logGroup: logGroup.logGroupName,
      },
    },
  }
);

After deploying your resources, you’ll want to confirm that your data pipeline is set up correctly before adding items to your Movie table. Here’s how to verify your pipeline configuration:

Open the AWS Management Console Navigate to the Amazon OpenSearch Service section.
Check the Pipelines Section Look for the pipeline you just created. Specifically, you’ll want to:
- Confirm the pipeline name matches your configuration.
- Verify the source and destination settings.
- Check the current status of the pipeline.

The image shows a configured pipeline with details including pipeline name, status, source, and destination settings.

Figure 4: Ingestion Pipeline configuration

Step 5: OpenSearch Query Implementation

Create Resolver and attach to query

Let’s create the search resolver. Create a new file named amplify/data/searchMovieResolver.js and paste the following code. For additional details please refer to Amazon OpenSearch Service Resolvers.

// amplify/data/searchMovieResolver.js
export function request(ctx) {
  return {
    version: "2018-05-29",
    method: "GET",
    params: {
      headers: {
        "Content-Type": "application/json",
      },
      body: {
        from: 0,
        size: 50,
        query: { match: { title: ctx.args.title } },
      },
    },
    resourcePath: `/movie/_search`,
  };
}
/**
 * Returns the fetched items
 * @param {import('@aws-appsync/utils').Context} ctx the context
 * @returns {*} the result
 */

export function response(ctx) {
  const { statusCode, body } = ctx.result;
  if (statusCode === 200) {
    return JSON.parse(body).hits.hits.map((hit) => hit._source);
  }
}

Navigate to the amplify/data/resource.ts file and modify the schema to include the search query:

// amplify/data/resource.ts

   searchMovie: a
    .query()
    .arguments({
      content: a.string(),
    })
    .returns(a.ref("Movie").array())
    .authorization((allow) => [allow.publicApiKey()])
    .handler(
      a.handler.custom({
        entry: "./searchMovieResolver.js",
        dataSource: "OpenSearchServerlessDataSource",
      })
    ),

Step 6: Deployment and Verification

1. Open your terminal and run the following command to start your personal cloud sandbox:

npx ampx sandbox

2. Open a separate terminal and run the following command to start a local development server.

npm run dev

The Movie Search Solution interface displays movie search results, presenting a list of titles and descriptions retrieved from OpenSearch.

Figure 5: Interfacing with the Movie Search Solution

Clean up

Now that you’ve completed this walkthrough, be sure to delete the backend resources to avoid any unexpected costs. You can remove the app as outlined below and verify that all resources are terminated in the AWS Console.

npx ampx sandbox delete

Conclusion

Congratulations! You’ve successfully created a scalable, serverless movie collection search solution using AWS Amplify and Amazon OpenSearch Serverless. You’ve also validated the search results through an Amplify-powered frontend. This approach delivers efficient, cost-effective search capabilities with minimal infrastructure management. Explore further about Amplify by trying our Quickstart tutorial, and join our Community Discord to provide feedback or feature requests.

Building a Gen AI-Powered Manufacturing Search Engine with AWS Amplify Gen 2

Ben-Amin York Jr. — Thu, 16 Jan 2025 18:10:45 +0000

In the manufacturing industry, the ability to quickly and accurately access relevant information across various systems is critical. However, traditional search engines often struggle with siloed data, making it difficult to connect the dots between defect logs, operational data, and cost analyses. This fragmentation can hinder decision-making and operational efficiency.

By leveraging Artificial Intelligence (AI) and advanced search technologies, manufacturers can break down data silos and centralize access to critical insights. With AI-powered search engines that utilize natural language processing (NLP), manufacturing teams can query defect types, severity, trends, and repair costs in a more intuitive and human-like manner. This approach enables manufacturers to:

Improve response times in identifying and addressing defects.
Optimize maintenance workflows by surfacing relevant insights from dispersed data sources.
Reduce downtime by quickly locating actionable insights to mitigate critical issues.
Streamline quality assurance by uncovering patterns and trends in defect data.

This blog walks you through building a search engine using AWS Amplify, Amazon Bedrock, Amazon OpenSearch, focusing on a manufacturing dataset involving defect tracking across various products. Using this data, you’ll learn how to query defect types, severity, and associated repair costs. AWS Amplify Gen 2, powered by the AWS Cloud Development Kit (CDK), enhances flexibility, allowing you to customize your backend resources and integrate a variety of AWS services to build robust applications. Whether it’s detecting defect trends or optimizing inspection methods, you’ll see how generative AI can transform manufacturing workflows.

Figure 1 Trends in defects over time or by location query.

To create your AI-powered search engine, you’ll utilize the following AWS technologies:

AWS Amplify: A comprehensive set of tools and services that help developers build, deploy, and manage secure full-stack applications. It integrates with AWS services including Amazon Cognito for user authentication and authorization. AWS Amplify also supports seamless integration with other services like Amazon S3 and AWS AppSync for storage and API management.
Amazon Bedrock: An AI service that offers high-performing foundation models (FMs). Amazon Bedrock connects with multiple data sources to form a knowledge base (KB). For this app, you’ll use Amazon S3 to form the by storing defect data, which is then processed and indexed by Amazon Bedrock, allowing for intelligent retrieval and response.
Amazon OpenSearch Service: : A flexible, scalable search engine that enables full-text search and analytics. After Amazon Bedrock retrieves the relevant data from the knowledge base, it sends the vectorized results to OpenSearch Service for optimized querying, enabling efficient and accurate defect detection, analysis, and troubleshooting.
Amazon Simple Storage (S3): A scalable storage solution used to store data, such as defect logs. Amazon S3 acts as the primary storage solution for the manufacturing defect data, feeding information into Amazon Bedrock to create the knowledge base used by the search engine.

By combining these AWS services, you’ll be able to create a search engine that not only indexes and retrieves data but also understands the intent behind user queries, providing more accurate and contextually relevant results. AI-powered search engines can help manufacturing customers reduce downtime, optimize defect detection, and improve product quality. With AWS Amplify’s scalability, you can build custom, real-time applications tailored to manufacturing workflows, making it easier to trace defects and streamline production processes.

Figure 2 Generative AI Defect Manufacturing Search Engine architecture diagram.

Prerequisites

An AWS account: Note that AWS Amplify is part of the AWS Free Tier.
Install: npm (v9 or later), and git (v2.14.1 or later).
A Text Editor: For this guide we will use VSCode, but you can use your preferred IDE.
Example Dataset: You’ll be utilizing manufacturing defect data in the provided manufacturing defect data file from Kaggle. However, feel free to explore other datasets available on the site that best fit your needs.
Amazon Bedrock Model Access: This guide requires access to Amazon Titan Text Embeddings V2 and the Anthropic Claude 3 Haiku model. Visit Amazon Bedrock Model access to request access to the listed models.

Cloning the Repo

Step 1: Navigate to the repository on AWS Samples and fork it to your GitHub repositories.

Step 2: Clone the app by running the command below in your terminal.

git clone https://github.com/<YOUR_GITHUB>/amplify-genai-manufacturing-search.git

Step 3: Access the newly cloned repository in VSCode by executing the commands below in your terminal.

cd amplify-genai-manufacturing-search
code . -r

VSCode will open the repository folder, including the Amplify folder, which contains the app code that you’ll review in the next section.

Figure 3 Opening code in VSCode.

Step 4: Install the required packages, including the Amplify Gen2 packages, by running the following command:

npm i

The Amplify Backend

In the final app (as seen in the gif at the beginning of the post), users type in their query and click a button to request information relevant to their query from Amazon Bedrock’s knowledge base. The code for this is in the repository you cloned. Here, you’ll go over the key steps for creating your Amplify-developed and hosted search engine app. In the repository, you’ll find an Amplify folder containing a data directory.

Figure 4 Amplify Gen 2 Project Folder Structure.

In the amplify/auth/resource.ts file,authentication is configured to require users to log in with their email to access the application and upload files. By enabling email-based login, you ensure only verified users can interact with sensitive data and functionalities.

import { defineAuth } from '@aws-amplify/backend';
 
export const auth = defineAuth({
    loginWith: {
        email: true,
    },
});

Next, in the amplify/data/resource.ts file, you’ll find a GraphQL query capable of receiving a list of sensor readings or defect data and linking to Amazon Bedrock to produce a contextually relevant response to the user. The GraphQL API schema consists of two main parts:

generateHaiku Query: This query takes a string argument called prompt and returns the response generated by Claude Haiku as a string.You restrict access to authenticated users using .authorization((allow) => [allow.authenticated()]), ensuring only signed-in users can query the search engine. This improves security by leveraging Amazon Cognito user pools for stronger access control, rather than relying on a public API key. The .handler(a.handler.function(generateHaikuFunction)) processes the response based on the provided prompt.
API Schema Configuration: The schema is defined using a.schema schema where the generateHaiku query is configured. The API’s default authorization mode is set to use userPools, specified in the authorizationModes configuration.

import { type ClientSchema, a, defineData } from "@aws-amplify/backend";
import { generateHaikuFunction } from "../functions/generateFunction/resource";

const schema = a.schema({
  generateHaiku: a.query()
    .arguments({ prompt: a.string().required() })
    .returns(a.string())
    .authorization((allow) => => [allow.authenticated()])
    .handler(a.handler.function(generateHaikuFunction)),
});

export type Schema = ClientSchema<typeof schema>;

export const data = defineData({
  schema,
  authorizationModes: {
    defaultAuthorizationMode: "userPool",
  },
});

The amplify/functions/generateFunction/resource.ts file defines a Lambda function that contains a handler.ts function to resolve your custom GraphQL queries.

import { defineFunction } from '@aws-amplify/backend';

export const generateHaikuFunction = defineFunction({
    name: 'generate-haiku',
    entry: './handler.ts',
    timeoutSeconds: 60
});

In the handler.ts function, you use the RetrieveAndGenerateCommand from the AWS SDK’s Agent Runtime client to retrieve relevant data from an Amazon Bedrock knowledge base, structure the user’s input with a predefined template, and generate a response based on the retrieved information. The session is secured with an AWS Key Management Service (KMS) ) key, and the function parses the response to extract the generated data and citations for a structured output.

import type { Schema } from "../../data/resource";
 
import {
    BedrockAgentRuntimeClient,
    RetrieveAndGenerateCommand,
    RetrieveAndGenerateCommandInput,
    PromptTemplate
} from "@aws-sdk/client-bedrock-agent-runtime";
 
const client = new BedrockAgentRuntimeClient();
 
export const handler: Schema["generateHaiku"]["functionHandler"] = async (
    event,
) => {
    const prompt = event.arguments.prompt;
 
    const promptTemplate: PromptTemplate = {
        textPromptTemplate: `
            Based on the following search results:
            $search_results$
            Respond to the specific query, focusing on the relevant information based on the search results.
            If the query asks about repair costs, format the repair cost as follows: include a $ sign before the amount.
            Example for repair cost:
            Defect ID: 176, Product ID: 13, Defect Type: Structural, Date: 3/9/2024, Location: Surface, Severity: Critical, Inspection Method: Manual Testing, Repair Cost: $952.49
            Respond directly to the query, and only include relevant fields such as defect severity, inspection type, or trends if applicable.
            Respond only if the search results are relevant. Do not respond to queries outside of the search results.
            Do not include introductory phrases like 'Here is a haiku' or 'From haiku'. Respond directly to the query.`,
    };
 
    const input: RetrieveAndGenerateCommandInput = {
        input: {
            text: prompt,
        },
 
        retrieveAndGenerateConfiguration: {
            type: "KNOWLEDGE_BASE",
            knowledgeBaseConfiguration: {
                knowledgeBaseId: process.env.KNOWLEDGE_BASE_ID!,
                modelArn: process.env.MODEL_ARN!,
                retrievalConfiguration: {
                    vectorSearchConfiguration: {
                        numberOfResults: 10
                    },
                },
                generationConfiguration: {
                    promptTemplate,
                    inferenceConfig: {
                        textInferenceConfig: {
                            temperature: 0.7,
                            maxTokens: 150,
                        },
                    },
                },
            },
        },
        sessionConfiguration: {
            kmsKeyArn: process.env.KMS_KEY!,
        },
    };
 
    const command = new RetrieveAndGenerateCommand(input);
 
    const response = await client.send(command);
 
    const generatedText = response.output?.text || "The query does not match any known results.";
 
    const citations = response.citations?.map((citation, index) => {
        const location = citation.retrievedReferences?.[0]?.location;
        if (location) {
            const s3Uri = location.s3Location?.uri || "";
            return `${index + 1}. ${s3Uri}`;
        } else {
            return `${index + 1}.`;
        }
    }).join("\n") || "No citations available";
 
    return `${generatedText}\n\nCitations:\n${citations}`;
};

In the amplify/storage/resource.ts file, you configure Amplify Storage, built on Amazon S3, to manage file storage and enable essential operations like uploads. You use the defineStorage function to instantiate the storage with a user-friendly name for internal reference. Although AWS Amplify generates a unique identifier for the bucket, providing a bucket name helps identify it within your app’s backend configuration. The bucket is set up to allow authenticated users to read and write to the public/* path, for storing sample search data.

import { defineStorage } from "@aws-amplify/backend";
 
export const storage = defineStorage({
    name: "amplify-search-tool-storage",
    access: (allow) => ({
        'public/*': [
            allow.authenticated.to(['read', 'write'])
        ]
    })
});

In the amplify/backend.ts you import the CDK libraries to configure various aspects of your application. The aws-iam library is used to manage permissions, aws-kms handles session management, aws-opensearchserverless configures Amazon OpenSearch Service, and aws-bedrock facilitates response generation. Each library serves a distinct purpose, ensuring your application is properly configured.

import * as kms from 'aws-cdk-lib/aws-kms';
import * as iam from 'aws-cdk-lib/aws-iam';
import * as opensearchserverless from 'aws-cdk-lib/aws-opensearchserverless'

// /* AWS CDK LIBRARIES FOR 2ND DEPLOYMENT */
// import * as bedrock from 'aws-cdk-lib/aws-bedrock';
// import { Effect, PolicyStatement } from "aws-cdk-lib/aws-iam";

Next, use the backend.createStack() method to direct the backend to generate a new CloudFormation Stack to house custom resources. With AWS Amplify Gen 2, you can create custom resources using the CDK, enabling the use of services beyond the Amplify library, with stacks backed by CloudFormation templates for scalability. For example, you could create a Generative AI stack for AI-related services and an authentication stack for managing Cognito resources, ensuring logical organization before adding custom AWS resources. Now, you can begin defining custom AWS resources!

const customResourceStack = backend.createStack('MyCustomResources');

Within the customResourceStack, define an Amazon OpenSearch Serverless access policy (CfnAccessPolicy) that outlines the permissions required to manage both indices and collections in Amazon OpenSearch Serverless. The Principal in this policy is set to `arn:aws:iam::${customResourceStack.account}:role/Admin` to ensure that only authorized entities with the specified IAM role can perform critical operations like creating, updating, and deleting indices and collections.

In addition to the access policy, define a security policy (CfnSecurityPolicy) that specifies encryption settings for the OpenSearch Service collection. This policy ensures that all data stored in the amplify-aoss-collection collection is encrypted using an AWS-owned key, which simplifies key management while ensuring data is protected at rest.

const accessPolicy = new opensearchserverless.CfnAccessPolicy(customResourceStack, 'OpenSearchAccessPolicy', {
  name: 'collection-policy',
  type: 'data',
  description: 'Access policy for collection',
  policy: JSON.stringify([{
    Description: 'Access for test-user',
    Rules: [
      {
        ResourceType: 'index',
        Resource: ['index/amplify-aoss-collection/*'],
        Permission: [
          'aoss:CreateIndex',
          'aoss:DeleteIndex',
          'aoss:UpdateIndex',
          'aoss:DescribeIndex',
          'aoss:ReadDocument',
          'aoss:WriteDocument'
        ]
      },
      {
        ResourceType: 'collection',
        Resource: ['collection/amplify-aoss-collection'],
        Permission: [
          'aoss:CreateCollectionItems',
          'aoss:DeleteCollectionItems',
          'aoss:UpdateCollectionItems',
          'aoss:DescribeCollectionItems'
        ]
      }
    ],
    /* REPLACE  WITH THE DEFAULT PRINCIPAL */
    Principal: [permissions.roleArn,`arn:aws:iam::${customResourceStack.account}:role/Admin`],
  }])
});
 
/* DEFINE AMAZON OPENSEARCH SECURITY POLICY */
const securityPolicy = new opensearchserverless.CfnSecurityPolicy(customResourceStack, 'OpenSearchSecurityPolicy', {
  description: 'Security policy for my-collection',
  name: 'amplify-security-policy',
  type: 'encryption',
  policy: JSON.stringify({
    Rules: [
      {
        ResourceType: 'collection',
        Resource: ['collection/amplify-aoss-collection'],
      }
    ],
    AWSOwnedKey: true,
  })
});

A collection is a grouping of one or more indexes, representing an analytics workload. This collection will serve as a scalable and efficient storage solution for your search engine data, enabling rapid search operations and ensuring high availability. By specifying the CfnCollection construct, you lay the foundation for data storage and retrieval capabilities.

const collection = new opensearchserverless.CfnCollection(customResourceStack, 'OpenSearchCollection', {
  name: 'amplify-aoss-collection',
  type: 'VECTORSEARCH',
  description: 'Collection for amplify search tool',
});

When you run the app (as demonstrated in the next section), a file named amplify_outputs.json is generated automatically. This file holds your API’s endpoint and Auth metadata details. In the src/app/App.tsx, you initialize and configure the AWS Amplify client library, then create a data client to facilitate fully-typed API requests to the AWS Amplify backend. The query is made in the handleSearch function using the client.queries.generateHaiku method.

import { Amplify } from 'aws-amplify';
import outputs from '../amplify_outputs.json';
import { generateClient } from "aws-amplify/api";
import { Schema } from "../amplify/data/resource";
 
Amplify.configure(outputs);
 
const client = generateClient();
 
const App: React.FC = () => {
  const [messages, setMessages] = useState([]);
 
  const handleSearch = async (query: string) => {
    if (!query.trim()) {
      setMessages((prevMessages) => [...prevMessages, { user: 'bot', text: 'Query cannot be empty.' }]);
      return;
    }
 
    try {
      const { data, errors } = await client.queries.generateHaiku({ prompt: query });
 
      if (errors) {
        throw new Error(`Error from Bedrock: ${errors[0].message}`);
      }
 
      setMessages((prevMessages) => [...prevMessages, { user: 'bot', text: data || "No response from AI" }]);
    } catch (error) {
      let errorMessage = 'Error fetching data.';
      if (error instanceof Error) {
        errorMessage = error.message;
      }
      setMessages((prevMessages) => [...prevMessages, { user: 'bot', text: `Error fetching data: ${errorMessage}` }]);
    }
  };

In src/components/Uploader.tsx the Amplify Storage Manager UI component streamlines file upload operations directly from your user interface to your Amazon S3 bucket. This component simplifies the process, enabling you to integrate robust file storage functionality with minimal setup. Whether you’re handling images, documents, or other file types, the Amplify Storage Manager offers flexible configuration options, such as setting upload limits, handling resumable uploads, and customizing file paths.

import React from 'react';
import { StorageManager } from '@aws-amplify/ui-react-storage';
import '@aws-amplify/ui-react/styles.css';
 
const Uploader: React.FC = () => {
    return (
        <div class="uploader">
            <StorageManager
                acceptedFileTypes={['.csv']}
                path="public/"
                maxFileCount={10}
                isResumable
            />
        </div>
    );
};
 
export default Uploader;

Running the App

Step 1: Amplify provides each developer with a personal cloud sandbox environment, offering isolated development spaces for rapid building, testing, and iteration. To initiate a cloud sandbox environment, open a new terminal window and execute the following command:

npx ampx sandbox

Step 2: Execute the command below to start a localhost development server.

npm run dev

After running the previous command to start the application, use the ‘Create Account‘ feature of the Amplify Authenticator component, to provide an email address and password. After finalizing user setup via a confirmation email, log in to gain access to the application.

Figure 5 Signing into the app, after creating an account.

After interacting with the app on the development server, stop the sandbox environment by pressing Ctrl + C in the terminal. Make sure to enter ‘Y’ when prompted to delete resources in the sandbox environment.

Figure 6 Delete cloud sandbox resources.

Deploying backend resources

With the app functioning as expected, deploy your backend resources by following the steps in ‘Getting Started with Deploying an App to Amplify Hosting’. Ensure that GitHub is selected as the repository for deployment.

Upload Sample Data

After deploying and signing into the application, upload sample data by accessing the app domain URL generated by Amplify. After uploading files, confirm the upload by checking the public/ folder within the Storage section of the AWS Amplify console.

Figure 7 Uploading Defects data file.

Creating a Vector Index in Amazon OpenSearch Serverless

Before defining a Bedrock knowledge base, in the Amazon OpenSearch console, Create a vector index for the amplify-aoss-collection. (Figure 5)

This index will store and search vector embeddings, which are numerical representations of text, images, or other data. Define the vector field name (for storing embeddings), vector dimensions (up to 16,000), and the distance metric (e.g., Euclidean, cosine, or dot product) to optimize your OpenSearch Service collection for efficient and accurate search operations.

Figure 8 Create vector index in OpenSearch Serverless collection.

From the Create Vector Index page, define the following values:

Vector index name: bedrock-knowledge-base-default-index
Vector fields, Add vector field:
- Vector field name: bedrock-knowledge-base-default-vector
- Engine: faiss
- Dimensions: 1024
- Distance metric: Euclidiean
Metadata management:
- Mapping field 1:
  - Mapping field: AMAZON_BEDROCK_TEXT_CHUNK
  - Data type: String
  - Filterable: True
- Mapping field 2:
  - Mapping field: AMAZON_BEDROCK_METADATA
  - Data type: String
  - Filterable: False

Lastly, select Create as shown in Figure 9.

Figure 9 Select Create for vector index in OpenSearch Serverless collection.

Defining an Amazon Bedrock Knowledgebase

Next, in the backend.ts file, the CfnKnowledgeBase construct creates a vector knowledge base for storing and managing structured and unstructured data. Here you’ll integrate the knowledge base with the OpenSearch Serverless collection to provide advanced vectorization and search capabilities. This knowledge base offers a repository of information that a foundational model can query to deliver accurate and contextually relevant responses.

const knowledgeBase = new bedrock.CfnKnowledgeBase(customResourceStack, 'BedrockKB', {
  knowledgeBaseConfiguration: {
    type: 'VECTOR',
    vectorKnowledgeBaseConfiguration: {
      embeddingModelArn: 'arn:aws:bedrock:us-east-1::foundation-model/amazon.titan-embed-text-v2:0',
    },
  },
  name: 'amplify-search-tool-kb',
  roleArn: permissions.roleArn,
  storageConfiguration: {
    type: 'OPENSEARCH_SERVERLESS',
    opensearchServerlessConfiguration: {
      collectionArn: collection.attrArn,
      vectorIndexName: 'bedrock-knowledge-base-default-index', 
      fieldMapping: {
        vectorField: 'bedrock-knowledge-base-default-vector',
        textField: 'AMAZON_BEDROCK_TEXT_CHUNK', 
        metadataField: 'AMAZON_BEDROCK_METADATA', 
    },
  }
});

After creating the knowledge base, define the Amazon S3 bucket created as the data source for the Amazon Bedrock knowledge base. To achieve this, retrieve the Amazon Resource Name (ARN) of the bucket by accessing its properties using dot notation. Configuring an Amazon S3 bucket to store sample search data facilitates efficient data ingestion and management. Using the CfnDataSource construct, you create a link from Amazon S3 to the knowledge base, allowing the knowledge base to access and process uploaded data.

new bedrock.CfnDataSource(customResourceStack, 'BedrockDataSource', {
  name: 'amplify-search-tool-data-source',
  knowledgeBaseId: knowledgeBase.attrKnowledgeBaseId,
  dataSourceConfiguration: {
    type: 'S3',
    s3Configuration: {
        bucketArn: backend.storage.resources.bucket.bucketArn,
    },
  },
});

Deploying the App Updates

Finalize updates by adding, committing, and pushing changes to your repository. This action automatically triggers a deployment in AWS Amplify, ensuring the app is up-to-date and live.

Sync S3 Data with Bedrock Knowledge Base

After deploying the app, sync the Amazon S3 bucket with the Amazon Bedrock Knowledge base. From the Amazon Bedrock console, navigate to Knowledge bases, select amplify-search-tool-kb. Then, scroll to Data source and select Sync (Figure 10).

Figure 10 Syncing Amazon S3 bucket data with Amazon Bedrock knowledge base.

Once the data source syncs successfully and the status shows “Available“, start querying the search engine directly through the application!

Figure 11 Interfacing with Defect Search app.

Cleaning Up

Navigate to the AWS Amplify console, click on “View app” for the application created during this blog. Then, go to “App Settings” followed by “General Settings.” Finally, select “Delete app” to remove the application and associated backend resources. Note, AWS Amplify will delete all backend resources created a part of your project.

Conclusion

Now that you’ve learned how to configure and deploy a generative AI-powered search engine using AWS Amplify Gen 2, Amazon Bedrock, Amazon OpenSearch Service, and other AWS services, it’s time to take the next step. Start building your own custom applications with the Amplify Gen 2 Workshop, and consider leveraging a generative AI-powered coding assistant, Amazon Q Developer, for your development efforts.

Looking for a quick way to start building AI-powered applications with AWS Amplify? Check out the Amplify AI Kit to bring your ideas to life faster than ever. By utilizing these advanced AI services, you can create and deploy sophisticated search capabilities that deliver enhanced user experiences.

AWS AppSync field-level resolvers: Enhancing GraphQL API development

Kim Wendt — Tue, 14 Jan 2025 14:52:48 +0000

Introduction

In this post, we’ll explore AWS AppSync field-level resolvers and how they can enhance your GraphQL API development. Field-level resolvers are powerful units of code that determine how data is fetched, processed, and returned for specific fields in your schema types. By leveraging field-level resolvers in AWS AppSync, you’ll learn how to efficiently handle complex data operations, integrate multiple data sources, and create more flexible and performant APIs. We’ll cover the basics of field resolvers and how they can help you build scalable and responsive applications. Whether you’re new to GraphQL or looking to optimize your existing AWS AppSync implementations, this post will provide you with practical insights to make the most of field-level resolvers in your projects.

Resolver patterns with AWS AppSync

AWS AppSync offers various resolver strategies to accommodate different data access patterns and complexity levels. For straightforward operations involving a single data source, unit resolvers are the go-to solution. These resolvers handle simple queries or mutations, mapping directly to a specific data source like Amazon DynamoDB or AWS Lambda. As applications grow more complex, pipeline resolvers become invaluable for orchestrating multiple data operations. These allow developers to chain together a series of functions, each performing a specific task such as data validation, transformation, or aggregation from multiple sources. This modular approach enhances code reusability and maintainability.

Field-level resolvers in GraphQL provide fine-grained control over individual fields within a type, allowing customized data fetching or computation for each field independently. They are particularly useful when different fields in the same type need to be resolved from various data sources or require unique processing. The choice between field-level resolvers and pipeline resolvers depends on specific application requirements, with field-level resolvers offering granular control and pipeline resolvers providing a structured approach for complex, multi-step operations.

Field-level resolvers provide a different method to reuse query logic in your code. In a pipeline resolver, you can reuse code through AWS AppSync functions, while field-level resolvers allow a field associated with a type to resolve using the same logic from multiple query patterns.

Restaurant scenario

To better understand field-level resolver implementation, we’ll discuss a practical scenario. This scenario explores a common use case in the restaurant industry where a query operation retrieves comprehensive information about a restaurant, including its menu items.

type MenuItem {
    item: String!
    price: Float!
    description: String
}

type Restaurant {
    id: ID!
    name: String!
    address: String
    menu_id: ID!
    menu: [MenuItem!]!
}

type Query {
    getRestaurantDetails(id: ID!): Restaurant
}

The challenge lies in the data architecture: while the general restaurant information is stored in one data source, the menu details are housed in a separate data source. To resolve this, we implement a field-level resolver for the menu field within the restaurant type. This resolver utilizes the menu_id from the parent restaurant object to fetch the corresponding menu items from the separate data source. The query operation demonstrated here showcases how clients can request restaurant details and associated menu items in a single, efficient GraphQL query, highlighting the power of AWS AppSync’s resolver system in handling complex data relationships.

Creating the resolvers

For this example, we will use an Amazon DynamoDB table to store information about the restaurants and an Amazon Aurora PostgreSQL database for storing menu information.

// Restaurant DynamoDB table design
Primary key: id (String)
Attributes:
- name (String)
- address (String)
- menu_id (String)

// Menu table schema
CREATE TABLE menu (
  id VARCHAR(36),
  menu_id VARCHAR(36),
  item TEXT NOT NULL,
  description TEXT NOT NULL,
  price NUMERIC(10,2) NOT NULL,
  PRIMARY KEY (id)
);

Creating the `getRestaurantDetails` field resolver

To retrieve the restaurant details for a single restaurant, we can attach the following unit resolver to the getRestaurantDetails query operation. In the resolver below, we are able to simplify the interaction to the DynamoDB table using the AWS AppSync DynamoDB module.

import { util } from '@aws-appsync/utils';
import { get } from '@aws-appsync/utils/dynamodb';

export function request(ctx) {    
    return get({ key: { id: ctx.args.id } });
}

export function response(ctx) {
    if (ctx.error) {
        util.error(ctx.error.message, ctx.error.type);
    }
    return ctx.result;
}

Resolving the `menu` field

The previous resolver allows us to retrieve the name, address, and menu_id for a specific restaurant. Now we need a way to retrieve the menu items as part of the same query operation. The unit resolver below is attached to the menu field in the Restaurant type so that whenever the Restaurant type is returned using a query operation, this resolver code executes to resolve the menu field. Similar to the resolver above, we are able to simplify the interaction to the PostgreSQL database using the AWS AppSync RDS module.

import { util } from "@aws-appsync/utils";
import { select, sql, createPgStatement, toJsonObject, typeHint } from "@aws-appsync/utils/rds";

export function request(ctx) {
    const menuId = ctx.source.menu_id;

    const fetchMenu = select({
        table: "menus",
        columns: "*",
        where: {
            menu_id: { eq: menuId },
        }
    });
    return createPgStatement(fetchMenu);
}


export function response(ctx) {
    const { error, result } = ctx;
    if (error) {
        return util.appendError(error.message, error.type, result);
    }
    return toJsonObject(result)[0];
}

Notice that on line 4 in the resolver above, we’re able to reference the menu_id which was resolved as part of the parent Restaurant type. In the resolver, you’re able to access any previously resolved fields from the parent type using the ctx.source object. For more information on the structure of the ctx object, please refer to the documentation.

Setting up data

Before executing the query, let’s seed the databases with some sample data. For the PostgreSQL database, execute the following statement:

 INSERT INTO 
  menus (id, menu_id, item, description, price) 
 VALUES ('39a4e192-92ce-4665-b874-7ffe7ba2d757', '9ce86066-1a49-4f41-b817-8fa605f680d5', 'Strawberry Milkshake', 'Made with 100% artificial ingredients', 10.21);
  INSERT INTO 
  menus (id, menu_id, item, description, price) 
 VALUES ('0f75668f-3014-4c42-bf82-3da8543b59ad', '9ce86066-1a49-4f41-b817-8fa605f680d5', 'Apple Pie', 'Contains zero apples', 7.11);

For the DynamoDB table, insert the following item:

{
  "id": {
    "S": "0cbf6478-d2c3-4549-a2d6-b4b8a3ddb582"
  },
  "address": {
    "S": "1234 Main Avenue"
  },
  "menu_id": {
    "S": "9ce86066-1a49-4f41-b817-8fa605f680d5"
  },
  "name": {
    "S": "Sam's Diner"
  }
}

Example query

Below is an example query that illustrates the field resolution we described above. To resolve the requested data for this query operation, AWS AppSync will first resolve the Restaurant type and then subsequently will resolve the menu field in the parent Restaurant type. This operation results in 1 network call from the client while the backed resolution complexity is completely abstracted away from the client.

query MyQuery {
  getRestaurantDetails(id: '0cbf6478-d2c3-4549-a2d6-b4b8a3ddb582') {
    name
    id
    menu_id
    address
    menu {
      item
      price
      description
    }
  }
}

AWS AppSync query editor

When dealing with relatively static information, such as menu items that don’t change often, leveraging caching can significantly boost your query operations’ performance. AWS AppSync offers two caching modes: per-resolver caching and full request caching. For expensive overall requests with many resolvers, the full-operation cache minimizes load and increasing performance across the entire request, while per-resolver caching minimizes load on a resolver, even across multiple request types. By enabling this feature, you can dramatically reduce response times and minimize unnecessary data fetches, resulting in a more responsive and efficient application. To implement caching in AWS AppSync, simply activate the “Per-resolver caching” or “Full request caching” option in the caching section of the AWS AppSync service menu. Per resolver caching allows fine-tune your caching strategy by configuring the caching keys and TTL for your cached data

Conclusion

In conclusion, AWS AppSync field-level resolvers offer a powerful and flexible way to enhance your GraphQL API development. By leveraging field resolvers, you can efficiently handle complex data operations, integrate multiple data sources, and create more responsive and scalable applications. Whether you’re dealing with straightforward queries or more intricate data relationships, field-level resolvers provide the granular control needed to resolve individual fields independently. This approach not only optimizes performance but also promotes code reusability and maintainability. As your API evolves, you can split the implementation into different APIs that can be merged into an AWS AppSync Merged API, further enhancing modularity and scalability. As demonstrated in the restaurant scenario, field resolvers can seamlessly fetch data from different sources and aggregate it into a single, efficient GraphQL query. By understanding and implementing field-level resolvers, you can unlock the full potential of AWS AppSync to build more dynamic and robust APIs.

Amazon Aurora MySQL-Compatible Edition now supports a redesigned RDS Data API for Aurora Serverless v2 and Aurora provisioned database instances. Data API enables access to Aurora databases via AWS AppSync GraphQL APIs through direct data sources which means you can use this same blog with a MySQL Aurora database with some minor changes to the resolver code.

The most visited Front-end Web and Mobile blog posts in 2024

Brian Beach — Thu, 02 Jan 2025 14:23:09 +0000

As we kick off 2025, I wanted to take a moment to highlight the top posts from 2024. Without further ado, here are the 10 front-end web and mobile blog posts of 2024.

Fullstack TypeScript Reintroducing AWS Amplify – This blog post announces the general availability of AWS Amplify Gen 2, a fullstack TypeScript experience for building cloud-connected apps. It highlights key features including zero-config authentication, type-safe cloud data integration, and PubSub APIs for real-time multiplayer use cases. The post walks through building a real-time multiplayer application, demonstrating how to deploy a frontend, set up authentication, create a cloud API, and implement real-time cursor sharing between users. It emphasizes Amplify’s integration with AWS services, improved developer experience with TypeScript, and the ability to create isolated development environments. The post also addresses migration concerns for existing Gen 1 users and positions Amplify within the broader fullstack TypeScript ecosystem.

Announcing AWS AppSync Events serverless WebSocket APIs to power real time web and mobile experiences at any scale – This blog post announces AWS AppSync Events, a new feature that enables developers to create serverless WebSocket APIs for real-time event broadcasting at scale. The service simplifies the process of building and managing WebSocket infrastructure, allowing developers to easily publish events to millions of subscribers. Key features include easy setup, serverless architecture, support for event-driven architectures, and integration with existing AWS services like Amazon EventBridge. The post explains how to create an API, define channel namespaces, and use event handlers for custom logic. It also demonstrates how to integrate AWS AppSync Events with web applications and highlights future plans for the service, including bi-directional WebSockets and additional data source support.

Build fullstack AI apps in minutes with the new Amplify AI Kit – This blog post announces the general availability of the AWS Amplify AI kit, a tool designed to help fullstack developers quickly build web apps with AI capabilities such as chat, conversational search, and summarization. The kit allows developers to create AI functionality without extensive cloud architecture or machine learning experience. It uses TypeScript for backend definition and offers two types of AI routes: conversation and generation. The kit integrates seamlessly with Amplify’s existing features, providing type-safe clients and React hooks for easy implementation. It also allows for connecting AI functionality to existing data models and includes features for generative UI. The post emphasizes the serverless nature of the architecture and the ease of deployment.

Deploy Next js 14 SSR apps with AWS Amplify Hosting s Amazon Linux 2023 Support – This blog post announces that AWS Amplify Hosting now defaults to Amazon Linux 2023 for newly deployed applications. This update enables the use of newer versions of Node.js, Ruby, and Python. The post highlights that Node.js 18 and 20, as well as Python 3.10 and 3.11, are pre-installed in the default build image. It provides a step-by-step guide on how to upgrade existing applications from Amazon Linux 2 to Amazon Linux 2023. The update particularly benefits developers using Next.js 14, allowing easier deployment without custom configuration. The post concludes by encouraging users to deploy their SSR or static apps using Amplify Hosting and join the Community Discord for feedback.

Use Generative AI and Next js with AWS Amplify to build a Fullstack Recipe Generator – This blog post guides readers through creating an AI-powered recipe generator using AWS Amplify Gen 2, Next.js, and Amazon Bedrock with Claude 3. The app allows users to input ingredients and receive AI-generated recipes. The tutorial covers prerequisites, setting up Amazon Bedrock access, cloning the repository, and implementing the backend using GraphQL and custom handlers. It explains how to connect Amplify with Amazon Bedrock, handle user inputs, and generate recipes. The post also walks through running the app locally and deploying it using Amplify Hosting. It concludes by showing how to clean up resources and encourages readers to explore Amplify Gen 2 further.

Amplify Functions Create serverless functions using TypeScript powered by AWS Lambda – AWS Amplify has launched Functions for Gen 2, enabling developers to create serverless functions using TypeScript, powered by AWS Lambda. This feature allows for seamless integration with other Amplify resources and custom AWS services. Functions can be defined and authored in TypeScript, with automatic bundling via esbuild. Key benefits include quick iteration through hot-swapping, typed environment variables and handlers, simplified secret management, and easy extension to other AWS services via CDK. The post guides developers through defining functions, configuring access to resources, handling custom queries, and interacting with services like Amazon Bedrock. This release streamlines serverless development within the Amplify ecosystem, enhancing productivity and flexibility for front-end developers.

New in AWS Amplify Integrate with SQL databases OIDC SAML providers and the AWS CDK – This blog post announces four new capabilities in AWS Amplify Gen 2, focusing on extensibility. These include integration with existing SQL databases (PostgreSQL or MySQL), authentication with any OpenID Connect or SAML provider, customization of Amplify-generated AWS service resources, and the ability to add any of the 200+ AWS services to an app. The post provides examples of integrating with a PostgreSQL database, setting up OIDC authentication, customizing S3 bucket lifecycle rules, and adding Amazon Bedrock for AI capabilities. These features aim to give developers more flexibility and power in building and customizing their applications while leveraging AWS services.

Bring your own SSL certificate to AWS Amplify Hosting – This blog post announces the general availability of Custom SSL Certificates on AWS Amplify Hosting, allowing users to configure their Amplify domains with their own SSL certificates from AWS Certificate Manager (ACM). The feature enables users to use certificates from third-party authorities, configure TLS versions and encryption algorithms, and share certificates across multiple domains. The post provides a step-by-step walkthrough on how to request or import an ACM certificate and associate it with an Amplify domain. It covers the process of provisioning a certificate in the US East (N. Virginia) Region, either by requesting a new one or importing an existing one, and then using it with an Amplify domain.

Building a Secure GraphQL API with AWS Amplify and AWS AppSync – This blog post describes how to build a secure GraphQL API using AWS Amplify and AWS AppSync, addressing Cross-Origin Resource Sharing (CORS) challenges in client-side web development. It outlines a high-level architecture integrating Amazon CloudFront with AWS AppSync to enforce domain-specific access to GraphQL APIs. The post provides step-by-step instructions for setting up a new AWS CDK project, configuring Amplify and AppSync, and implementing CloudFront distribution settings. It also covers updating the Amplify app configuration and testing the implementation. The solution aims to simplify CORS configuration, enhance security, and improve user experience for developers building robust web applications.

Best practices for AWS AppSync GraphQL APIs – This blog post discusses best practices for building GraphQL APIs using AWS AppSync. It covers four main areas: security, performance, coding standards, and deployment. Key recommendations include choosing appropriate authentication methods, implementing caching strategies, using pipeline resolvers and JavaScript for coding, and adopting Infrastructure as Code for deployment. The post emphasizes the benefits of AWS AppSync as a fully managed service that integrates well with other AWS services. It also highlights the importance of using AWS Amplify for simplified deployment and CI/CD pipelines. Overall, the article provides a comprehensive guide for developers to optimize their AWS AppSync GraphQL APIs.

re:Invent 2024 Front-end Web and Mobile Playlist

Brian Beach — Thu, 02 Jan 2025 14:22:42 +0000

The dust has settled after another re:Invent. I once again had the privilege of organizing the Front-end Web and Mobile (FWM) track along with Ali Spittel and countless others. For 2024, the FWM track included 29 sessions. If you weren’t able to attend, I have compiled a list of the on-demand sessions for you below.

FWM202 Fullstack AI with AWS Amplify Generative AI is transforming fullstack development. In this session, learn how AWS Amplify, Amazon Q, and Amazon Bedrock work together to streamline building generative AI apps. See how Amplify enables developers to build AI-driven features like intelligent search, summarization, content generation, and interactive chatbots backed by Amazon Bedrock. The session also demonstrates how Amplify with Amazon Q can accelerate your development process.

FWM203 I didn’t know AWS AppSync could do that!AWS AppSync is a managed service for developers to connect their apps to cloud data, events, and AI models. No longer just a GraphQL API service, with AWS AppSync you can leverage serverless WebSockets to create real-time event APIs, build AI gateways to simplify and secure application access to Amazon Bedrock, and more. Join this session to learn about all the exciting new AWS AppSync features released this year.

FWM204 Optimizing the world’s top apps: How Meta tests using AWS Device Farm In this session, learn how you can improve the quality of your mobile and web apps by running tests on real devices at scale with AWS Device Farm. Hear from Meta, a leading social media company, about how it uses Device Farm to streamline its mobile app testing process, improve the quality of its mobile apps and SDKs, run automated and manual tests on real devices in the cloud, identify and fix issues faster, and release updates more frequently.

FWM205 Startup to enterprise: Build frontend and fullstack apps that scale AWS Amplify offers professional development teams an end-to-end experience and proven patterns to accelerate productivity and build with the speed and reliability of AWS infrastructure. Learn how to use these built-in patterns—along with Amplify’s flexibility to customize your AWS backend with CDK—to build apps that your organization can’t outgrow. This session provides a walkthrough of real-world scenarios and introduces new enterprise-focused capabilities in Amplify that make it easier than ever to build, deploy, and host secure, scalable, cloud-connected applications on AWS.

FWM302 Real-time event patterns with WebSockets and AWS AppSync AWS AppSync makes it easier for developers to build applications that consume real-time data updates and events, like live sports scores and stats, group chat messages, prices, or location and schedule updates. With AWS AppSync managed WebSocket channels, you can easily scale to connect millions of users and deliver billions of messages. In this session, learn how organizations like PGA Tour are using AWS AppSync to deliver real-time event updates to their application users. Additionally, get an overview of new features like enhanced filtering options and native integration with Amazon EventBridge.

FWM310 Build an AI gateway for Amazon Bedrock with AWS AppSync Integrating generative AI into applications can be complex, often requiring developers to deal with complex permissions, exposed credentials, and identity management challenges when accessing AI backends. This session discusses how to use AWS AppSync to simplify integration with AI backends like Amazon Bedrock, implement tailored queries for your use cases, take advantage of security features to deploy a production-ready API, and control access to your generative AI resources. It covers both synchronous and asynchronous use cases.

FWM311 What’s new in AWS for frontend developers AWS Amplify makes it easy for frontend web and mobile developers to build full-stack applications in hours with minimal cloud expertise. This session walks through Amplify’s capabilities, including how you can easily configure a backend with authentication, data, and storage; how you can create a frontend UI; and how you can host server-side rendered web apps with Next.js. Learn about exciting new features that make it even easier for developers and teams to accelerate the pace of their innovation, leverage data to build differentiated application experiences, and give individual engineers the power of a virtual team.

AWS Amplify Hosting Adds Web Application Firewall Protection – Public Preview

Nikhil Swaminathan — Tue, 24 Dec 2024 17:25:45 +0000

Today, AWS Amplify Hosting is launching new Firewall capabilities that will allow developers to protect and further secure their web applications. This is a direct integration with AWS WAF, allowing Amplify developers to connect a Web ACL directly to their Amplify hosted application. A web firewall is essential for professional developers to protect their applications from common web exploits, enhance security, and ensure compliance. It offers features like IP blocking/allowlisting, geo-restrictions, and protection against bot traffic. By providing WAF, Amplify customers can significantly improve their application’s security posture, mitigate risks, and maintain the integrity of their data and user experience.

AWS WAF is a full service offering that lets customers configure a set of rules, called a web access control list (web ACL), that allow, block, or monitor (count) web requests based on customizable web security rules and conditions that you define. When you integrate your Amplify Hosting app with AWS WAF, you gain more control over incoming traffic. To learn more about AWS WAF, see How AWS WAF Works in the Developer Guide.

If you are new to the AWS WAF service, Amplify Hosting has made it easy for developers to set up—

IP Blocking – Restrict web traffic by allowing or blocking requests from specified IP address ranges
Geo Restriction – allow or block access based on specific countries
Firewall protections – general firewall protections to protect against the most common vulnerabilities found in web applications, block IP addresses from potential threats based on Amazon internal threat intelligence, and protect against malicious actors discovering application vulnerabilities.
Disable Amplify URL – restrict access to the default Amplify generated amplifyapp.com domain (useful once you add a custom domain to prevent bots and search engines from crawling the domain)

As a reminder, protections enabled through the Amplify console, will be applied to an underlying Web ACL in your AWS account. For fine-grained rulesets, developers can leverage the WAF console rule builder.

Getting Started

To get started with associating WAF to your app, please follow our public documentation.

Availability and pricing

Firewall support is available today, in preview, in all AWS Regions that Amplify Hosting operates except for the opt-in regions. This integration falls under a WAF global resource, similar to CloudFront. Web ACLs can be attached to multiple Amplify Hosting apps, but they must reside in the same region.

During the preview, you will only incur utilization-based charges from the WAF service. At a glance, WAF charges $5/month per web ACL and $1 per rule among other charges. See WAF pricing. At a minimum, you will pay $7 for this integration assuming the 1 web ACL with 2 rules. In addition to the WAF usage charges, this integration will incur a flat fee per app from the Amplify service once it becomes generally available (GA). During the preview period, there will be no Amplify-specific charges. Pricing details will be announced at GA.

Next steps

Add firewall protections to your app today, by visiting the AWS Amplify console.

Working with AWS AppSync Events: Real-time Web Games with Chat

Michael Liendo — Tue, 26 Nov 2024 16:14:00 +0000

In this post, we’ll look at the core concepts needed to create an online version of a game where players try to match four of their tokens in a row. We’ll also see how AWS Amplify Gen 2 enables us to quickly connect to an AWS backend, and how AWS AppSync events allows players to send game updates in real-time through the use of WebSocket connections. By the end of this post, you’ll feel more confident in using AppSync events with authorization handled by Identity and Access Management (IAM), and better understand its role in today’s application development.

This post is the second post in a series on AppSync events. While the announcement post contains an overview of the service, the first post in this series on building with AppSync events can be found here.

Application Overview

I remember first teaching my kids how to win at the popular game tic-tac-toe. For those that don’t know, it’s what’s known as a “solved” game—there’s a way to guarantee you either win or draw. This was a great way for them to learn about algorithms, but admittedly, it made our time playing the game much less fun.

Fortunately, it was at that moment in their young age that I introduced them to the game four-in-a-row. While this is still a solved game, it’s more difficult to track and much easier to simply have a good time playing.

Instead of carrying around the game pieces and being within talking distance from the person we’re playing against, our application is fully online and supports chat functionality. However, instead of requiring players to login, we’ll instead ask for their username and generate a unique game code that they can share with the person they’re playing with.

By creating a game, you are player one (red), and by joining a game, you are the player two (yellow). To make sure the other player is there, players can chat with each other throughout the game.

The game will automatically stop once four of the same colored pieces are placed in a row, whether that’s vertically, horizontally, or diagonally. From there, players can choose to play a new game, or exit the game all together.

To view the code, along with a readme with instructions for hosting and running the code locally, view the repository.

Due to games being short-lived, there isn’t a need to persist data in a database. In addition, having real-time capabilities as the heart of this application, means there isn’t an API.

In fact, the entire backend is comprised of two core AWS services:

Amazon Cognito: A Cognito Identity pool provides scoped down permissions for unauthenticated access to our event API
AWS AppSync events: Standalone WebSocket endpoints that scale to millions of subscribers.

Creating an AWS AppSync event API with IAM Authorization

An AppSync event API can authorize calls using an API key, Cognito userpools, AWS Lambda, OIDC, or IAM. In the previous post, we saw how an API key can be configured, and in future posts we’ll showcase both Lambda and Cognito. However, for applications that need secure unauthenticated access, the IAM auth mode is a great choice and what we’ll discuss in this section.

With Amplify a thin layer over the AWS CDK is used when an Amplify project is scaffolded.

While this project uses AWS Amplify to create a fullstack application, it is not a required part of using AWS AppSync events

In the amplify/backend.ts file, you’ll notice that the we have auth configured:

const backend = defineBackend({ auth })

This one line of code setups ups our Cognito user pool and Cognito identity pool. Since the user pool keeps track of logged in users, we won’t make use of it, however, we the identity pool is key for our application since it will authorize our users that visit our app but haven’t logged in. To showcase how that comes together, we create a separate CDK stack to house services that extend Amplify:

const customResources = backend.createStack('custom-resources-connect4')

This is simply a logical way to group services together and nest them in our main backend stack. The items that we’ll add to this stack will all related to our event API:

const cfnEventAPI = new CfnApi(customResources, 'cfnEventAPI', {
    name: 'serverless-connect4',
    eventConfig: {
        authProviders: [{ authType: AuthorizationType.IAM }],
        connectionAuthModes: [{ authType: AuthorizationType.IAM }],
        defaultPublishAuthModes: [{ authType: AuthorizationType.IAM }],
        defaultSubscribeAuthModes: [{ authType: AuthorizationType.IAM }],
    },
})

new CfnChannelNamespace(customResources, 'cfnEventAPINamespace', {
    apiId: cfnEventAPI.attrApiId,
    name: 'game',
})

As shown above, we first create our event API by leveraging the L1 construct from the AWS CDK. In doing so, we provide it with the name of our API, and pass in an config that represents the auth providers we’ll accept, and which providers to allow for connecting, publishing, and subscribing.

Additionally, we create a root namespace called game. Client apps can connect to this namespace, and segments off of the root like /game/gameId/chat, to further specify the connection data they are interested in receiving.

Setting up an event API as infrasture-as-code (IAC), currently involves using an L1 construct. These directly correspond to their CloudFormation reference. The posts in this series will be updated once the higher-level L2 constructs are available.

By specifying, IAM as the authorization mode, we’ll need to attach a policy that allows calling our event API to an AWS service. The service we’ll use is our Cognito Identity pool:

backend.auth.resources.unauthenticatedUserIamRole.attachInlinePolicy(
    new Policy(customResources, 'AppSyncEventPolicy', {
        statements: [
            new PolicyStatement({
                actions: [
                    'appsync:EventConnect',
                    'appsync:EventPublish',
                    'appsync:EventSubscribe',
                ],
                resources: [`${cfnEventAPI.attrApiArn}/*`, `${cfnEventAPI.attrApiArn}`],
            }),
        ],
    })
)

Above, we simply use the unauthenticatedUserIamRole from our auth resource (Cognito) to directly attach a policy. Note that Cognito comes available with two roles: One for when users are logged in and stored in a user pool (authenticatedRole), and another for when they are not logged in and we want to use permissions from the identity pool (unauthenticatedRole).

With our event API configured and connected to Cognito, we’ll pass the related values to our frontend application so we can make use of them to connect, publish, and subscribe:

backend.addOutput({
    custom: {
        events: {
            url: `https://${cfnEventAPI.getAtt('Dns.Http').toString()}/event`,
            aws_region: customResources.region,
            default_authorization_type: AuthorizationType.IAM,
        },
    },
})

The format here is important as the Amplify JavaScript libraries have been updated to work with event API’s so long as custom data in the events object contains the url, aws_region, and default_authorization_type items.

Following the readme for this project, with our backend configured, a developer can now run npx ampx sandbox to deploy these resources to their AWS account.

Connecting to an AppSync event API with AWS Amplify

In our NextJS application, we have a home page located at app/page.tsx, and our game page at app/game/[code]/page.tsx.

As shown in the earlier screenshot, the home page simply captures the username of the user and in the event the user is creating a new game, it will generate a game code. From there, the user is taken to a dynamic route where the code is the game code.

As shown in the app/layout.tsx file, our Next.js application is already configured to use our AWS backend. The setup for this can be found in the components/configureAmplify.tsx file.

In the app/game/[code]/page.tsx we can see our application take shape. We connect to our WebSocket endpoint using the events.connect method from the aws-amplify/data library. The best place to do this is in a useEffect call since we want it to happen when the page first loads:

useEffect(() => {
    const subscribeToGameState = async (gameCode: string) => {
        const channel = await events.connect(`/game/${gameCode}`)
        const sub = channel.subscribe({
            next: (data) => {
                dispatch({ type: 'UPDATE_GAME_STATE', newState: data.event })
            },
            error: (err) => console.error('uh oh spaghetti-o', err),
        })
        return sub
    }

    const subPromise = subscribeToGameState(gameCode)
    return () => {
        Promise.resolve(subPromise).then((sub) => {
            console.log('closing the connection')
            sub.unsubscribe()
        })
    }
}, [gameCode])

Once we establish a connection to a particular channel, we can begin publishing and subscribing to it. For this use case, every time we receive a message from another player, we send the data to a reducer so that the new state can be rendered in our UI. This can be viewed in the app/game/[code]/GameState.ts file.

The last part of this useEffect file involves cleaning up any connections once the page is closed or navigated away from. This is connection by calling a subscriptions unsubscribe method. This helps avoid memory leaks that would otherwise slow down our application.

Publishing an event is how we pass data from one event source to a client. In our app, anytime a player places a piece on the board, clicks the “New Game” or “Reset Game” buttons, we publish and event containing those details to the /game/${gameCode} segment on our channel:

await events.post(`/game/${gameCode}`, {
    board: newState.board,
    currentPlayer: newState.currentPlayer,
    winner: newState.winner,
    gameOver: newState.gameOver,
})

As you can see, making use of an event API in your fullstack applications requires very little code!

When it comes to sending chat messages, the process is the same. Another useEffect call sets up a connection on the /game/${gameCode}/chat segment of our channel and whenever a user hits enter on the message input, a call to await events.post(`/game/${gameCode}/chat`,newMessage) is sent.

Conclusion

In this post, we discussed how an application can be brought to life when combining a modern frontend framework like Next.js, with the power of Amplify, and the ease and scalability of AppSync events. We also saw how Amplify can be extended beyond its core capabilities to use L1 constructs in the CDK.

AWS AppSync event API’s offer 250,000 event operations as part of its free tier and scales to millions of subscribers. As a fully managed service, developers now have a simple way to bring real-time capabilities to their apps without being locked to a specific API service.

To learn more about AWS AppSync events visit the documentation page. Also, if you’re interested in building games on AWS, there is currently an AWS Game Builder Challenge going on with $150,000 being awarded in prizes!

Working with AWS AppSync Events: Serverless WebSockets for Pub/Sub

Michael Liendo — Mon, 25 Nov 2024 22:56:19 +0000

AWS AppSync simplifies and manages connecting applications to events, data, and AI models. Now, with the new addition of AWS AppSync events, developers can create real-time experiences by publishing updates from any event source to subscribed clients over serverless WebSockets. AWS AppSync events offers a standalone Pub/Sub service that is not bound to GraphQL.

In this post we’ll start small by discussing a practical-yet-simple use case: a leaderboard. However, in future posts, we’ll showcase different authorization modes, data enrichment, and other scenarios where an event API would be useful.

Application Overview

Ephemeral leaderboards, as the name suggests, are simply leaderboards that do not persist data. While often used in fast, short-lived games, this architecture also applies to high-volume chat apps where what was said previously, is less important than what is said in the moment.

In case you’d like to implement this solution yourself, the code along with installation instructions can be cloned from this repo.

As seen in the screenshot below, our application is a single page that allows users to subscribe to all player position updates in realtime. To simulate an external source posting events, there’s an included “Simulate Scoring” button that will publish a series of updates over a quick interval.

It’s important to callout the simplicity of our architecture. There isn’t a need for an authZ service, an API, or a database. We’re simply using our event API inside of our web application.

Creating a Fullstack Application

The easiest way to set this up is in the AWS Console, however, this post will show how to create an Event API using AWS CDK L1 constructs.

Additionally, when it comes to building fullstack applications on AWS, AWS Amplify Gen 2 excels by offering a TypeScript-first experience that allows developers to drop down to CDK L2 and L1 constructs when needed.

AWS Amplify is used for simplification of publishing and subscribing, but is in no way a requirement for working with an event API

Get started initializing the frontend repository with Amplify Gen 2 by running the following command:

npm create amplify

Along with automatically installing the AWS CDK and Amplify JavaScript libraries, that command also creates an amplify directory where developers can add/modify their AWS backend.

Next, feel free to delete the auth and data folders since those reference Amazon Cognito and AWS AppSync GraphQL configurations that won’t be needed in this project.

Finally, we’ll cleanup the references to those services by updating the amplify/backend.ts so that it only contains the following:

import { defineBackend } from '@aws-amplify/backend'

const backend = defineBackend({})

Creating an event API using the AWS CDK

AWS Amplify is being used as our way of creating a fullstack CDK project. While Amplify abstracts several AWS services, the breadth of AWS offerings means there are many that fallback to using a CDK construct. This is enables developers to start using AWS services in their code as soon as those constructs are added.

We’ll take advantage of this feature by importing the L1 constructs used for to create an event API.

To get started, we’ll first create a separate stack of resources that will contain all of L1 constructs for our app. In the amplify/backend.ts file, add the following line of code:

const customResources = backend.createStack('custom-resources-leaderboard')

This is simply a logical container that we can use to group services.

The event API for our purposes will be broken up into 3 parts:

The API itself
The namespace(s) that the API can use for publishing and subscribing
The authorization mechanism needed to secure our API

import {
    AuthorizationType,
    CfnApi,
    CfnApiKey,
    CfnChannelNamespace,
} from 'aws-cdk-lib/aws-appsync'

// previous code...

// new code
const cfnEventAPI = new CfnApi(customResources, 'cfnEventAPI', {
    name: 'realtime-leaderboard',
    eventConfig: {
        authProviders: [{ authType: AuthorizationType.API_KEY }],
        connectionAuthModes: [{ authType: AuthorizationType.API_KEY }],
        defaultPublishAuthModes: [{ authType: AuthorizationType.API_KEY }],
        defaultSubscribeAuthModes: [{ authType: AuthorizationType.API_KEY }],
    },
})

new CfnChannelNamespace(customResources, 'cfnEventAPINamespace', {
    name: 'default',
    apiId: cfnEventAPI.attrApiId,
})

const cfnApiKey = new CfnApiKey(customResources, 'cfnEventAPIKey', {
    apiId: cfnEventAPI.attrApiId,
    description: 'realtime leaderboard demo',
})

Note that due to the recent release of AWS AppSync events, only L1 constructs are available. A less verbose construct (L2), is currently in development. This post will be updated once that becomes available.

Worth calling out is how this event API is currently using an API key for authorization. This is great for development purposes and testing, how the docs demonstrate how to use authorization modes that include AWS Identity and Access Management (IAM), Amazon Cognito, OIDC, and AWS Lambda permissions as well.

The last step in creating our backend resources, is to pass the resolved values to our frontend application. Fortunately the Amplify JavaScript libraries have been updated to easy connect, publish, and subscribe to events so long as the required values are passed in a specified format.

At the bottom of the amplify/backend.ts file, paste in the following:

backend.addOutput({
    custom: {
        events: {
            url: `https://${cfnEventAPI.getAtt('Dns.Http').toString()}/event`,
            api_key: cfnApiKey.attrApiKey,
            aws_region: customResources.region,
            default_authorization_type: AuthorizationType.API_KEY,
        },
    },
})

We’re now ready to deploy our backend. This will create an amplify_outputs.json file in the root of our project that contains the output needed to configure our frontend.

If you do not have an AWS Account set up, follow this guide from Amplify to setup your credentials.

Run the following command to deploy:

npx ampx sandbox
# npx ampx sandbox --profile your-profile-name

Connecting, Publishing, and Subscribing to an event API using AWS Amplify

This project’s repository is already configured with Amplify. This is shown in the components/configureAmplify.tsx file and made use of in the app/layout.tsx file.

All that’s left to do is test that our backend works by calling the related methods in our frontend.

By design, an AWS AppSync event does not need the Amplify libraries. It’s possible to configure a client using native WebSocket protocols. Amplify simply offers a convenient solution to prevent boilerplate.

In the app/page.tsx file, we’ll want to setup a connection to the channel we created in our backend called default. We also have the ability to create segments on our channel. To view this in action, inside of a useEffect method, we’ll connect to our application with the following code:

const channelConnect = async () => {
    try {
        const channel = await events.connect('/default/leaderboard')
        channelRef.current = channel

        channel.subscribe({
            next: handleNewData,
            error: (err) => console.log(err),
        })
    } catch (e) {
        console.log('Error connecting to channel: ', e)
    }
}

The events.connect function from Amplify is used to establish the connection to the default/leaderboard channel. This allows us to subscribe to any incoming data from that particular channel.

Whenever a user clicks the “Simulate Scoring” button, we publish events. While this is occurring from the same page, this could easily be added to an AWS Lambda function, or other source.

Publishing data is used with the events.post function, as shown with the following code in the app/page.tsx file where a random player is selected and given a random score update before posting to the event API:

const handlePublish = async () => {
    for (let i = 0; i <= 10; i++) {
        const randomItem =
            leaderboardData[Math.floor(Math.random() * leaderboardData.length)].id
        const randomScore = Math.floor(Math.random() * 20)

        await events.post('/default/leaderboard', {
            id: randomItem,
            score: randomScore,
        })
        await new Promise((resolve) => setTimeout(resolve, 100))
    }
}

Conclusion

In this post, we discussed how AWS AppSync events offer a simple Pub/Sub solution that can be used in both greenfield and brownfield applications. We also showcased how Amplify Gen 2 can be used to bring in L1 constructs, enabling developers to use newly announced features as infrastructure-as-code sooner.

While this application was a simple demonstration, it’s important to note that AWS AppSync events are applicable to high-throughput applications that can scale to millions of subscribers such as gaming, sports-betting, and live-auctioning.

Get started with 250,000 real-time event API operations per month for free. To learn more about AWS AppSync events, visit the documentation page. For more information on pricing, see the pricing page.

Building RAG-based applications with AWS Amplify AI Kit and Neon Postgres

Michael Liendo — Fri, 22 Nov 2024 20:07:15 +0000

Modern application development has shifted to include not just tooling that offers a great developer experience (DX), but a sensible balance between simply getting started and the path to production. It is this very sentiment that inspired the release of Amplify AI kit. This abstraction over common AI tasks like conversing with a large language model (LLM) and generating content from a prompt means developers have a faster time to market and avoid writing boilerplate code.

In this post, we’ll move beyond the getting-started experience and use a serverless Postgres database from Neon to retrieve product data instead of the default database model from Amplify. In doing so, we’ll simplify the code needed to converse with an LLM using retrieval-augmented generation (RAG).

Application Overview

A common appeal to application consumers is how AI is used to enhance an existing product, instead of competing with it. A simple and effective way of demonstrating that is to create a chatbot that customers can interact with. In a real-world scenario, this wouldn’t prevent a customer from shopping on their own, but provides guides them towards a purchase using natural language.

Architecturally speaking, whenever a user visits the application, they can chat with our LLM-powered bot. These models are trained on general data, though in our use case, we’d like it to know about our product data as well. Product information can change at any time, so it’s important to pull from the information in our database. This idea of choosing between general information or accessing specific data is powerful and accomplished with a tool (also known as “function-calling”).

An important concept to keep in mind, is that when an LLM chooses to use a tool, it is not making a call to your data on your behalf. It is simply passing along what tool would work best given the user’s prompt. From there, applications decide what function they’d like invoke.

The response from that function is then sent back to the LLM, and formatted as natural language to the end-user.

As one might imagine, orchestrating this pattern yourself can not only be tedious, but can lead to errors. Fortunately, this undifferentiated heavy-lifting is what Amplify AI kit provides by default.

Specifically, our project will use Amazon Bedrock with the Claude 3.5 Haiku LLM since this model comes with tool support. Amplify will allow us to specify a tool that corresponds to one of our databases. In our case, that will be our Neon Postgres database containing our product information.

Creating Serverless Postgres Databases with Neon

The ability to connect to existing datasourcesmeans developers can use the power of Amplify’s schema introspection outside of Amazon DynamoDB, the default database, to have CRUD operations generated on their behalf. Setting up a Neon database is straightforward. After creating an account, you’re prompted to create a project.

Neon supports branch-based projects, similar to git. These are copies of the main branch. In my case, I have the option to create a branch called dev/mtliendo . This is recommended, but not required. In either case, you’ll want to make sure to copy the connection string for that branch as it will be important in the following sections.

Our default database is now set up, however it doesn’t yet contain any tables. More specifically, our table schema has yet to be defined. You’ll be saddened to find out that I don’t know how to write SQL. Fortunately, Neon solves this with their “Generate with AI” feature. By chatting with their LLM about what I’d like to do and a response will be generated for me.

In their SQL editor, I write the following:

Create a table schema called “Products”. Each product has a random id, an “updated at” field that is a date-time, a “created at” field that is a date-time, a “price in cents” field that is a number, a “name”, and a “description”.

After running the prompt, I’m presented with the following response:

CREATE TABLE Products (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    price_in_cents INTEGER NOT NULL,
    name VARCHAR(255) NOT NULL,
    description TEXT
);

From there, I have option to make changes to the code, and run the command once everything once I’m comfortable with the syntax.

To verify everything is setup as expected, clicking on the “Tables” link in the sidebar will allow us to verify the schema, as well as populating our database.

For this project, I’ve added several items to the database. Also, be sure to copy the connection string to our database since we’ll be needing that in following section. The connection string can be found in the “Overview” section of the sidebar.

Enhancing Amplify Gen 2 with AI Kit

AWS Amplify is the easiest way to connect your frontend applications to a backend powered by AWS. Assuming an app using a JavaScript framework like NextJS has already been created, scaffold Amplify files by running the following command in the root of the project:

npm create amplify

This will install Amplify’s dependencies as well as create an amplify directory. Before modifying the code in that directory, we’ll install a few other dependencies needed for Amplify AI kit:

npm i @aws-amplify/ui-react @aws-amplify/ui-react-ai

These are UI components that we’ll make use of shortly.

Before doing so, we’ll let Amplify introspect our database with the products table so we can use that in our backend. The first step is to store our connection string as a secret. This secret is stored in a Parameter Store in AWS Systems Manager. Fortunately, Amplify provides a simple way to doing so.

In your terminal, run the following command:

npx ampx sandbox secret set SQL_CONNECTION_STRING

This sets a secret value of SQL_CONNECTION_STRING and prompts for the value. From here, paste in the connection string copied from Neon and press enter.

This section assumes you already have AWS Amplify configured on your local machine. If you need to configuration Amplify, please refer to the documentation for instructions.

Once the secret is stored, we can instruct Amplify to introspect our database and create CRUD operations that we can make use of in our frontend application:

npx ampx generate schema-from-database --connection-uri-secret SQL_CONNECTION_STRING --out amplify/data/schema.sql.ts

Running this command will create a schema.sql.ts file in the amplify/data folder. It’s important to not modify this file as it’s managed by Amplify. Once that command is ran, the file should look similar to the below screenshot:

Amplify uses this file to map our Postgres database to a format that works with its a.model method.

Check out the documentation if you want to learn what Amplify does behind-the-scenes to make this work.

import { type ClientSchema, defineData, a } from '@aws-amplify/backend'
import { schema as generatedSqlSchema } from './schema.sql'

const sqlSchema = generatedSqlSchema.setAuthorization((models) => [
    models.items.authorization((allow) => [allow.authenticated().to(['read'])]),
])
const schema = a.schema({
    chat: a
        .conversation({
            aiModel: a.ai.model('Claude 3.5 Haiku'),
            systemPrompt:
                'You are a helpful assistant, that focuses on selling and upselling merchandise',
            tools: [
                a.ai.dataTool({
                    name: 'MerchQuery',
                    description:
                        'Search for questions regarding merchandise, shopping apparel, and item prices.',
                    model: a.ref('items'), //! This refers to the name of our table
                    modelOperation: 'list',
                }),
            ],
        })
        .authorization((allow) => allow.owner()),
})

const combinedSchema = a.combine([sqlSchema, schema])

export type Schema = ClientSchema<typeof combinedSchema>

export const data = defineData({ schema: combinedSchema })

Now that our Neon database is in our application, we can import that into the amplify/data/resource.ts file and combine it with the conversation capabilities of Amplify AI kit. Let’s breakdown what is happening in this file:

Line 4: Here we are assigning authorization rules on our products table from Neon. In this case, only signed in users can perform read operations against it.
Line 8: We create an identifier called chat. This is a conversation bot that takes in, at a minimum, the name of the LLM, and a prompt on how it should behave. Worth nothing that the model names are typed and are available in Intellisense.
Line 13: We enhance our bot by giving it a tool. The name and description are up to us to define, whereas the model must refer to the name of our Neon database. Currently the only supported modelOperation is list.
Line 22: This line offers insight into what is happening behind the scenes. A DynamoDB table keeps track of a signed in users conversation history.

By putting together all of these elements, we have a fully-managed solution for securely conversing with an LLM that is aware of the items in our database.

To test our solution, we’ll first deploy our AWS backend by running the following command:

npx ampx sandbox

Once deployed, we can import our Amplify configuration and configure our client-side application to make use of the config, UI components, and hooks provided by Amplify:

import { generateClient } from 'aws-amplify/api'
import { Schema } from '@/amplify/data/resource'
import { useEffect } from 'react'
import { Amplify } from 'aws-amplify'
import awsconfig from '@/amplify_outputs.json'
import { withAuthenticator } from '@aws-amplify/ui-react'
import { AIConversation, createAIHooks } from '@aws-amplify/ui-react-ai'
import '@aws-amplify/ui-react/styles.css'

Amplify.configure(awsconfig)

const client = generateClient<Schema>()
const { useAIConversation } = createAIHooks(client)

Once configured, the entire frontend with chat, conversational awareness, streaming, loading states and authentication, can be set up in around 20 lines of code:

function Home() {
    const [
        {
            data: { messages },
            isLoading,
        },
        handleSendMessage,
    ] = useAIConversation('chat')

    return (
        <div className="flex justify-center items-center m-10 max-w-screen-md">
            <AIConversation
                avatars={{ user: { username: 'Focus Otter' } }}
                messages={messages}
                handleSendMessage={handleSendMessage}
                isLoading={isLoading}
                variant="bubble"
                welcomeMessage="Hello! I'm your helpful storefront assistant. Feel free to ask me questions about my merch!"
            />
        </div>
    )
}

export default withAuthenticator(Home)

Feel free to compare the code above, with the first screenshot in this post. The new AIConversation component of Amplify AI kit provides a full chat UI while still exposing various props to further customize to your specific needs.

Conclusion

In this post we discussed some of the complexities of building out fullstack applications that support conversing to an LLM using retrieval-augmented generation (RAG). We then saw how AWS Amplify’s new AI kit greatly simplifies this experience by abstracting away boilerplate allowing developers to focus on the parts that truly make the application different. As we saw, this ease in setup doesn’t come at the expense of extensibility. We proved that by creating a Postgres database from Neon and using that alongside our tool.

Amplify AI kit is yet another step forward in building scalable, secure fullstack applications. To get stared with Amplify AI kit in your own application, visit the documentationand get started today.

Build a Travel Planner with React Native, AWS Amplify, and Amazon Bedrock Knowledge Base

Muhammed Salih Güler — Fri, 22 Nov 2024 17:46:12 +0000

With the announcement of the Amplify AI kit, we learned how to build custom UI components, conversation history and add external data to the conversation flow. In this blog post, we will learn how to build a travel planner application using React Native. The application will generate responses using Retrieval Augmented Generation (RAG) and Large Language Models (LLMs) based on knowledge bases.

To equip large language models (LLMs) with up-to-date and proprietary information, you can use RAG, a technique that fetches data from company data sources and enriches the prompt to provide more relevant and accurate responses. With Amazon Bedrock Knowledge Bases, you can give FMs and agents contextual information from your company’s private data sources for RAG to deliver more relevant, accurate, and customized responses.

You can use the backend building and creating Knowledge Bases and RAG parts of this article with any web framework. However, this tutorial assumes you are building your applications with React Native and will explain the frontend code accordingly.

Building an Amplify App

For creating an Amplify application, we have to run the create-amplify command at the root folder of your application:

npm create amplify@latest -y

This will install the necessary dependencies for our project on the AWS Amplify. If we open our project now on our IDE, we can see a new folder called amplify:

The folder has a simple to-do application with email authentication. We will define the resources for the related categories under its own folders. E.g. For authentication we will update the auth/resource.ts file.

Let’s add the authentication flow for our users to sign up for a personalized experience. First open the auth/resource.ts file and update it like the following:

import { defineAuth } from "@aws-amplify/backend";

export const auth = defineAuth({
  loginWith: {
    email: {
      verificationEmailSubject: "Welcome to Travel Advisor! Verify your email!",
      verificationEmailBody: (code) => `Here is your verification code: ${code()}`,
      verificationEmailStyle: "CODE",
    },
  },
  userAttributes: {
    preferredUsername: {
      mutable: true,
      required: true,
    },
  },
});

This will customize the user confirmation email and ask users to create a username for registration. Now we will do the initial deployment through an Amplify sandbox. You can use a personal cloud sandbox environment that provides an isolated development space to rapidly build, test, and iterate on a fullstack app. Each developer on your team can use their own disposable sandbox environment connected to cloud resources. Let’s do our first deployment. Before we do that, update the backend.ts with the following:

import { defineBackend } from "@aws-amplify/backend";
import { auth } from "./auth/resource";
import { data } from "./data/resource";

/**
 * @see https://docs.amplify.aws/react/build-a-backend/ to add storage, functions, and more
 */
defineBackend({
  auth,
});

Commenting out the data resource it will prevent it from deploying for now. Run the following command to start a sandbox environment for auth:

npx ampx sandbox

Next step is to implement the frontend. For this, we will be using Amplify UI Components. Amplify UI is a collection of accessible, themeable, performant components that can connect directly to the cloud. With a few lines of code, we can turn complicated tasks to trivial tasks.

First install the necessary libraries for using the UI libraries.

npm install --force @aws-amplify/ui-react-native aws-amplify @aws-amplify/react-native react-native-safe-area-context @react-native-community/netinfo @react-native-async-storage/async-storage react-native-get-random-values

The force flag is added due to the conflict of the ui library with latest version of react native.

Install the pods for iOS to bind the libraries to native libraries.

npx pod-install

After that update the App component in the App.tsx with the following:

import outputs from "./amplify_outputs.json";
Amplify.configure(outputs);

const SignOutButton = () => {
  const { signOut } = useAuthenticator();
  return (
    <TouchableOpacity onPress={signOut}>
      <MaterialIcons name="exit-to-app" size={32} />
    </TouchableOpacity>
  );
};

export default function App() {
  const [username, setUsername] = useState("");
  useEffect(() => {
    const fetchUsername = async () => {
      const attributes = await fetchUserAttributes();
      const username = attributes.preferred_username ?? "";
      setUsername(username);
    };
    fetchUsername();
  }, []);
  return (
    <Authenticator.Provider>
      <Authenticator>
        <SafeAreaView style={styles.container}>
          <KeyboardAvoidingView behavior={"height"} style={styles.container}>
            <View style={styles.header}>
              <Text style={styles.headerIcon}>✈</Text>
              <Text style={styles.headerText}>Travel Advisor</Text>
              <SignOutButton />
            </View>
          </KeyboardAvoidingView>
        </SafeAreaView>
      </Authenticator>
    </Authenticator.Provider>
  );
}

Here are the major changes that happened:

Through the fetchUserAttributes we are getting the extra attributes we defined.
With the useAuthenticator hook, we are calling the signOut button.
Authenticator and Authenticator.Provider components will create the UI for authentication and control the authentication flow.

Now the authentication flow is ready to be tested. The next step is to implement the AI capabilities.

Amplify’s new AI capabilities make it easier to work with generative AI. For example, if we want to generate our components, let’s use the generation capability to see what it would look like. Open the data/resource.ts file and update it with the following:

import { type ClientSchema, a, defineData } from "@aws-amplify/backend";

const schema = a.schema({
  generateDestination: a
    .generation({
      aiModel: a.ai.model("Claude 3.5 Sonnet"),
      systemPrompt: `
You are an advanced travel assistant with comprehensive knowledge about global destinations, including their geography, climate patterns, historical significance, tourist attractions, and cost of living. Your task is to analyze the following information: {{input}}
Based solely on this input, determine the single best city on Earth for the user. Your response should be concise and definitive, presenting only the chosen city along with comprehensive information about their geography, climate patterns, historical significance, tourist attractions, and cost of living and why it's the ideal match. Do not ask for additional information or clarification. Provide your recommendation based exclusively on the given details.
      `,
    })
    .arguments({
      input: a.string().required(),
    })
    .returns(a.string().required())
    .authorization((allow) => [allow.authenticated()]),
});

export type Schema = ClientSchema<typeof schema>;

export const data = defineData({
  schema,
  authorizationModes: {
    defaultAuthorizationMode: "userPool",
  },
});

Thanks to this, we can generate an answer for our questions. If we open our App.tsx file and call the generateDestination like the following from anywhere we can now generate a destination:

const { data, errors } = await client.generations.generateDestination({
    input: inputText,
});

Creating a Knowledge Base

The information is highly depending on the strength of our prompt. Also the information is around the AI Model and it’s properties. However, Amazon Bedrock Knowledge Bases can help us give more information to our prompt.

We will create a basic knowledge base like the following:

City	Country	Population	Description	Financial Hub	Is Capital?	Ranking
Tokyo	Japan	9.73 Million	Tokyo is the capital of Japan. It blends ultramodern skyscrapers with historic temples and gardens. Known for its unique pop culture, advanced technology, and exquisite cuisine. Home to the world’s largest fish market and busiest pedestrian crossing.	Yes	Yes	1
Istanbul	Turkey	15.46 Million	Istanbul straddles Europe and Asia across the Bosphorus Strait. Rich in history, it showcases Byzantine and Ottoman architecture. Famous for its bazaars, Turkish baths, and diverse culinary scene. The Hagia Sophia and Blue Mosque are iconic landmarks.	Yes	No	5
Berlin	Germany	3.7 Million	Berlin is Germany’s capital, known for its vibrant arts scene, modern architecture, and complex history. Home to world-class museums, diverse neighborhoods, and remnants of the Berlin Wall. Famous for its techno clubs, street art, and multicultural cuisine.	No	Yes	2
New York	USA	8.8 Million	New York City is a global hub for finance, arts, and culture. Home to iconic landmarks like the Statue of Liberty and Empire State Building. Known for its diverse neighborhoods, Broadway theaters, world-class museums, and culinary diversity. Rich in history from colonial times to present.	Yes	No	4
Prague	Czech Republic	1.3 Million	Prague is the capital of the Czech Republic, known as “The City of a Hundred Spires.” Famous for its medieval architecture, including Prague Castle and Charles Bridge. Renowned for its beer culture, classical music heritage, and well-preserved Old Town Square.	No	Yes	3

Go to Amazon S3 Console now and click the Create bucket button:

Select a unique name for our bucket and leave all as default selection. Next upload our file to our S3 bucket:

Now we can create our knowledge bases. First, open the AWS Console and go to Amazon Bedrock page. Once we land on the page, select the Knowledge bases from the left menu.

Click on the Create knowledge base button. Leave all of the default values (double check that S3 is selected) and click on next. In the next page, select the data source from our S3 buckets:

Select an embedding model to convert our data:

We will also let Amazon create a vector store on our behalf or select a previously created store to allow Bedrock to store, update and manage embeddings of our data. Now we can start creating our knowledge base.

The default setup for an Amazon Bedrock Knowledge Base is OpenSearch Serverless which has a default cost whether or not you use it. You can get an AWS bill if you are not careful. If you are just testing this out make sure to turn off the OpenSearch Serverless instance when you are done.

We can test our knowledge base already in the console and see if the data is working as expected.

Now it is time to use the knowledge base in our application.

Using the Created Knowledge Base

First let’s do some clean-up. We have to create our knowledge base aware conversation and connect that to a AppSync Resolver to communicate with the database. Update the data/resource.ts file with the following:

import { type ClientSchema, a, defineData } from "@aws-amplify/backend";

const schema = a.schema({
  chat: a
    .conversation({
      aiModel: a.ai.model("Claude 3 Haiku"),
      systemPrompt: `You are a helpful assistant.`,
      tools: [
        a.ai.dataTool({
          name: "DestinationKnowledgeBase",
          description:
            "A knowledge base to be checked about everything related to the cities.",
          query: a.ref("searchDestination"),
        }),
      ],
    })
    .authorization((allow) => allow.owner()),
  searchDestination: a
    .query()
    .arguments({ input: a.string() })
    .handler(
      a.handler.custom({
        dataSource: "DestinationKnowledgeBaseDataSource",
        entry: "./bedrockresolver.js",
      })
    )
    .returns(a.string())
    .authorization((allow) => [allow.authenticated()]),
});

export type Schema = ClientSchema<typeof schema>;

export const data = defineData({
  schema,
  authorizationModes: {
    defaultAuthorizationMode: "userPool",
  },
});

This will add the earlier created knowledge base to the conversation as tool. The description will be the explanatory text for LLM to interact with the knowledge base. For adding a js resolver, create a file called bedrockresolver.js and paste the following:

export function request(ctx) {
  const { input } = ctx.args;
  return {
    resourcePath: "/knowledgebases/<knowledge-base-id>/retrieve",
    method: "POST",
    params: {
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        retrievalQuery: {
          text: input,
        },
      }),
    },
  };
}

export function response(ctx) {
  return JSON.stringify(ctx.result.body);
}

This will get the knowledge base with the provided id to the conversation’s context through AppSync. Lastly, we have to update the policies from lambda to data source in the backend.ts file:

import { defineBackend } from "@aws-amplify/backend";
import { auth } from "./auth/resource";
import { data } from "./data/resource";
import * as iam from "aws-cdk-lib/aws-iam";

const backend = defineBackend({
  auth,
  data,
});

const KnowledgeBaseDataSource =
  backend.data.resources.graphqlApi.addHttpDataSource(
    "DestinationKnowledgeBaseDataSource",
    "https://bedrock-agent-runtime.<region>.amazonaws.com",
    {
      authorizationConfig: {
        signingRegion: "<region>",
        signingServiceName: "bedrock",
      },
    }
  );

KnowledgeBaseDataSource.grantPrincipal.addToPrincipalPolicy(
  new iam.PolicyStatement({
    resources: [
      "arn:aws:bedrock:<region>:<user-id>:knowledge-base/<knowledge-base-id>",
    ],
    actions: ["bedrock:Retrieve"],
  })
);

Lastly update your UI like the following to handle the streaming:

import React, { useEffect, useState } from "react";
import {
  StyleSheet,
  Text,
  View,
  TextInput,
  TouchableOpacity,
  SafeAreaView,
  KeyboardAvoidingView,
  FlatList,
  ActivityIndicator,
} from "react-native";
import MaterialIcons from "@expo/vector-icons/MaterialIcons";
import { Authenticator, useAuthenticator } from "@aws-amplify/ui-react-native";
import { fetchUserAttributes } from "aws-amplify/auth";
import { Amplify } from "aws-amplify";
import { Schema } from "./amplify/data/resource";
import { generateClient } from "aws-amplify/data";

import outputs from "./amplify_outputs.json";
import { createAIHooks } from "@aws-amplify/ui-react-ai";

Amplify.configure(outputs);
const client = generateClient<Schema>();
const { useAIConversation } = createAIHooks(client);

const HomePage = () => {
  const [username, setUsername] = useState("");
  const [inputText, setInputText] = useState("");

  const [
    {
      data: { messages },
      isLoading,
    },
    handleSendMessage,
  ] = useAIConversation("chat");

  const handleSend = () => {
    handleSendMessage({
      content: [{ text: inputText }],
    });
    setInputText("");
  };
  useEffect(() => {
    const fetchUsername = async () => {
      const attributes = await fetchUserAttributes();
      const fetchedUsername = attributes.preferred_username ?? "";
      setUsername(fetchedUsername);
    };
    fetchUsername();
  }, []);
  return (
    <SafeAreaView style={styles.container}>
      <KeyboardAvoidingView behavior={"height"} style={styles.container}>
        <View style={styles.header}>
          <Text style={styles.headerIcon}>✈</Text>
          <Text style={styles.headerText}>Travel Advisor</Text>
          <TouchableOpacity
            onPress={() => {
              const { signOut } = useAuthenticator();
              signOut();
            }}
          >
            <MaterialIcons name="exit-to-app" size={32} />
          </TouchableOpacity>
        </View>
        <FlatList
          data={messages}
          keyExtractor={(message) => message.id}
          renderItem={({ item }) =>
            item.content
              .map((content) => content.text)
              .join("")
              .trim().length == 0 ? (
              <View style={styles.loadingContainer}>
                <ActivityIndicator />
              </View>
            ) : (
              <ChatMessage
                text={item.content
                  .map((content) => content.text)
                  .join("")
                  .trim()}
                isUser={item.role == "user"}
                userName={item.role == "user" ? username : "Travel Advisor"}
              />
            )
          }
          contentContainerStyle={styles.chatContainer}
          ListEmptyComponent={() => (
            <View style={styles.emptyContainer}>
              <Text style={styles.emptyText}>
                Start a conversation by sending a message below!
              </Text>
            </View>
          )}
        />
        <View style={styles.inputContainer}>
          <TextInput
            style={styles.input}
            value={inputText}
            onChangeText={setInputText}
            placeholder="Describe your dream travel..."
            multiline={true}
            numberOfLines={3}
          />
          <TouchableOpacity
            style={[styles.sendButton, isLoading && styles.sendButtonDisabled]}
            onPress={handleSend}
            disabled={isLoading}
          >
            <Text style={styles.sendButtonText}>Send</Text>
          </TouchableOpacity>
        </View>
      </KeyboardAvoidingView>
    </SafeAreaView>
  );
};

interface Message {
  text: string;
  isUser: boolean;
  userName: string;
}

const ChatMessage = ({ text, isUser, userName }: Message) => (
  <View>
    <View
      style={[
        styles.messageBubble,
        isUser ? styles.userMessage : styles.aiMessage,
      ]}
    >
      <Text style={styles.messageText}>{text}</Text>
    </View>
    <Text style={[styles.nameText, isUser ? styles.userName : styles.aiName]}>
      {userName}
    </Text>
  </View>
);

export default function App() {
  return (
    <Authenticator.Provider>
      <Authenticator>
        <HomePage />
      </Authenticator>
    </Authenticator.Provider>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: "#FFFFFF",
  },
  header: {
    flexDirection: "row",
    alignItems: "center",
    padding: 15,
    borderBottomWidth: 1,
    borderBottomColor: "#E0E0E0",
  },
  headerIcon: {
    fontSize: 24,
    marginRight: 10,
  },
  headerText: {
    fontSize: 20,
    fontWeight: "bold",
    flex: 1,
  },
  signOutIcon: {
    fontSize: 24,
  },
  chatContainer: {
    padding: 10,
  },
  messageBubble: {
    maxWidth: "80%",
    padding: 10,
    borderRadius: 20,
    marginBottom: 5,
  },
  aiMessage: {
    alignSelf: "flex-start",
    backgroundColor: "#F0F0F0",
  },
  userMessage: {
    alignSelf: "flex-end",
    backgroundColor: "#DCF8C6",
  },
  messageText: {
    fontSize: 16,
  },
  nameText: {
    fontSize: 12,
    marginBottom: 10,
  },
  userName: {
    alignSelf: "flex-end",
    color: "#4CAF50",
  },
  aiName: {
    alignSelf: "flex-start",
    color: "#666666",
  },
  inputContainer: {
    flexDirection: "row",
    padding: 10,
    borderTopWidth: 1,
    borderTopColor: "#E0E0E0",
  },
  input: {
    flex: 1,
    backgroundColor: "#F0F0F0",
    borderRadius: 20,
    paddingHorizontal: 15,
    paddingVertical: 10,
    fontSize: 16,
  },
  sendButton: {
    backgroundColor: "#4CAF50",
    paddingHorizontal: 12,
    borderRadius: 20,
    justifyContent: "center",
    alignItems: "center",
    marginLeft: 10,
  },
  sendButtonDisabled: {
    backgroundColor: "#A5D6A7",
  },
  sendButtonText: {
    color: "#FFFFFF",
    fontSize: 24,
  },
  loadingContainer: {
    alignSelf: "flex-start",
    marginBottom: 10,
  },
  loadingText: {
    fontSize: 24,
    color: "#666666",
  },
  emptyContainer: {
    flex: 1,
    justifyContent: "center",
    alignItems: "center",
    height: 500,
  },
  emptyText: {
    fontSize: 16,
    color: "#666666",
    textAlign: "center",
  },
});

The most important part of the code above is the following:

const { useAIConversation } = createAIHooks(client);
- Creates a react hook to fetch conversation information, listen to messages and send messages to your conversation

const [
  {
    data: { messages },
    isLoading,
  },
  handleSendMessage,
] = useAIConversation("chat");

Listens to the messages and sends messages

Overall the app will use the retrieved information and show it on the screen as it is retrieved real-time.

Now if you deploy your sandbox again, you will see that your application will call the knowledge base with the provided information. Now run the application and see how it looks:

Cleanup

In this blog post you have learned how you can call an LLM through an Amazon Bedrock Knowledge Base. Before wrapping things up, make sure you delete your resources in the Amplify sandbox by running:

npx ampx sandbox delete -y

Also, the vector databases can be expensive, once you are done testing the application, make sure to delete your instances in the Amazon OpenSearch Serverless dashboard.

Wrapping Up

In this blog post, you learned how you can create your knowledge base and use it with your application. If you would like to learn more take a look at our starting guide for AI. In it we go over in detail how to get started with Amplify AI kit.