Frontend Deployment

This guide covers deploying the Justina frontend, a Next.js 16 application built with React 19 and TypeScript.

Prerequisites

Ensure you have:

Node.js 20+ installed
npm, yarn, pnpm, or bun package manager
Backend API running and accessible

See the Prerequisites page for installation instructions.

Clone Repository

git clone <repository-url>
cd S02-26-Equipo-24-Web-App-Development/frontend

Install Dependencies

The frontend uses several key dependencies:

Next.js 16.1.6 - React framework
React 19.2.3 - UI library
Babylon.js 8.51.2 - 3D surgical simulation
STOMP/WebSocket - Real-time telemetry
Tailwind CSS - Styling
TypeScript 5 - Type safety

npm install

Configure Environment

Create Environment File

Create .env.local in the frontend directory:

.env.local

NEXT_PUBLIC_API_URL=http://localhost:8080
NEXT_PUBLIC_WS_URL=ws://localhost:8080

Variables prefixed with NEXT_PUBLIC_ are exposed to the browser.

Environment Variables

Variable	Description	Default	Required
`NEXT_PUBLIC_API_URL`	Backend REST API URL	`http://localhost:8080`	Yes
`NEXT_PUBLIC_WS_URL`	WebSocket server URL	`ws://localhost:8080`	Yes

Update both URLs to point to your production backend. Use wss:// (secure WebSocket) in production.

Production Configuration

For production deployment:

.env.production

NEXT_PUBLIC_API_URL=https://api.yourdomain.com
NEXT_PUBLIC_WS_URL=wss://api.yourdomain.com

Development Server

Run the development server with hot reload:

npm run dev

The application will be available at:

http://localhost:3000

The page auto-updates as you edit files. The development server uses React Fast Refresh.

Production Build

Build Application

Create an optimized production build:

npm run build

This command:

Compiles TypeScript
Bundles and minifies JavaScript
Optimizes images and assets
Generates static pages where possible
Creates .next/ build directory

Expected output:

✓ Compiled successfully
✓ Linting and checking validity of types
✓ Collecting page data
✓ Generating static pages (5/5)
✓ Finalizing page optimization

Start Production Server

After building, start the production server:

npm run start

The application serves on port 3000 by default.

Custom Port

PORT=8080 npm run start

Deployment Options

Vercel (Recommended)

Vercel is the easiest deployment option for Next.js applications:

Install Vercel CLI

npm install -g vercel

Deploy

vercel

Follow the prompts to:

Link to your Vercel account
Configure project settings
Set environment variables

Configure Environment Variables

In Vercel dashboard, add:

NEXT_PUBLIC_API_URL = Your backend URL

Vercel automatically detects Next.js and configures optimal settings.

Node.js Server

Deploy on any Node.js hosting:

Build Application

npm run build

Upload Files

Transfer these directories to your server:

.next/
public/
package.json
next.config.ts
.env.production

Install Dependencies

npm install --production

Start Server

npm run start

PM2 Process Manager

Use PM2 for production process management:

Install PM2

npm install -g pm2

Start Application

pm2 start npm --name "justina-frontend" -- start

Configure Auto-Restart

pm2 startup
pm2 save

Monitor Application

pm2 status
pm2 logs justina-frontend
pm2 monit

Docker Deployment

Create Dockerfile in frontend directory:

FROM node:20-alpine AS base

# Install dependencies
FROM base AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci

# Build application
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

# Production image
FROM base AS runner
WORKDIR /app

ENV NODE_ENV production

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs

EXPOSE 3000

ENV PORT 3000

CMD ["node", "server.js"]

Build and run:

# Build image
docker build -t justina-frontend .

# Run container
docker run -p 3000:3000 \
  -e NEXT_PUBLIC_API_URL=http://backend:8080 \
  justina-frontend

Static Export

For static hosting (Nginx, Apache, S3):

Static export has limitations with dynamic features like WebSockets and API routes.

Modify next.config.ts:

next.config.ts

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  output: 'export',
  images: {
    unoptimized: true,
    remotePatterns: [
      {
        protocol: "https",
        hostname: "images.unsplash.com",
      },
    ],
  },
};

export default nextConfig;

Build:

