Dec 20, 2024
Go + Next.js: Full-Stack Architecture for Modern Web Apps
11 min · Backend · Frontend · Go · Next.js · Architecture · TypeScript
Go + Next.js: Full-Stack Architecture for Modern Web Apps
The combination of Go on the backend and Next.js on the frontend has become the gold standard for building modern, scalable web applications. Go provides performance, concurrency, and operational simplicity. Next.js provides a superior developer experience and world-class performance on the frontend.
But making them work together seamlessly requires thoughtful API design, proper type sharing, and architectural patterns that embrace asynchronicity.
Why Go + Next.js?
Go's Strengths
- Performance: Compiled to machine code, single binary deployment
- Concurrency: Goroutines make handling thousands of concurrent requests simple
- Simplicity: Minimal dependencies, explicit error handling, no magic
- Operational: Single binary, no runtime required, easy to monitor
Next.js Strengths
- Developer Experience: File-based routing, hot reload, excellent tooling
- Performance: Built-in image optimization, code splitting, ISR
- Type Safety: Full TypeScript support from client to server
- Flexibility: Works as static site generator, server-side renderer, or SPA
Together, they let you build fast, maintainable applications at scale.
Architecture Overview
┌─────────────────────────────────────────────────┐
│ Next.js Application (TypeScript) │
│ │
│ ┌────────────────────────────────────────────┐ │
│ │ Frontend Components & Pages │ │
│ │ - React with TypeScript │ │
│ │ - Tailwind CSS + Framer Motion │ │
│ │ - Next.js App Router │ │
│ └────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────┐ │
│ │ API Client Layer │ │
│ │ - Typed fetch wrapper │ │
│ │ - Error handling │ │
│ │ - Request/response transformation │ │
│ └────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘
│
│ JSON over HTTP/REST
│
┌─────────────────────────────────────────────────┐
│ Go Application (http Server) │
│ │
│ ┌────────────────────────────────────────────┐ │
│ │ HTTP Handlers │ │
│ │ - Validate request │ │
│ │ - Call service logic │ │
│ │ - Return JSON response │ │
│ └────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────┐ │
│ │ Service Layer │ │
│ │ - Business logic │ │
│ │ - Orchestration │ │
│ │ - Error handling │ │
│ └────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────┐ │
│ │ Repository Layer │ │
│ │ - Database queries (GORM) │ │
│ │ - Transactions │ │
│ │ - Caching (Redis) │ │
│ └────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘
│
│ SQL/Redis Protocol
│
┌─────────────────────────────────────────────────┐
│ PostgreSQL + Redis │
└─────────────────────────────────────────────────┘Type-Safe Communication Across the Stack
One of the biggest wins of Go + Next.js is leveraging TypeScript to maintain type safety from frontend to backend.
Shared Type Definition Pattern
Create a shared types package that both frontend and backend reference:
// shared/types/api.ts (included in both projects)
export namespace API {
// Request/Response types
export interface Product {
id: string;
name: string;
description: string;
price: number;
createdAt: string;
updatedAt: string;
}
export interface CreateProductRequest {
name: string;
description: string;
price: number;
}
export interface UpdateProductRequest {
name?: string;
description?: string;
price?: number;
}
export interface ApiResponse<T> {
success: boolean;
data?: T;
error?: {
code: string;
message: string;
details?: Record<string, unknown>;
};
}
export interface ListResponse<T> {
items: T[];
total: number;
page: number;
pageSize: number;
}
}Backend Implementation (Go)
Generate Go types from TypeScript using tools like json-to-go:
// backend/pkg/models/product.go
package models
type Product struct {
ID string `json:"id" gorm:"primaryKey"`
Name string `json:"name" gorm:"index"`
Description string `json:"description"`
Price float64 `json:"price"`
CreatedAt time.Time `json:"createdAt"`
UpdatedAt time.Time `json:"updatedAt"`
}
type CreateProductRequest struct {
Name string `json:"name" binding:"required"`
Description string `json:"description"`
Price float64 `json:"price" binding:"required,gt=0"`
}
type ApiResponse struct {
Success bool `json:"success"`
Data interface{} `json:"data,omitempty"`
Error *ErrorData `json:"error,omitempty"`
}
type ErrorData struct {
Code string `json:"code"`
Message string `json:"message"`
Details map[string]interface{} `json:"details,omitempty"`
}Frontend Implementation (TypeScript)
Use the shared types in your Next.js client:
// src/shared/api/client.ts
import type { API } from '@/shared/types/api';
export class ApiClient {
private baseUrl: string;
constructor(baseUrl: string) {
this.baseUrl = baseUrl;
}
async request<T>(
endpoint: string,
options?: RequestInit
): Promise<API.ApiResponse<T>> {
const response = await fetch(`${this.baseUrl}${endpoint}`, {
...options,
headers: {
'Content-Type': 'application/json',
...options?.headers,
},
});
if (!response.ok) {
const error = await response.json();
throw new Error(error.error?.message || 'Request failed');
}
return response.json();
}
async getProduct(id: string): Promise<API.Product> {
const response = await this.request<API.Product>(`/api/v1/products/${id}`);
if (!response.success || !response.data) {
throw new Error('Failed to fetch product');
}
return response.data;
}
async createProduct(req: API.CreateProductRequest): Promise<API.Product> {
const response = await this.request<API.Product>('/api/v1/products', {
method: 'POST',
body: JSON.stringify(req),
});
if (!response.success || !response.data) {
throw new Error('Failed to create product');
}
return response.data;
}
}
// Usage in components
export async function ProductForm() {
const api = new ApiClient(process.env.NEXT_PUBLIC_API_URL!);
async function handleSubmit(formData: API.CreateProductRequest) {
try {
const product = await api.createProduct(formData);
console.log('Product created:', product);
} catch (error) {
console.error('Error:', error);
}
}
return (
// Form JSX
);
}Go Backend Structure: Handler → Service → Repository
A clean separation of concerns in Go follows this pattern:
Layer 1: HTTP Handlers
// backend/pkg/api/handlers/product.go
package handlers
import (
"github.com/gin-gonic/gin"
"myapp/pkg/models"
"myapp/pkg/services"
)
type ProductHandler struct {
service *services.ProductService
}
func (h *ProductHandler) CreateProduct(c *gin.Context) {
// 1. Validate input
var req models.CreateProductRequest
if err := c.ShouldBindJSON(&req); err != nil {
c.JSON(400, models.ApiResponse{
Success: false,
Error: &models.ErrorData{
Code: "VALIDATION_ERROR",
Message: err.Error(),
},
})
return
}
// 2. Call service
product, err := h.service.CreateProduct(c.Request.Context(), req)
if err != nil {
c.JSON(500, models.ApiResponse{
Success: false,
Error: &models.ErrorData{
Code: "INTERNAL_ERROR",
Message: "Failed to create product",
},
})
return
}
// 3. Return response
c.JSON(201, models.ApiResponse{
Success: true,
Data: product,
})
}
func (h *ProductHandler) GetProduct(c *gin.Context) {
id := c.Param("id")
product, err := h.service.GetProduct(c.Request.Context(), id)
if err != nil {
c.JSON(404, models.ApiResponse{
Success: false,
Error: &models.ErrorData{
Code: "NOT_FOUND",
Message: "Product not found",
},
})
return
}
c.JSON(200, models.ApiResponse{
Success: true,
Data: product,
})
}Layer 2: Services (Business Logic)
// backend/pkg/services/product.go
package services
import (
"context"
"errors"
"myapp/pkg/models"
"myapp/pkg/repositories"
)
type ProductService struct {
repo *repositories.ProductRepository
}
func (s *ProductService) CreateProduct(
ctx context.Context,
req models.CreateProductRequest,
) (*models.Product, error) {
// Validate business rules
if req.Price < 0 {
return nil, errors.New("price must be positive")
}
// Create product in repository
product, err := s.repo.Create(ctx, models.Product{
Name: req.Name,
Description: req.Description,
Price: req.Price,
})
if err != nil {
return nil, err
}
// Could trigger side effects here
// - Send email notification
// - Queue job for search indexing
// - Update cache
s.invalidateCache(ctx, "products:list")
return product, nil
}
func (s *ProductService) GetProduct(
ctx context.Context,
id string,
) (*models.Product, error) {
return s.repo.GetByID(ctx, id)
}Layer 3: Repository (Data Access)
// backend/pkg/repositories/product.go
package repositories
import (
"context"
"myapp/pkg/models"
"gorm.io/gorm"
)
type ProductRepository struct {
db *gorm.DB
}
func (r *ProductRepository) Create(
ctx context.Context,
product models.Product,
) (*models.Product, error) {
if err := r.db.WithContext(ctx).Create(&product).Error; err != nil {
return nil, err
}
return &product, nil
}
func (r *ProductRepository) GetByID(
ctx context.Context,
id string,
) (*models.Product, error) {
product := &models.Product{}
if err := r.db.WithContext(ctx).Where("id = ?", id).First(product).Error; err != nil {
return nil, err
}
return product, nil
}
func (r *ProductRepository) List(
ctx context.Context,
page, pageSize int,
) ([]models.Product, int64, error) {
var products []models.Product
var total int64
db := r.db.WithContext(ctx)
if err := db.Model(&models.Product{}).Count(&total).Error; err != nil {
return nil, 0, err
}
offset := (page - 1) * pageSize
if err := db.
Offset(offset).
Limit(pageSize).
Find(&products).Error; err != nil {
return nil, 0, err
}
return products, total, nil
}Handling Long-Running Operations
Some operations (AI processing, file uploads, complex reports) shouldn't block API responses. The Go + Next.js stack handles this with job queues:
Backend: Queue Job and Return Immediately
// backend/pkg/api/handlers/product.go
type GenerateReportRequest struct {
ProductID string `json:"product_id"`
Format string `json:"format"`
}
func (h *ProductHandler) GenerateReport(c *gin.Context) {
var req GenerateReportRequest
if err := c.ShouldBindJSON(&req); err != nil {
c.JSON(400, gin.H{"error": err.Error()})
return
}
// Queue job in Redis
job := models.Job{
ID: uuid.New().String(),
Type: "generate_report",
Payload: req,
Status: "pending",
}
if err := h.jobQueue.Enqueue(c.Request.Context(), job); err != nil {
c.JSON(500, gin.H{"error": "Failed to queue job"})
return
}
// Return immediately with job ID
c.JSON(202, gin.H{
"job_id": job.ID,
"status": "processing",
})
}
// Background worker processes jobs
func (s *ProductService) ProcessReportJob(ctx context.Context, job models.Job) error {
// Long-running operation
report := generateComplexReport(job.Payload.ProductID)
// Store result
s.reportStorage.Save(ctx, job.ID, report)
// Update job status
s.jobQueue.MarkComplete(ctx, job.ID)
return nil
}Frontend: Poll for Completion
// src/hooks/useAsyncJob.ts
import { useState, useEffect } from 'react';
export function useAsyncJob(jobId: string) {
const [status, setStatus] = useState<'processing' | 'complete' | 'error'>('processing');
const [result, setResult] = useState(null);
useEffect(() => {
const interval = setInterval(async () => {
const response = await fetch(`/api/v1/jobs/${jobId}`);
const data = await response.json();
if (data.status === 'complete') {
setResult(data.result);
setStatus('complete');
clearInterval(interval);
} else if (data.status === 'error') {
setStatus('error');
clearInterval(interval);
}
}, 2000);
return () => clearInterval(interval);
}, [jobId]);
return { status, result };
}
// Usage
function ReportGenerator() {
const [jobId, setJobId] = useState<string | null>(null);
const { status, result } = useAsyncJob(jobId || '');
async function generateReport() {
const response = await api.request('/api/v1/reports/generate', {
method: 'POST',
body: JSON.stringify({ format: 'pdf' }),
});
setJobId(response.data?.job_id);
}
return (
<div>
<button onClick={generateReport}>Generate Report</button>
{status === 'processing' && <p>Processing...</p>}
{status === 'complete' && <a href={result}>Download Report</a>}
</div>
);
}Error Handling Strategy
Consistent error handling across the stack:
// backend/pkg/errors/errors.go
package errors
type Code string
const (
CodeValidationError Code = "VALIDATION_ERROR"
CodeNotFound Code = "NOT_FOUND"
CodeUnauthorized Code = "UNAUTHORIZED"
CodeConflict Code = "CONFLICT"
CodeInternalError Code = "INTERNAL_ERROR"
)
type ApiError struct {
Code Code `json:"code"`
Message string `json:"message"`
Details map[string]interface{} `json:"details,omitempty"`
Status int `json:"status,omitempty"`
}
func (e *ApiError) Error() string {
return e.Message
}
// Middleware to catch and format errors
func ErrorHandlerMiddleware(c *gin.Context) {
c.Next()
if len(c.Errors) > 0 {
err := c.Errors[0]
if apiErr, ok := err.Err.(*ApiError); ok {
c.JSON(apiErr.Status, models.ApiResponse{
Success: false,
Error: &models.ErrorData{
Code: string(apiErr.Code),
Message: apiErr.Message,
Details: apiErr.Details,
},
})
} else {
c.JSON(500, models.ApiResponse{
Success: false,
Error: &models.ErrorData{
Code: string(CodeInternalError),
Message: "Internal server error",
},
})
}
}
}Deployment and Scaling
Go Backend Deployment
# Dockerfile for Go backend
FROM golang:1.24-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o server ./cmd/server
FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/server .
EXPOSE 8080
CMD ["./server"]# Build and push
docker build -t myapp-backend:latest .
docker push registry.example.com/myapp-backend:latest
# Deploy to production
kubectl apply -f deployment.yamlNext.js Frontend Deployment
# Build
pnpm run build
# Deploy to Vercel (recommended)
vercel --prod
# Or deploy Docker image to your infrastructure
docker build -t myapp-frontend:latest .
docker push registry.example.com/myapp-frontend:latestMonitoring and Observability
Go Backend Metrics
import "github.com/prometheus/client_golang/prometheus"
var (
httpRequestsTotal = prometheus.NewCounterVec(
prometheus.CounterOpts{
Name: "http_requests_total",
Help: "Total HTTP requests",
},
[]string{"method", "endpoint", "status"},
)
httpDuration = prometheus.NewHistogramVec(
prometheus.HistogramOpts{
Name: "http_request_duration_seconds",
Help: "HTTP request duration in seconds",
},
[]string{"method", "endpoint"},
)
)
// Middleware
func MetricsMiddleware(c *gin.Context) {
start := time.Now()
c.Next()
duration := time.Since(start).Seconds()
httpDuration.WithLabelValues(
c.Request.Method,
c.Request.URL.Path,
).Observe(duration)
httpRequestsTotal.WithLabelValues(
c.Request.Method,
c.Request.URL.Path,
fmt.Sprintf("%d", c.Writer.Status()),
).Inc()
}Frontend Performance Monitoring
// src/shared/lib/analytics.ts
export function reportWebVitals(metric: any) {
const body = JSON.stringify(metric);
navigator.sendBeacon('/api/v1/metrics', body);
}
// pages/_app.tsx
import { reportWebVitals } from '@/shared/lib/analytics';
export function reportWebVitals(metric: NextWebVitalsMetric) {
reportWebVitals(metric);
}Lessons Learned
1. Invest in Type Safety Early
Shared types prevent bugs and make refactoring safe. They're worth the initial setup cost.
2. Handle Async Properly
Don't block API responses on long operations. Use job queues.
3. Error Handling Matters
Consistent error formats across the stack make debugging vastly easier.
4. Monitor from Day One
Set up metrics and logging early. They're invaluable for production issues.
5. Clean Layering Pays Off
Handler → Service → Repository separation makes code testable and maintainable.
Conclusion
Go + Next.js is a powerful combination precisely because it lets you leverage the strengths of each:
- Go: Performance, simplicity, concurrency, operational ease
- Next.js: Developer experience, TypeScript, performance, flexibility
Combined with proper API design, type safety, and asynchronous patterns, you can build scalable, maintainable systems that serve millions of users.
The stack isn't just hype - it's a genuinely excellent choice for modern web applications.