Tutorials
This guide covers deploying your Next.js website built with Agility CMS to AWS Amplify Hosting. AWS Amplify supports both Static Site Generation (SSG) and Server-Side Rendering (SSR) for Next.js applications.
AWS Amplify Hosting provides a fully managed hosting service for Next.js applications with built-in CI/CD, global CDN, and support for both static and dynamic Next.js features.
Most developers deploying Agility CMS websites to AWS Amplify will be starting from an existing Next.js project:
These starters already include proper Next.js configuration, Agility CMS integration, and the necessary build scripts. You'll still need to configure your environment variables, but you won't need to set up Next.js from scratch or configure Agility CMS integration manually.
Before you begin, ensure you have:
If you don't already have an Agility CMS instance set up:
GUID (Instance ID)Live API Key (for production)Preview API Key (for development/preview)Security Key (for webhooks)You'll need these credentials for both local development and AWS Amplify deployment configuration.
AWS Amplify supports two deployment modes for Next.js:
For fully static sites using Static Site Generation only. This is the simplest deployment option but has limitations.
Supported Features:
Limitations:
AWS Amplify's managed Next.js hosting supports all Next.js features including SSR, API routes, and ISR.
Supported Features:
Ensure your package.json has the required scripts:
{
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start"
}
}
Note: The Agility CMS Next.js starters already include proper Next.js configuration for AWS Amplify deployment, including image optimization settings that work with Agility's Edge CDN.
Important: Only follow this step if you're deploying as a fully static site. If you're using managed Next.js hosting (recommended), skip this section.
If you're deploying your Next.js site as a fully static site, you need to make a few changes:
Update the build script in your package.json:
{
"scripts": {
"build": "next build && next export"
}
}
Replace next/image components with AgilityPic from @agility/nextjs:
// ❌ Do NOT use next/image
import Image from 'next/image'
<Image src={image.url} alt={image.label} width={image.width} height={image.height} />
// ✅ Use AgilityPic instead (recommended - simplest option)
import { AgilityPic } from "@agility/nextjs";
<AgilityPic
src={image.url}
alt={image.label}
width={image.width}
height={image.height}
/>
// Alternative: Use AgilityImage if you need next/image features
import { AgilityImage } from "@agility/nextjs";
<AgilityImage src={image.url} alt={image.label} width={image.width} height={image.height} />
Important for Agility CMS: Use
AgilityPicfrom@agility/nextjsfor all Agility CMS images. AgilityPic is a simple wrapper around the<picture>tag that automatically handles optimization and caching at the Edge via Agility's CDN - and it doesn't require JavaScript! This provides better performance thannext/image.
Update getStaticPaths fallback in /pages/[...slug].js:
export async function getStaticPaths() {
return {
paths: [],
fallback: false // Changed from 'blocking' or true
}
}
⚠️ CRITICAL: ALL image optimization and caching for Agility websites is handled at the Edge via Agility's CDN. You should NOT use
next/imagefor Agility CMS images. Instead, use theAgilityPiccomponent from@agility/nextjs- it's simpler and doesn't require JavaScript!
Why AgilityPic instead of next/image?
<picture> tag - no JavaScript required<picture> tagUsing AgilityPic (Recommended - Simplest Option):
import { AgilityPic } from "@agility/nextjs";
// Simple usage
<AgilityPic
src={fields.image.url}
alt={fields.image.label}
width={fields.image.width || 768}
height={fields.image.height || 512}
/>
// With styling
<AgilityPic
src={fields.image.url}
alt={fields.image.label}
width={768}
height={512}
className="rounded-lg object-cover object-center"
/>
Alternative: AgilityImage (if you need Next.js Image component features):
import { AgilityImage } from "@agility/nextjs";
// AgilityImage wraps next/image - use only if you need next/image specific features
<AgilityImage src={fields.image.url} alt={fields.image.label} width={768} height={512} />
No next.config.js image configuration needed - AgilityPic handles everything automatically through Agility's CDN.
Open AWS Amplify Console:
Create a New App:
Select Repository and Branch:
main or master)AWS Amplify will auto-detect Next.js and configure build settings automatically. Review and confirm:
npm run build (or yarn build).next (for managed Next.js hosting) or out (for static export)Click "Advanced settings" to configure:
Environment Variables - Add your Agility CMS credentials:
AGILITY_GUID=xxx
AGILITY_API_FETCH_KEY=xxx
AGILITY_API_PREVIEW_KEY=xxx
AGILITY_SECURITY_KEY=xxx
AGILITY_LOCALES=en-us
Note: If you have multiple locales, comma-separate them without spaces (e.g.,
en-us,fr-ca)
Build Image Settings (if needed):
18.x or laterCaching (optional):
node_modules and .next directories to speed up buildsClick "Save and deploy" to start your first deployment.
AWS Amplify will:
The initial deployment typically takes 3-5 minutes. You can monitor progress in the Amplify console.
Once deployment completes, AWS Amplify will provide you with a default domain:
https://<branch-name>.<app-id>.amplifyapp.comhttps://main.d1m7bkiki6tdw1.amplifyapp.comPreview deployments allow you to preview changes before merging pull requests or publishing content.
Once AWS Amplify provides preview URLs, configure them in Agility CMS:
Get Preview URL from AWS Amplify:
https://pr-123.<app-id>.amplifyapp.com)Set Up Preview Deployment in Agility:
Now, when you create a pull request, AWS Amplify will automatically create a preview deployment, and you can preview your Agility CMS content changes in that preview environment.
You can configure AWS Amplify to automatically rebuild your site when content is published in Agility CMS.
main or master)In Agility CMS, go to Settings > Webhooks
Click "Add webhook"
Give your webhook a name (e.g., "AWS Amplify Production")
Paste the webhook URL from AWS Amplify
Configure webhook events:
Click "Save"
Test the webhook by clicking "Send test payload" to verify the connection
Now, whenever you publish content in Agility CMS, AWS Amplify will automatically rebuild and redeploy your site.
AWS Amplify provides a default amplifyapp.com domain, but you can connect your own custom domain.
example.com)Here's a complete reference for Agility CMS environment variables needed in AWS Amplify:
AGILITY_GUID=xxx
Your Agility CMS instance GUID. Found in Settings > API Keys in Agility CMS.
AGILITY_API_FETCH_KEY=xxx
Your Live API Key for fetching published content. Found in Settings > API Keys in Agility CMS.
AGILITY_API_PREVIEW_KEY=xxx
Your Preview API Key for fetching draft content. Found in Settings > API Keys in Agility CMS.
AGILITY_SECURITY_KEY=xxx
Your Security Key for webhook authentication. Found in Settings > API Keys in Agility CMS.
AGILITY_LOCALES=en-us
Comma-separated list of locale codes (without spaces). Examples:
en-usen-us,fr-ca,es-esAGILITY_SITEMAP=website
The sitemap reference name if you have multiple sitemaps. Defaults to website if not specified.
Set environment variables in two places:
AWS Amplify Console → App settings → Environment variables:
GitHub Secrets (if using GitHub Actions or custom build scripts):
Issue: Build fails with "Invalid API Key" or "Instance not found"
Solution:
AGILITY_GUID and API keys are correct in AWS Amplify environment variablesnpm run build with the same environment variablesIssue: Build fails with "Cannot find module" errors
Solution:
package.json has all required dependenciesnode_modules is not in .gitignore (or ensure dependencies are installed during build)Issue: Build timeout
Solution:
node_modules in Amplify build settingsoutput: 'standalone' in next.config.js to reduce build sizeIssue: Site shows 404 errors for dynamic routes
Solution:
next.config.jsgetStaticPaths returns all necessary pathsIssue: Images not loading
Solution:
next/image - AgilityPic handles all image optimization automaticallynext/image with AgilityPic from @agility/nextjs (or AgilityImage if you need next/image features)@agility/nextjs package is installed and AgilityPic is imported correctlyIssue: Preview mode not working
Solution:
AGILITY_API_PREVIEW_KEY is set correctly in environment variablesIssue: Webhooks not triggering rebuilds
Solution:
In AWS Amplify build settings, enable caching for:
node_modules directory.next directory (if not using standalone output)This significantly speeds up subsequent builds.
For smaller deployment sizes, enable standalone output in next.config.js:
module.exports = {
output: 'standalone',
}
This creates a minimal production build with only necessary files.
⚠️ CRITICAL for Agility CMS: ALL image optimization for Agility websites is done at the Edge (via Agility's CDN). Do NOT use
next/image. Use theAgilityPiccomponent from@agility/nextjsinstead - it's simpler and doesn't require JavaScript!
Use AgilityPic - No Configuration Needed:
import { AgilityPic } from "@agility/nextjs";
<AgilityPic
src={fields.image.url}
alt={fields.image.label}
width={768}
height={512}
/>
AgilityPic automatically:
<picture> tag<picture> tagNo next.config.js image configuration needed - AgilityPic handles everything automatically.
AWS Amplify automatically provisions SSL certificates for all domains (including custom domains) via AWS Certificate Manager. Ensure HTTPS is enforced:
AGILITY_SECURITY_KEY secret and secureAWS Amplify Hosting pricing:
For most small to medium sites, AWS Amplify hosting costs are minimal or free within the free tier limits.
# Local development
npm run dev
# Build locally (test before deploying)
npm run build
# Start production server locally
npm run start
This guide covers deploying Next.js applications with Agility CMS to AWS Amplify. For platform-specific questions, refer to the AWS Amplify documentation or Agility CMS support.