npm run build

The out/ directory contains static files ready for deployment.

Nginx Configuration

Example Nginx configuration for reverse proxy:

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Verify Deployment

Check Application

Open browser to:

http://localhost:3000

Test Backend Connection

Verify the frontend can connect to the backend API.Check browser console for errors:

Press F12 → Console tab

Test WebSocket Connection

Ensure real-time features work:

Start a surgical simulation
Verify telemetry data flows
Check for WebSocket errors in console

Troubleshooting

API Connection Errors

Check NEXT_PUBLIC_API_URL is correct:

echo $NEXT_PUBLIC_API_URL

Verify backend is accessible:

curl http://your-backend-url/swagger-ui/index.html

Check CORS configuration on backend.

WebSocket Connection Failed

Ensure backend WebSocket endpoint is accessible:

ws://your-backend-url/ws/simulation

Check firewall rules allow WebSocket connections.Verify JWT token is being sent correctly.

3D Scene Not Loading

Babylon.js requires WebGL support. Check browser compatibility:

console.log(window.WebGLRenderingContext)

Verify 3D model files are accessible in public/ directory.

Build Failures

Clear cache and rebuild:

rm -rf .next node_modules
npm install
npm run build

Check TypeScript errors:

npm run lint

Performance Optimization

Image Optimization

Next.js automatically optimizes images. Use the <Image> component:

import Image from 'next/image'

<Image
  src="/surgery-image.jpg"
  alt="Surgery"
  width={800}
  height={600}
  priority
/>

Font Optimization

The project uses Next.js font optimization with Geist:

import { GeistSans } from 'next/font/geist'

Monitoring and Logs

PM2 Logs

pm2 logs justina-frontend
pm2 logs justina-frontend --lines 100

Next.js Logs

# Development
npm run dev

# Production
NODE_OPTIONS='--inspect' npm run start

Next Steps

After deploying the frontend:

Deploy Backend - Ensure backend is running
Deploy AI Service - Deploy AI analysis service
Configure SSL certificates
Set up CDN for static assets
Configure monitoring and analytics
Set up error tracking (Sentry, LogRocket)

Additional Resources

Environment Variables - Configuration reference
Next.js Documentation - Official Next.js docs
Vercel Deployment - Vercel deployment guide
Frontend dependencies: package.json
Tech stack: Next.js 16, React 19, TypeScript 5, Babylon.js 8

Setup

Components

Frontend Deployment

Prerequisites

Clone Repository

Install Dependencies

Configure Environment

Create Environment File

Environment Variables

Production Configuration

Development Server

Production Build

Build Application

Start Production Server

Custom Port

Deployment Options

Vercel (Recommended)

Node.js Server

PM2 Process Manager

Docker Deployment

Static Export

Nginx Configuration

Verify Deployment

Troubleshooting

Performance Optimization

Image Optimization

Font Optimization

Monitoring and Logs

PM2 Logs

Next.js Logs

Next Steps

Additional Resources

Build docs developers (and LLMs) love

Setup

Components

​Prerequisites

​Clone Repository

​Install Dependencies

​Configure Environment

​Create Environment File

​Environment Variables

​Production Configuration

​Development Server

​Production Build

​Build Application

​Start Production Server

​Custom Port

​Deployment Options

​Vercel (Recommended)

​Node.js Server

​PM2 Process Manager

​Docker Deployment

​Static Export

​Nginx Configuration

​Verify Deployment

​Troubleshooting

​Performance Optimization

​Image Optimization

​Font Optimization

​Monitoring and Logs

​PM2 Logs

​Next.js Logs

​Next Steps

​Additional Resources

Build docs developers (and LLMs) love

Prerequisites

Clone Repository

Install Dependencies

Configure Environment

Create Environment File

Environment Variables

Production Configuration

Development Server

Production Build

Build Application

Start Production Server

Custom Port

Deployment Options

Vercel (Recommended)

Node.js Server

PM2 Process Manager

Docker Deployment

Static Export

Nginx Configuration

Verify Deployment

Troubleshooting

Performance Optimization

Image Optimization

Font Optimization

Monitoring and Logs

PM2 Logs

Next.js Logs

Next Steps

Additional Resources