Skip to main content
Entirius
AI platform for e-commerce
Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage

ADR-003: Next.js for Frontend Applications

Status

Status: Accepted
Date: 2025-06-23
Authors: Piotr Brzozowski
Reviewers: Piotr Brzozowski

Decision

React with Next.js is adopted as the frontend framework for all Entirius customer-facing and administrative applications. This provides server-side rendering for SEO optimization, modern development experience with TypeScript, and seamless integration with the Django REST API backend.

Quick Reference

Essential Commands

# Create new Next.js app
npx create-next-app@latest app-name --typescript --tailwind --eslint

# Development server
npm run dev

# Production build
npm run build
npm start

# Type checking
npm run type-check

Key Implementation Patterns

  • SSR for e-commerce pages: Use getServerSideProps for product and category pages
  • API integration: Use OpenAPI-generated client with Next.js API routes
  • State management: React Context for simple state, Redux Toolkit for complex state
  • Styling: Tailwind CSS for consistent design system
  • Performance: Image optimization with next/image, code splitting with dynamic imports

Context

Entirius e-commerce platform requires a modern frontend framework for both the customer-facing application and the administrative panel. The solution needs to:

  • Provide excellent user experience for e-commerce customers
  • Support server-side rendering for SEO optimization
  • Enable rapid development of administrative interfaces
  • Integrate seamlessly with Django REST API backend (ADR-002)
  • Support modern development practices and tooling
  • Scale with the modular monolith architecture (ADR-001)

Key technical requirements:

  • TypeScript support for type safety
  • SEO-friendly rendering for e-commerce content
  • Mobile-responsive design capabilities
  • State management for complex UI interactions
  • Component reusability between customer and admin interfaces
  • Performance optimization for e-commerce workloads
  • Integration with OpenAPI-generated client SDKs

Considered Options

Option 1: React with Next.js

  • Description: Use React library with Next.js framework for both frontend and admin panel
  • Pros:
    • Server-side rendering (SSR) and static site generation (SSG) for SEO
    • Full-stack capabilities with API routes
    • Excellent TypeScript integration
    • Large ecosystem and community support
    • Built-in performance optimizations
    • File-based routing system
    • Image optimization and lazy loading
    • Incremental Static Regeneration (ISR)
    • Easy deployment and hosting options
  • Cons:
    • Learning curve for Next.js-specific features
    • Can be complex for simple applications
    • Bundle size considerations
    • React-specific patterns and lifecycle
  • Impact on system: Provides modern, performant frontend with excellent SEO capabilities

Option 2: Vue.js with Nuxt.js

  • Description: Use Vue.js framework with Nuxt.js for universal application development
  • Pros:
    • Gentle learning curve and intuitive syntax
    • Excellent documentation and developer experience
    • Built-in state management with Vuex/Pinia
    • Server-side rendering with Nuxt.js
    • Smaller bundle sizes compared to React
    • Strong TypeScript support
    • Composition API for better code organization
  • Cons:
    • Smaller ecosystem compared to React
    • Less job market availability
    • Fewer third-party component libraries
    • Less integration with enterprise tools
    • Smaller community for e-commerce specific solutions
  • Impact on system: Clean, maintainable frontend with good performance

Option 3: Angular

  • Description: Use Angular framework for enterprise-grade application development
  • Pros:
    • Full framework with opinionated structure
    • Excellent TypeScript integration (built-in)
    • Powerful CLI and development tools
    • Built-in dependency injection
    • Strong testing framework
    • Enterprise-ready architecture patterns
  • Cons:
    • Steep learning curve
    • Heavy framework overhead
    • Complex for simple use cases
    • Verbose syntax and boilerplate
    • Less suitable for content-heavy e-commerce sites
    • Limited SSR capabilities compared to Next.js
  • Impact on system: Robust but potentially over-engineered for e-commerce needs

Rationale

Chosen option: React with Next.js

Key decision factors:

  • SEO optimization: Next.js SSR/SSG capabilities are crucial for e-commerce visibility and search engine rankings
  • Performance: Built-in optimizations for images, fonts, code splitting, and Core Web Vitals
  • Developer experience: Excellent tooling, hot reloading, debugging capabilities, and TypeScript integration
  • Ecosystem maturity: Vast library of React components, e-commerce solutions, and community support
  • API integration: Seamless integration with OpenAPI-generated clients from Django REST API backend
  • Scalability: Component architecture scales well with modular monolith approach and team growth
  • Risk analysis: Low technical risk due to mature ecosystem, extensive documentation, and wide adoption
  • Business impact: Faster time-to-market with proven e-commerce patterns and community solutions
  • Compatibility: Excellent integration with existing Django backend and planned CI/CD workflows
  • ADR-001: Aligns with modular monolith architecture
  • ADR-002: Integrates with Django REST API

References