Skip to main content

ADR-002: Use Next.js

Status​

Accepted

Date​

2026-07-20

Context​

Chilarai requires a modern web-based frontend application capable of supporting:

  • Student management
  • Admissions management
  • Attendance tracking
  • Fee management
  • Administrative dashboards
  • Reporting interfaces
  • Parent and teacher portals
  • Future AI-assisted experiences

The frontend framework must provide:

  • Excellent TypeScript support
  • Strong developer productivity
  • Long-term maintainability
  • A large ecosystem and community
  • Compatibility with the Nx monorepo architecture
  • A scalable architecture suitable for long-term product growth

A frontend framework decision must be made before implementation of the user experience layer begins.

Decision Drivers​

The selected approach should:

  • Support TypeScript as a first-class citizen
  • Enable rapid development by a small team
  • Have a large ecosystem and talent pool
  • Provide long-term stability
  • Support modern UI patterns
  • Integrate well with Nx
  • Support future AI-assisted user experiences
  • Reduce framework and infrastructure complexity
  • Support server-side rendering when needed

Alternatives Considered​

Option 1: Angular​

Advantages​

  • Mature enterprise framework
  • Strong architectural guidance
  • Excellent dependency injection support
  • Consistent application structure

Disadvantages​

  • Larger learning curve
  • More framework complexity
  • Slower development velocity for a small team
  • Smaller ecosystem compared to React

Assessment​

Angular remains a strong enterprise option but introduces more complexity than is justified for the current team size and product stage.

Option 2: React without a Framework​

Advantages​

  • Large ecosystem
  • Flexible architecture
  • Excellent TypeScript support
  • Strong community support

Disadvantages​

  • Requires additional decisions for routing
  • Requires additional decisions for application structure
  • Requires additional decisions for rendering strategy
  • Requires additional build and tooling decisions

Assessment​

React provides an excellent foundation but leaves too many architectural concerns unresolved.

Option 3: Next.js​

Advantages​

  • Built on React
  • Excellent TypeScript support
  • Integrated routing
  • Strong ecosystem
  • First-class support within Nx
  • Modern application architecture
  • Large community adoption
  • Long-term industry viability

Disadvantages​

  • Additional abstraction layer over React
  • Framework-specific concepts such as App Router
  • Dependency on Next.js release cadence

Assessment​

Next.js provides sensible defaults while preserving access to the broader React ecosystem.

Option 4: Vue / Nuxt​

Advantages​

  • Good developer experience
  • Modern component model
  • Strong documentation

Disadvantages​

  • Smaller talent pool
  • Less familiarity within the team
  • Reduced ecosystem alignment with existing experience

Assessment​

A technically strong alternative that does not offer significant advantages over Next.js for this project.

Decision​

Use Next.js as the frontend application framework for Chilarai.

The initial implementation will use:

  • TypeScript
  • React
  • App Router
  • CSS
  • Nx integration

Rationale​

Next.js provides the best balance between development speed, maintainability, ecosystem maturity, and long-term sustainability.

The framework delivers:

  • A strong React foundation
  • Excellent TypeScript support
  • Integrated routing
  • Modern project structure
  • Strong Nx integration
  • Access to the largest frontend ecosystem

Compared with Angular, it reduces complexity and improves development velocity.

Compared with React alone, it removes the need to make numerous foundational framework decisions.

The framework aligns well with the architecture and team goals for Chilarai.

Consequences​

Positive Consequences​

  • Faster frontend development
  • Large ecosystem of libraries and components
  • Excellent TypeScript support
  • Consistent project structure
  • Easier onboarding for future contributors
  • Strong integration with the Nx monorepo

Negative Consequences​

  • Frontend architecture becomes dependent on Next.js conventions
  • Contributors must understand App Router concepts
  • Framework upgrades must follow Next.js guidance

Follow-up Actions​

  • Adopt App Router as the default routing model
  • Standardize on TypeScript across the frontend
  • Establish a UI component strategy
  • Evaluate Tailwind CSS and shadcn/ui
  • Establish frontend architectural guidelines