DeployFrame Docs

Local Development

How to work with your deployed AI SaaS platform locally for development and testing

Local Development

This guide explains how to set up and run the frontend of your AI SaaS platform locally for development and testing. The local frontend will connect to your deployed backend services on AWS, allowing you to develop and test UI changes quickly without affecting the live application.

Prerequisites

Before starting local development, ensure you have:

  • Successfully deployed your AI SaaS platform to AWS
  • Completed all integration steps (Stripe, Google OAuth, etc.)
  • Node.js and npm installed on your local machine

Environment Variables Required: If you're on a different machine than where you deployed, you'll need to set up the project environment variables first. The commands in this guide require these environment variables:

  • PROJECT_ROOT - Path to the project root directory
  • CDK_DIR - Path to the CDK directory
  • APP_NAME - Application name from environment variables
  • STAGE - Deployment stage (dev/prod)
  • AWS_DEFAULT_REGION - AWS region for deployment

If you don't have these set up, please refer back to the Deployment Configuration section to set up these variables, or run this quick verification:

echo "PROJECT_ROOT: $PROJECT_ROOT"
echo "CDK_DIR: $CDK_DIR"
echo "APP_NAME: $APP_NAME"
echo "STAGE: $STAGE"
echo "AWS_DEFAULT_REGION: $AWS_DEFAULT_REGION"

All variables should show their values. If any are empty, you need to set them up before proceeding.

Setting Up Local Development

From your project root, navigate to the frontend directory:

cd $PROJECT_ROOT/frontend

Create Local Environment File

Create a .env.local file in the frontend directory with the following template:

##################################################
# App Configuration
##################################################
NEXT_PUBLIC_APP_NAME='ai-saas'
##################################################
# AWS AppSync Configuration
##################################################
NEXT_PUBLIC_AWS_APPSYNC_REGION='eu-west-2'
NEXT_PUBLIC_AWS_APPSYNC_GRAPHQL_ENDPOINT=''
##################################################
# AWS API Gateway Custom Endpoints
##################################################
NEXT_PUBLIC_AWS_CLOUD_LOGIC_CUSTOM=''
##################################################
# AWS Cognito Configuration
##################################################
NEXT_PUBLIC_AWS_COGNITO_REGION='eu-west-2'
NEXT_PUBLIC_AWS_COGNITO_DOMAIN=''
NEXT_PUBLIC_AWS_USER_POOLS_ID=''
NEXT_PUBLIC_AWS_USER_POOLS_WEB_CLIENT_ID=''
NEXT_PUBLIC_AWS_COGNITO_IDENTITY_POOL_ID=''
##################################################
# AWS S3 Configuration
##################################################
NEXT_PUBLIC_AWS_PROJECT_REGION='eu-west-2'
NEXT_PUBLIC_AWS_USER_FILES_S3_BUCKET_REGION='eu-west-2'
NEXT_PUBLIC_AWS_USER_FILES_S3_BUCKET=''
##################################################
# App Redirect URLs
##################################################
NEXT_PUBLIC_REDIRECT_SIGNIN='http://localhost:3000'
NEXT_PUBLIC_REDIRECT_SIGNUP='http://localhost:3000'
##################################################
# Stripe Configuration
##################################################
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=""
##################################################
# Google Analytics
##################################################
NEXT_PUBLIC_GA_ID='G-XXXXX'
##################################################
# Site Configuration
##################################################
NEXT_PUBLIC_SITE_URL='http://localhost:3000'
##################################################
# App Environment
##################################################
APP_ENV='development'

The regions are pre-configured to match your deployment region (eu-west-2). Set NEXT_PUBLIC_APP_NAME to match your APP_NAME from the deployment configuration. The other empty values need to be filled with your actual deployment values.

Get Your Deployment Values

You need to fill in the empty values in your .env.local file. You can get these values in two ways:

Option A: Visual Guide

Watch the comprehensive video guide available on the main documentation page that shows you how to find these values in the AWS Console.

Option B: Using CloudFormation Commands

Run these commands to automatically retrieve the values from your deployment:

# Get AppSync GraphQL Endpoint
APPSYNC_ENDPOINT=$(aws cloudformation list-exports \
  --region $AWS_DEFAULT_REGION \
  --query "Exports[?Name=='${STAGE}-${APP_NAME}-graphql-users-credits-api-url'].Value" \
  --output text)
echo "NEXT_PUBLIC_AWS_APPSYNC_GRAPHQL_ENDPOINT='$APPSYNC_ENDPOINT'"
 
# Get API Gateway Endpoint (from Amplify environment variables)
AMPLIFY_APP_ID=$(aws cloudformation list-exports \
  --region $AWS_DEFAULT_REGION \
  --query "Exports[?Name=='${STAGE}-${APP_NAME}-amplify-app-id'].Value" \
  --output text)
API_GATEWAY_ENDPOINT=$(aws amplify list-branches \
  --region $AWS_DEFAULT_REGION \
  --app-id "$AMPLIFY_APP_ID" \
  --query "branches[?branchName=='dev'].environmentVariables.NEXT_PUBLIC_AWS_CLOUD_LOGIC_CUSTOM" \
  --output text)
