Deploy Frontend

The Next.js frontend is hosted on AWS Amplify and auto-deploys when changes are pushed to the staging or main branches.

Automatic Deployments

Branch Environment Trigger
staging Staging Merge PR to staging
main Production Merge PR to main

How It Works

  1. A pull request is merged into staging (or main).
  2. Amplify detects the push and starts a build.
  3. Amplify runs npm run build for the Next.js application.
  4. On success, the new version is deployed and the URL is updated.

Build logs are available in the Amplify Console.

Checking Build Status

Via Amplify Console

  1. Open the Amplify Console in the PhD Advantage AWS account (735234196709).
  2. Select the branch (staging or main).
  3. View the build status and logs.

Via AWS CLI

aws amplify list-jobs \
  --app-id d1vpp3bmermmyp \
  --branch-name staging \
  --profile dissertation-editor

Manual Redeploy

If you need to redeploy without a code change (e.g., after updating Amplify environment variables):

  1. Open the Amplify Console.
  2. Select the branch.
  3. Click Redeploy this version.

Alternatively, via CLI:

aws amplify start-job \
  --app-id d1vpp3bmermmyp \
  --branch-name staging \
  --job-type RELEASE \
  --profile dissertation-editor

Updating Environment Variables

Frontend environment variables are configured in the Amplify Console, not in the codebase.

Step 1: Update the Variable

  1. Open the Amplify Console for the app.
  2. Go to Hosting > Environment variables.
  3. Add a new variable or update an existing one.

Current variables:

Variable Description
NEXT_PUBLIC_TOKEN_ENDPOINT Full URL for the LiveKit token API endpoint
NEXT_PUBLIC_API_URL Base URL for all backend API calls

Step 2: Trigger a Redeploy

Environment variable changes do not take effect until the next build. Trigger a manual redeploy after updating variables.

Build Configuration

Amplify uses the amplify.yml build specification (or auto-detected Next.js settings). The build process:

  1. Installs dependencies: npm install
  2. Builds the application: npm run build
  3. Deploys the output (SSR-enabled Next.js)

Troubleshooting

Problem Solution
Build fails with dependency errors Check package-lock.json is committed. Amplify runs npm ci which requires the lockfile.
Build succeeds but site shows old content Clear browser cache or open in incognito. Check if the build deployed to the correct branch.
Environment variable not working Ensure the variable name starts with NEXT_PUBLIC_ if it needs to be available in the browser. Redeploy after updating.
Build timeout Amplify has a default 30-minute build timeout. If the build is slow, check for large dependencies or optimize the build.
404 on dynamic routes Ensure the Amplify rewrite rules are configured to serve the Next.js application for all routes.

Deployment Order

When changes span both backend and frontend:

  1. Deploy backend first -- Lambda functions and API Gateway must be updated before the frontend expects new endpoints or response formats.
  2. Merge frontend PR to staging -- Amplify auto-deploys and uses the already-updated backend.
  3. Test on staging.
  4. Merge to main for production.

This order ensures backward compatibility during the deployment window.