echo "NEXT_PUBLIC_AWS_CLOUD_LOGIC_CUSTOM='$API_GATEWAY_ENDPOINT'"
 
# Get Cognito Domain
COGNITO_DOMAIN=$(aws cloudformation list-exports \
  --region $AWS_DEFAULT_REGION \
  --query "Exports[?Name=='${STAGE}-${APP_NAME}-user-pool-domain'].Value" \
  --output text)
echo "NEXT_PUBLIC_AWS_COGNITO_DOMAIN='$COGNITO_DOMAIN'"
 
# Get User Pool ID
USER_POOL_ID=$(aws cloudformation list-exports \
  --region $AWS_DEFAULT_REGION \
  --query "Exports[?Name=='${STAGE}-${APP_NAME}-user-pool-id'].Value" \
  --output text)
echo "NEXT_PUBLIC_AWS_USER_POOLS_ID='$USER_POOL_ID'"
 
# Get User Pool Client ID
USER_POOL_CLIENT_ID=$(aws cloudformation list-exports \
  --region $AWS_DEFAULT_REGION \
  --query "Exports[?Name=='${STAGE}-${APP_NAME}-user-pool-client-id'].Value" \
  --output text)
echo "NEXT_PUBLIC_AWS_USER_POOLS_WEB_CLIENT_ID='$USER_POOL_CLIENT_ID'"
 
# Get Identity Pool ID
IDENTITY_POOL_ID=$(aws cloudformation list-exports \
  --region $AWS_DEFAULT_REGION \
  --query "Exports[?Name=='${STAGE}-${APP_NAME}-identity-pool-id'].Value" \
  --output text)
echo "NEXT_PUBLIC_AWS_COGNITO_IDENTITY_POOL_ID='$IDENTITY_POOL_ID'"
 
# Get S3 Bucket Name
S3_BUCKET=$(aws cloudformation list-exports \
  --region $AWS_DEFAULT_REGION \
  --query "Exports[?Name=='${STAGE}-${APP_NAME}-bucket-name'].Value" \
  --output text)
echo "NEXT_PUBLIC_AWS_USER_FILES_S3_BUCKET='$S3_BUCKET'"

Copy the output values and paste them into your .env.local file, replacing the empty strings.

For NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY, use the same Stripe publishable key you configured during the Stripe setup process.

Install Dependencies

Install the required Node.js dependencies:

npm install

This will install all the packages needed to run the frontend locally, including Next.js, React, and AWS SDK components.

Start the Development Server

Run the Next.js development server:

npm run dev

The development server will start and be available at http://localhost:3000.

The local frontend will connect to your deployed backend services on AWS, so all features should work exactly as they do in the deployed version.

Verifying Local Development Setup

Access Your Local Application

Open your web browser and navigate to http://localhost:3000. You should see your AI SaaS platform loading locally.

Test Authentication

Try signing in with an existing account or creating a new account to verify that authentication is working correctly with your deployed Cognito setup.

Test Core Features

Verify that key features are working:

  • User dashboard loads correctly
  • Credit balance is displayed
  • Subscription information is accessible
  • AI services are available (if you have credits)

All data interactions happen with your deployed AWS services, so any changes you make (like using credits or updating profile information) will be reflected in both local and deployed versions.

Understanding Local Development

When running the frontend locally:

  • Frontend: Runs on your local machine at http://localhost:3000
  • Backend services: Still running in AWS (Lambda functions, API Gateway, etc.)
  • Authentication: Uses your deployed AWS Cognito configuration
  • Data storage: Uses your deployed AWS S3 buckets and DynamoDB tables
  • Payment processing: Uses your configured Stripe account

This setup allows you to:

  • Make changes to the frontend code and see results immediately
  • Debug frontend issues more easily
  • Test new UI features before deploying
  • Customize the interface without affecting the live application

Making and Testing Changes

Edit Frontend Code

Make changes to any file in the frontend directory. The development server will automatically reload the page when you save changes.

Test Your Changes

Your changes will be immediately visible at http://localhost:3000. Test thoroughly to ensure everything works as expected.

Deploy Changes (When Ready)

When you're satisfied with your changes, deploy them to your live application:

# Commit your changes
git add .
git commit -m "Describe your changes"
git push

AWS Amplify will automatically build and deploy your frontend changes when you push to your repository.

Best Practices

  1. Test thoroughly locally before pushing changes to your repository
  2. Use version control to track all changes
  3. Keep environment files secure - never commit .env.local to version control
  4. Monitor AWS costs during development as requests still go through AWS services
  5. Create feature branches for major changes before merging to main

Next Steps

Now that you have local development set up, you can:

  • Customize the user interface to match your brand
  • Add new features to the platform
  • Modify existing components and pages
  • Test integrations with third-party services

Previous

AI Services Testing

Next

Infrastructure Overview

On this page