Forem: Hamed Farag

I Built a Browser UI for Claude Code — Here's Why

Hamed Farag — Mon, 16 Mar 2026 08:15:44 +0000

I started using Claude Code a few months ago. Terminal-first, no nonsense, incredibly powerful. But after weeks of juggling sessions, losing track of costs, and wishing I could approve tool calls from my phone while grabbing coffee — I started building something for myself.

That something became Claudeck.

It started on March 1st as a quick experiment I called "shawkat-ai" — a simple WebSocket bridge between my browser and the Claude Code SDK so I could chat without squinting at terminal output. Then I added cost tracking because I wanted to know where my money was going. Then session persistence. Then workflows. Then agents. Then a plugin system. Then Telegram integration. Then autonomous agent DAGs.

Two weeks later — yes, two weeks — it was a full-featured browser UI with 50+ features, renamed to Claudeck, published on npm, and somehow competing with tools backed by YC and teams of engineers. 55 commits in 15 days, each one adding a major feature.

This is the story of why I built it, what makes it different, and why you might want to try it.

The Problem with Claude Code in the Terminal

Don't get me wrong — Claude Code in the terminal is excellent. It's fast, it's powerful, and it gets out of your way. But there are real friction points:

You can't see the big picture. How much have you spent today? This week? Which sessions burned the most tokens? The terminal doesn't tell you.

Context switching is painful. You're mid-conversation, need to check something in another session, and now you've lost your place. No tabs, no background sessions, no parallel conversations.

You can't walk away. Claude asks for permission to run a bash command. You're making coffee. The session just... waits. Anthropic recently shipped Remote Control — scan a QR code and approve from your phone via claude.ai. It's a step forward, but it's Max-only ($100–$200/mo), requires your terminal to stay open, and gives you approval control without the broader context — no cost tracking, no session management, no workflows.

No visual tools. File diffs are raw text. There's no file explorer. No git panel. No way to drag a file into the conversation.

No workflows. Every PR review starts with the same three prompts. Every repo onboarding follows the same pattern. But you type them out fresh each time.

I kept a mental list of these annoyances. On March 1st, 2026, I decided to fix them. What I thought would be a weekend project turned into a two-week sprint that I couldn't stop.

What is Claudeck?

Claudeck is a browser-based UI for Claude Code. One command to launch:

npx claudeck

It connects to the official Claude Code SDK running on your machine. Your API key, your local files, your git repos — nothing goes through a third-party server. It's a local web app that gives Claude Code a proper interface.

Think of it as what VS Code is to vim — the same power, but with a visual layer that makes certain things dramatically easier.

The Landscape: Why Not Use Something Else?

When I started building on March 1st, I wasn't thinking about alternatives. By the time I looked up two weeks later with a fully shipped product, there were at least a dozen. Here's the honest picture:

Opcode (20K+ stars, YC-backed)

A polished desktop app built with React and Tauri. Great session management, usage analytics, and custom agent creation. But it's desktop-only — no mobile, no PWA, no browser access. And it requires installing a native app.

CloudCLI (7.9K stars)

The multi-CLI Swiss Army knife. Supports Claude Code, Cursor CLI, Codex, and Gemini CLI. Has a file explorer and git integration. But no cost dashboard, no workflows, no prompt templates, and no parallel chat mode.

CodePilot (3.1K stars)

Electron + Next.js desktop app with model switching and permission controls. Solid, but again — desktop-only, no workflows, no cost analytics, no prompt templates.

Anthropic's Remote Control

Anthropic's own answer: run claude remote-control, scan a QR code, control from your phone via claude.ai/code. But it's Max-only ($100–$200/mo), the terminal must stay open, and there's no file explorer, no analytics, no multi-session management.

So why Claudeck?

Because none of them scratched every itch. I wanted:

Browser-based — open a tab, start working. No Electron, no Tauri, no native install.
Cost visibility — know exactly what I'm spending, per session, per day, per project.
Workflows and templates — stop retyping the same prompts.
Agent orchestration — not just one agent, but chains, DAGs, and an auto-orchestrator.
AFK approval — approve tool calls from my phone via Telegram while away from my desk.
Zero bloat — vanilla JS, 6 npm dependencies, no build step.

No existing tool offered all of these. So I built it.

Features That Matter

I'm not going to list all 50+ features. Here are the ones that changed how I work:

Parallel Mode (2x2 Grid)

Four independent Claude conversations running simultaneously in a grid layout. I use this constantly:

Pane 1: refactoring a module
Pane 2: writing tests for it
Pane 3: reviewing a PR
Pane 4: exploring documentation

Each pane has its own session, its own context, its own streaming output. No competitor has this.

Cost Dashboard

A full analytics dashboard with daily cost charts, per-session breakdowns, input/output token counts, and error pattern analysis. I can see at a glance that Tuesday's refactoring session cost $4.20 across 47 turns, and that 30% of my errors are "File Not Found."

This is the feature that convinced me to make Claudeck public. Every Claude Code user deserves to know where their money goes.

AI Workflows

Pre-built multi-step pipelines:

Review PR — analyze diff, identify issues, suggest improvements (3 steps, context carries forward)
Onboard Repo — map structure, explain architecture, generate dev guide
Migration Plan — audit dependencies, assess impact, create plan
Code Health — identify tech debt, suggest improvements

You can create your own workflows with full CRUD. Each step carries context from the previous one, so Claude builds on its own analysis.

Autonomous Agents

Four built-in agents (PR Reviewer, Bug Hunter, Test Writer, Refactoring) that run as high-turn autonomous sessions. But the real power is in composition:

Agent Chains — sequential pipelines: Bug Hunter finds issues, then PR Reviewer analyzes the fixes
Agent DAGs — visual dependency graphs: Bug Hunter and Test Writer run in parallel, then PR Reviewer synthesizes both
Orchestrator — describe a task in plain language, and it auto-decomposes into specialist agent calls

I built a full visual DAG editor with an SVG canvas where you drag agents and draw connections. It feels like a simplified version of a CI/CD pipeline builder, but for AI agents.

Telegram Integration (Two-Way)

This is the one people don't expect. Configure a Telegram bot, and:

Outbound: Every session completion, agent run, workflow step, and error sends a rich notification to your phone with metrics (cost, tokens, duration).
Inbound: When Claude needs permission to run a tool, you get an inline keyboard on Telegram with Approve/Deny buttons. Approve from your phone, and the web UI modal auto-dismisses.

I built this because I run long agent sessions and walk away. Now I approve bash commands from my couch.

Prompt Templates with Variables

{
  "title": "Code Review",
  "prompt": "Review {{file_path}} for {{concern}}"
}

Click the template, fill in the form, send. Sixteen built-in templates, plus it auto-discovers .claude/commands/ and .claude/skills/ from your project directory.

File Explorer, Git Panel, and Code Diffs

Lazy-loaded file tree with syntax-highlighted preview
Git panel with branch switching, staging, commit, and log
LCS-based code diff viewer with green/red line highlighting for Edit and Write tool outputs

These aren't groundbreaking individually, but having them integrated into the same interface where you're chatting with Claude eliminates constant context switching.

Plugin System

Full-stack plugin architecture. Drop files in ~/.claudeck/plugins/my-plugin/ with a client.js and optionally a server.js, and it appears in the marketplace. Built-in plugins include Linear integration, a todo list with brag tracking, and even a couple of games for when you're waiting on a long agent run.

The best part? You can extend Claudeck using Claude Code itself. I published a Claude Code skill that lets you scaffold new plugins with a single command:

# Install the skill (one-time)
npx skills add https://github.com/hamedafarag/claudeck-skills

# Then in Claude Code, just describe what you want:
/claudeck-plugin-create my-widget A dashboard showing system metrics

Claude generates the full plugin — client.js, client.css, and optionally server.js with Express routes — directly into ~/.claudeck/plugins/. Refresh the page and your plugin is live in the marketplace. No fork needed, no build step, no PR. You describe it, Claude builds it, Claudeck loads it.

The Technical Philosophy

Zero Framework, Six Dependencies

Claudeck's frontend is vanilla JavaScript ES modules. No React. No Vue. No Svelte. No bundler. No build step.

The entire backend runs on Express, WebSocket (ws), better-sqlite3, web-push, dotenv, and the Claude Code SDK. That's it. Six npm dependencies.

Why? Because I wanted to iterate fast. No waiting for builds. No fighting with framework upgrade cycles. No 200MB node_modules. Change a file, refresh the browser.

This choice is a big reason the entire project went from zero to 50+ features in 15 days. When you're building something for yourself, every minute spent on tooling is a minute not spent on features. Vanilla JS with ES modules and CSS custom properties is surprisingly productive when you're not fighting abstractions.

Everything is Local

No cloud. No accounts. No telemetry. Your data lives in ~/.claudeck/ — a SQLite database, some JSON config files, and your plugins. Delete the directory and it's gone.

This was non-negotiable for me. I'm sending code to Claude — I'm not also sending my usage patterns to a third party.

PWA with Offline Fallback

Install it as a PWA from Chrome's address bar. It runs in a standalone window, supports push notifications (even when the browser is closed), and has an offline fallback page. On mobile, it's fully responsive with tablet and phone breakpoints.

What Claudeck Doesn't Do

Honesty matters. Here's where alternatives beat Claudeck:

No authentication — anyone on your local network can access it. This is the biggest gap and the next thing I'm building.
No multi-CLI support — CloudCLI supports Claude Code, Cursor CLI, Codex, and Gemini CLI. Claudeck is Claude Code only.
No desktop app — if you want a native macOS/Windows experience, Opcode and CodePilot are better choices.
No live file editing — CloudCLI lets you edit files directly in the UI. Claudeck shows file previews but doesn't have an editor (that's what your IDE is for).

Who is Claudeck For?

Solo developers who use Claude Code daily and want visibility into costs, reusable workflows, and a visual interface without leaving the browser.

Developers who work AFK — the Telegram integration means you can kick off a long agent run, walk away, and approve tool calls from your phone.

Power users who want parallel conversations, agent pipelines, and prompt templates — features that the terminal simply can't offer.

Teams evaluating Claude Code who need cost analytics to justify the spend.

Try It

npx claudeck

One command. No install. Opens in your browser. Your first session is free (well, you're paying Anthropic — Claudeck itself is free and open source).

The source is on GitHub: github.com/hamedafarag/claudeck

If you find it useful, star the repo. If you build a plugin, let me know. If you find a bug — definitely let me know.

The File Structure Dilemma

Hamed Farag — Mon, 29 Jan 2024 15:56:26 +0000

Introduction and A Fact

In this discussion, we'll delve into file structure within the realm of frontend development, with a particular focus on React. React, at its core, is a library, not a framework. It primarily operates within the view layer, enabling its integration into applications like Angular for managing the UI. This integration involves referencing React through CDNs and creating components in JavaScript or JSX, which are then incorporated into Angular seamlessly.

React, distinct from Angular (specifically Angular version 1), doesn't adhere to the traditional Model-View-Controller (MVC) pattern. While Angular incorporates elements of MVC, React positions itself solely as a view layer library. This unique stance brings with it distinct concepts and approaches.

Given React's nature as a library, setting up a project involves careful planning and selection of additional libraries to supplement its capabilities. Tasks such as routing require specific libraries like React Router DOM. For state management, developers might opt for external libraries. The necessity to explore the React ecosystem for libraries catering to basic requirements is a fundamental aspect of working with React.

Ultimately, React doesn't function in isolation for production-grade projects. It necessitates a combination of complementary libraries to form a complete framework. The React documentation even suggests pairing with tools like Vite or NextJS. The essence of React lies in its coexistence with its ecosystem, proving that React alone isn't sufficient for building substantial projects.

The crux of the matter lies in determining the optimal file structure. Decisions regarding the hierarchical arrangement of files and their interrelationships require strategic planning from the outset, influenced by various factors. This article explores potential file organization strategies for your project, helping you make informed decisions about structuring your files.

Determining File Structure Factors

When deciding on your file structure for a project, several key factors come into play. The primary consideration is the project's size. This could range from a small, personal project to a complex one with multiple modules and numerous pages.

The second crucial factor is the team size working on the project. It could be a solo endeavor, a small team of two to five members, or larger groups divided into multiple teams. The team size significantly influences how the file structure should be organized, as larger teams require more systematic and clear file structures to ensure efficient collaboration.

It's important to note that there is no universally prescribed method for naming and organizing files. The approach can vary, often involving common folder names like 'components', 'hooks', 'pages', 'styles', and 'UI', among others.

In summary, the structure of your files will largely depend on the project's scale and the team's size. It could range from a simple setup with just a few folders to a complex structure dividing the project into sub-projects or micro-frontends for larger-scale applications.

Step by Step Approach

Basic File Structure

In the simplest form, such as those generated by boilerplates or CLI tools like create-react-app, Vite, or Next.js without using templates, the structure typically includes an entry point and a 'components' folder. This basic setup offers a foundational framework which can be expanded as needed.

Detailed Components Folder

The 'components' folder can be subdivided into two main categories:

UI Components: This folder, possibly named 'ui', would contain stateless UI components like buttons, tabs, and accordions. These components may have internal states but don't rely on external states, functioning primarily through props.

Logic or Business Components: The other subdivision, possibly named 'business' or 'logic', would house components that are more complex and intertwined with the application's logic or business aspects. An example would be a user card component with detailed information like avatar, name, email, and job description. These components might also interact with APIs and are reused across different parts of the project.

The categorization of components into 'ui' or 'logic/business' depends on their complexity and functionality. A UI-focused component like a simple button would fit into the 'ui' category, whereas a component involving more complex logic and data interaction would be more suited for the 'logic/business' category.

Hooks!

Alongside the 'components' folder within the source directory, another essential folder named "hooks" can be established. This folder is particularly relevant in React development, as it houses custom hooks. Ideally, these hooks should be universally applicable across the entire project. However, if a hook is intrinsically linked to a specific module, page, or substantial entity, it can be placed within that respective context. This flexibility underlines the absence of a rigid structure; adaptability is key, but with careful management to prevent disarray in the project.

The 'hooks' folder typically contains various custom hooks, each serving a distinct purpose. A common and highly useful example is the 'useClickOutside' hook. This hook is designed to detect clicks outside of a component, enabling specific actions in response. For instance, in a custom dropdown menu, this hook helps in automatically closing the menu when a click is detected outside its boundaries. The implementation of this hook may vary, but its function is clear from its name: it reacts to external clicks to close or modify elements accordingly. Such a custom hook, like 'useClickOutside', would be located within the 'hooks' folder, readily accessible for integration into components like dropdowns.

Organizing Styles

In our exploration of file organization within a React project, a crucial aspect to address is the 'styles' folder. This area, often vast and multifaceted, requires careful division. In my experience, particularly with projects utilizing SASS, the approach to organizing styles is twofold.

Firstly, there are global or shared styles that transcend individual components. These include mixins, functions, and overrides for third-party tools. Such styles don't belong to any single component but rather need a broader scope, hence the creation of a dedicated 'styles' folder. This higher-level repository ensures that overarching styles have a proper place within the project structure.

Working with SASS, I prefer adhering to the 7-1 SASS pattern, which effectively segments the 'styles' folder into seven sub-folders: 'base', 'components', 'pages', 'layout', 'vendors', 'utils', and 'themes'. This structured approach to managing styles is not just about segregating files arbitrarily; it follows a deliberate pattern to enhance organization and maintainability. This systematic arrangement allows any new team member to quickly grasp the structure and logic behind the style organization.

Regarding component-specific styles, the component architecture approach recommends a slightly different strategy. When a component has its own unique styles, and you're working with SASS, CSS, or LESS, it's advisable to place the style file directly adjacent to the component's logic file. For instance, a 'Button' component would have a corresponding folder named 'Button', containing two files: one with the React logic and the other with its associated styles. This methodology ensures that component-level styles are tightly coupled with their respective components, fostering a more modular and intuitive structure.

Overall, whether dealing with project-level styles in the 'styles' folder or component-specific styles alongside their logic files, the key is to establish a logical, documented structure. This approach not only aids in current project maintenance but also ensures that future contributors can easily understand, navigate, and extend the project's styling architecture.

The Average File Structure

In the realm of project organization, particularly for moderate-sized projects, there's a common practice of having a 'pages' folder. This folder is structured such that each subfolder represents a distinct page of the application, like the home page, about us page, contact us page, and so on. Each page is appropriately named and nested within the 'pages' folder, ensuring an organized and intuitive layout for the project's various pages.

Additionally, these pages often share a common layout, leading to the necessity of a 'layouts' folder. Positioned alongside the 'pages' folder, 'layouts' contains the shared layout templates used across different pages. For instance, a typical layout might include a header, footer, and a central content area. When a new page is created in a React-based project, it is composed with this main layout, incorporating the header and footer by default. The content area is what each specific page uniquely provides. Therefore, the introduction of a 'layouts' folder complements the 'pages' folder, streamlining the structure and design of each page.

Furthermore, some project structures distinguish between 'components' and 'containers'. This distinction harks back to the early days of React, where the concept of 'dumb' (stateless) components and 'smart' (stateful) components, or containers, was prevalent. In this context, a 'container' is typically a stateful component that represents a page or a significant part of it. This approach sees the 'container' as a large component comprising several smaller, stateless components, possibly including shared state elements. The choice between using a 'containers' folder versus a 'pages' folder varies among developers, but ultimately, both serve to organize larger, more complex components within the project.

In summary, the choice of folders like 'components', 'layouts', and 'containers' or 'pages' reflects different schools of thought in project organization. Each serves a specific purpose: 'pages' for individual pages, 'layouts' for shared design elements across pages, and 'containers' or 'components' for managing stateful and stateless elements respectively.

Feature-First (Module-First) File Structure

As a project expands, its structure often evolves to accommodate larger and more complex components, leading us to consider concepts like 'modules' and 'features'. In a structure often referred to as 'feature-first' or 'module-first', these two terms are essentially interchangeable. This approach significantly alters the traditional organization of folders such as components, styles, and hooks, which are now shared across various features or modules.

For instance, a universally used UI component, like a 'Button', would reside in a shared, accessible location outside specific modules. With the introduction of this 'feature-first' or 'module-first' approach, the existence of a separate 'pages' folder becomes redundant. This is because modules or features, as newly introduced entities, are more comprehensive and encompass aspects like pages.

To illustrate, let's take a module named 'CRM' (Customer Relationship Management), representing a business feature in a project. This module isn't just a single element; it's akin to a mini-project within the larger project. It includes multiple pages, reusable components specific to CRM, and its unique business and workflow processes.

When delving into a module like CRM, you'll discover a structure mirroring the main project source folder. Inside, there are subfolders named 'components', 'hooks', 'layouts', 'pages', and 'styles', all specific to the CRM module. Additionally, there's a central file, such as 'index.js', 'crm.js', 'jsx', or 'tsx' (depending on the programming language), serving as the module's entry point. Alongside this, a 'routes' file details the internal routes of the CRM module. Each module manages its own routing, reflecting its specific functionalities.

This 'module-first' or 'feature-first' structure effectively creates a self-contained ecosystem within each module, ensuring that every aspect of a module, from components to styles, is organized and easily navigable. This approach is particularly beneficial for large-scale projects, where clear segregation and modularization of features or business areas are essential for maintainability and scalability.

At times, it's practical to blend the 'feature-first' or 'module-first' approach with the use of 'containers' or 'pages'. This is particularly relevant when dealing with shared pages that are universally applicable across all modules or features. For instance, a 404 error page is a common requirement that doesn't warrant individual versions for each module or feature. It's more sensible to place such universal pages at the top level of the project structure.

Essential Folders

In the projects I develop, I typically consider incorporating several essential folders, each serving a distinct purpose in building a robust file structure. These folders are integral to answering common structural questions, like where to place utility functions.

helpers: This folder contains core helper functions used throughout the project. Examples include "httpClient", "XHRResolver", "Logger", etc., which provide fundamental support across various components.
utils: Here, I place small, pure functions that perform specific tasks. Functions like "convertHexToRGBA" and "buildQueryString" are examples of utility functions that handle precise operations.
data & services along with transformers: This setup aligns with the three-tier architecture principle, with transformers adding an extra layer for modifying or reshaping payload or response data. It's a structured way to manage data processing and service interaction.
types or interfaces: This folder is dedicated to storing types and interfaces, crucial for ensuring type safety and clear contract definitions within the code.
configs: For static configurations used throughout the project, such as default values for certain variables or a default date format, this folder is the designated place.
enums: I use the enums folder to store enumeration types, which helps in defining a set of named constants, improving the readability and maintainability of the code.
translations: If the project supports multiple languages, this folder contains the translation files necessary for internationalization.

These folder names and their usage can be adapted as needed. Depending on the specific requirements and scale of your project, you might choose to use all of these folders or only a selection. The flexibility to modify and tailor these folders to your project's needs is a key aspect of this structure.

Rare (Extrem) File Structure

The most complex file structure I'll discuss is for exceptionally large projects, often managed by multiple teams, each focusing on a distinct business segment. This setup is known as a micro front-end architecture.

Previously, I wrote an article about Micro-Frontend, explaining that this concept involves different teams handling separate parts of a product, from the front-end to the database. These distinct segments are then integrated under a container or shell to form a cohesive application. In the context of front-end development, each team might adopt different file structures, such as a focus on pages and layouts or adopting a feature-first or module-first approach. The choice of structure depends on the project's scale and the specific business area each team is responsible for.

Another scenario I covered in previous article involves managing a large project through a monorepo, which presents its unique file structure challenges. In a monorepo setup, there's typically a root folder named 'packages'. Within 'packages', you find various subfolders for different segments like 'helpers', 'utilities', 'CRM', 'project management', 'UI', and 'components'. The division of these packages is flexible, depending on the project's needs, and each package essentially functions as a standalone project. For example, expanding the 'CRM' folder under 'packages' reveals a complete project setup, with its components, hooks, styles, and other elements. If extracted from the monorepo, it should be able to operate independently.

In some cases, a monorepo might not be structured as a micro front-end but simply as a collection of packages. These packages could include reusable components, shared styles, or distinct projects. Each package, while conforming to the overarching monorepo structure, follows its internal organization. This could range from a basic setup with components and containers to more elaborate structures incorporating features or modules. For instance, a package named 'project management' might contain a 'features' folder, managing all aspects related to project management within that package.

In summary, the file structure in a micro front-end or a monorepo is multifaceted, catering to the complexity and scale of large projects. Each package or segment within this setup is organized in a way that allows it to function both as part of the larger whole and as an independent entity, ensuring modularity and flexibility in the project's architecture.

Outro

There is no universally accepted school of thought or definitive catalog dictating file structure in project development. Instead, the organization of files is largely influenced by factors such as the size and scope of the team, the business objectives, and the project's anticipated lifespan. This variability underscores the importance of collaboration between the front-end lead or senior front-end developers and the business and architectural teams. Such engagement is crucial for understanding the project's vision, pipeline, and end goals, which could range from a few months to several years.

The involvement of the front-end team from the outset is essential. It allows them to align their approach with the broader objectives, influencing key aspects like the file structure. Foreknowledge of the project's trajectory – whether it's adding features over four years or just one – is vital for designing a scalable and adaptable structure from day one. However, it's important to recognize that no structure is permanent. Flexibility and periodic adjustments are necessary, though frequent overhauls should be avoided to prevent disruptions.

The goal is to establish a file structure that is robust enough to last for several years, anticipating significant feature expansions. This proactive approach is preferable to a reactive one, where the structure becomes cumbersome and intertwined, necessitating major restructuring. As the project evolves, various factors, such as performance enhancements, team expansion, or shifting business requirements, may necessitate revisiting and modifying the file structure.

It's crucial to understand that a file structure is not static. It evolves, potentially changing every six months or even every three months, based on numerous variables: team dynamics, business goals, feature complexity, and team expansion. These factors dictate how the file structure should be adapted or divided to create a conducive environment for efficient work and future extensions.

In summary, while there is no one-size-fits-all approach to file structuring in project development, the key lies in maintaining a balance between flexibility and foresight. The structure should be adaptable to accommodate changes yet thoughtfully planned to sustain the project's growth and evolution over time.

Frontend Architecture: The Architecture - Summary

Hamed Farag — Sat, 23 Sep 2023 11:42:07 +0000

What is Frontend Architecture after all this?

Frontend architecture refers to the structure and organization of the client-side part of a web application and converting the architectural drivers into a technical solution, technical roadmap, communicating the vision to a number of stakeholders both inside and outside the software development team, and introducing the technical leadership.

What is the difference between Architecture and design?

"Architecture" typically refers to the high-level structural decisions that have a significant impact on the system and are difficult to change once made. On the other hand, "design" encompasses the detailed decisions and implementations that are more flexible and can be adjusted without major consequences.

What are the Architectural Drivers?

Functional Requirements: The technical functions that represent the main product features. These functions describe how the system behaves and what it should do.
Quality Attributes: Quality Attributes are a set of criteria that describe how a software system should behave and perform rather than specifying specific functionalities or features.
Constraints: Constraints can encompass various factors, such as technical limitations, resource constraints, or environmental considerations.
Principles: The Standards or the Guidelines that should be applied while implementing and creating the Frontend solution.

References

Book: Software Architecture for Developers by @simonbrown
Book: Frontend Architecture for Design System by Micah Godbolt
Youtube: GOTO Conferences

Frontend Architecture: The Architecture (Part. 6)

Hamed Farag — Sat, 23 Sep 2023 08:42:04 +0000

4. Principles

Okay, each one of us wants to establish a standard or utilize a pre-existing one to ensure consistency in the frontend solution. This standard should also facilitate a quick onboarding process for new team members, enabling them to understand it quickly.

Creating standards and principles for your development team is a crucial step in ensuring consistency and efficiency in your projects. We have two pillars, development, and architecture, let's explore how we can build standards around each of them:

Development Principles

The principle that many frontend engineers instantly think of relates to the way in which software should be developed

Coding Guidelines: Establish clear coding conventions and style guides for your team. This includes naming conventions, code formatting, and commenting standards. Tools like ESLint and Prettier can help enforce these guidelines.
Style Guidelines: The method by which your team approaches styling can encompass CSS, involve a pre-processor language, incorporate CSS-in-JS, or make use of a utility-first CSS library. Depending on your choice, it is imperative to carefully select the appropriate methodology, design an effective file structure, and determine whether to utilize existing reusable styles or craft a customized solution.
Document your work: How to document your work to communicate it to your teammates. You will create reusable components. helpers, utils, write comments for the complex parts, etc. All these parts you should care about documenting them in a proper way using basic documentation files and comments or using a powerful documentation tool.
Logging and Monitoring: How will you monitor your application to measure performance and to monitor for production bugs?
Testing: Define testing standards, including unit tests, integration tests, and end-to-end tests. Decide on testing frameworks and coverage targets.
Version Control: Define a version control strategy using Git. Set rules for branching, committing, and merging code. Consider using a branching model like Gitflow.
Code Reviews: Implement a process for peer code reviews to catch issues early and maintain code quality. Specify who should review the code and the criteria for approval.
JS & UI Frameworks: Which JavaScrip Framework you will use in your next project, would you like to use a ready-made UI framework, you have options and you have to choose one.
CI/CD: Establish automated build and deployment pipelines to ensure code is consistently built, tested, and deployed.
Responsiveness: Your application will be mobile-first or desktop-first? it will be better if you know this information from day one.
Accessibility: You should care about Semantic HTML and ARIA attributes from day one.
CSR, SSR, SSG: Considering the specific requirements of your project, you should decide whether to opt for Client-Side Rendering (CSR) or if there is a need to prioritize Search Engine Optimization (SEO), in which case Server-Side Rendering (SSR) or Static Site Generation (SSG) would be more suitable.
Multiple Languages: Should your project support more than one language? Make sure you do not write static content directly into the code or into the HTML.
Design System: Do you have a centralized location for reusable components, guidelines, and well-defined standards? Having this is crucial for constructing a clean application.
APIs: One of the critical aspects to consider is establishing a robust foundation for consuming backend APIs in a standardized and efficient manner.
State Management: Do we truly need to adopt a state management library and use it in general, or is it necessary only to use it for sharing specific pieces of data? Determining whether to use it or not is a crucial decision.
Default Configuration: It's advisable to centralize all default and shared values and configurations; otherwise, it can become chaotic.

Architecture Principles

There are also some principles that relate to how the frontend should be structured. For example

Main Architecture (Micro-frontend vs. Monolithic): When comparing monolithic frontends and micro-frontends, there are several factors to consider. Scalability and modularity are critical for large projects, and micro-frontends are better suited for these types of projects. However, monolithic front ends are more uncomplicated and more straightforward to develop and maintain.
MVC vs. CBA: When React was published to the public in 2013, it came with the CBA (Component-Based Architecture), CBA is an approach where you build an application by creating self-contained and reusable components, with each component encapsulating its logic and UI. MVC (Model-View-Controller) is an architectural pattern where you separate an application into three main components: Model (data and logic), View (user interface), and Controller (handles user input and updates Model and View). You can go with one of them based on your chosen framework or even you can combine them.
Repo Type: Polyrepo vs. Monorepo: Polyrepo architecture is a software development approach in which each project or component is housed in its own individual repository. This stands in contrast to Monorepo architecture, where all the source code for a project or a group of related projects resides within a single repository. Your choice between these approaches should be determined by factors such as the size of your frontend project, your business requirements, team size, deployment processes, and the need to share code. Each approach has its own set of advantages and disadvantages.
Layering Strategy: One of the most popular architectural patterns worth discussing is the Three-tier architecture. This architecture is a design pattern that separates applications into UI layers (client layers), application layers, and database layers. Each layer has a specific responsibility and communicates with the other layers through well-defined interfaces. This is the definition, but usually, I tweak this pattern and use it in a little different way:
- Database Layer (Data Layer): This layer is responsible for making API calls using promise-based HTTP Clients like Axios or Fetch. Regardless of the approach you choose, this is the sole location for API calls.
- Application Layer (Service Layer): After creating the function responsible for fetching data in the Data Layer, you should invoke this function in the Service Layer to either receive or send data. In this layer, you may execute business logic, modify the data's structure before sending or after receiving it using Transformer functions.
- Transformer Layer (Normalization or Mapping Layer): This is an optional layer that contains functions responsible for altering the data's structure. For example, you can use this layer to change date formats, adjust property names in received objects, or reshape the data you intend to send to the data layer.
- UI Layer: This layer typically comprises UI components, containers, pages, and layouts. Additionally, it should interact with the Service Layer solely to retrieve data for binding and rendering purposes.

Placement of business logic: As mentioned above, we should place the business logic in the Service layer or, any other place, but with one condition, to be a centralized place and not to be a part of something else (Part of a Component for example).
Reusable Component (Dump Component): Use ready-made components to build your application or build these components from scratch based on the need and to be well-documented and not have a side-effect.
Feature-First vs. Type-First vs. Container(Page)-First File Structure: How you can organize your file, there are several approaches for organizing your files inside your frontend project. Choose one or combine more than one, organize your file, and stick with it.

Frontend Architecture: The Architecture (Part. 5)

Hamed Farag — Mon, 11 Sep 2023 19:31:00 +0000

3. Constraints

Software is a part of our life, and our life is a part of this world, and this world has constraints, For example, human can not fly like Superman, and that is why software application also faces some constraints, These constraints can drive shape and influence the architecture of a software system and that is why there is not a standard or guidelines for each type of software, like if you are planning to develop a finance application, you have to apply standard called (The Only Guidelines of how to implement and deliver a finance software applications), based on the constraints and what we are facing per environment we have to take different decisions based on the situation.

We have different constraints in shape and size, let's take a look at them.

Time to deliver, Scope, and Budget constraints

Time and budget are probably the constraints that most software developers are familiar with, and most of the time we usually ask about when to deliver this feature and whether can we buy this library or that framework or not

I have a funny story about a unique situation. I was once on a team called "the midnight team." To understand how we got there, let's go back a bit.
In one of my past projects, our project manager made a deal with a client. They agreed that our company would finish the project six months after we started it, which happened during a meeting between our project manager and the client's team. When our project manager came back to our company, they told our bosses that we got the project, but there was a small problem: we didn't have a team ready!
So, our bosses had to act fast. They gathered some developers from different parts of the company to create a team, which we called "the midnight team." These developers worked on the project after their normal work hours. No matter what challenges we faced or how late we worked, we were determined to finish the project in six months. Surprisingly, we did it, but we all felt a bit crazy by the end!

For the Scope constraint, usually, the scope is defined during the discovery phase where the business analyst extracts all the business goals and requirements and learns about the business processes to determine the best functionality for solving a particular issue for both the business and its customer, this for the service projects (custom solution for a client), and for the product projects at least we have a list of features we need to implement and we can prioritize them by adding some tags like MVP, must-have, nice-to-have and so on, and then create a pipeline and after that we can start the sprints and etc.
Of course, as the development process goes, and business goals change, the scope can change as well. However, if you have a manager who lacks maturity or doesn't have a technical background (or both), they might alter the project based on market or client demands without considering the original deadline. I've worked with some managers like this. They modify the scope but still expect us to deliver by the same deadline. They often abuse Agile methods to the extreme. In the end, upper management is wondering why the team couldn't meet the agreed-upon deadline!

The Budget constraints may affect some aspects, One of them, we don't have a budget to buy a library or a framework that will accelerate the development process, we don't have a good budget for hiring good developers, we have only some local servers for deployments and also for testing the software application, and later on will deploy on the cloud before the delivery date!.

Technology constraints

I strongly dislike React! We should go with Angular instead. One of our clients insisted on this, and another client completely avoided open-source libraries with community support. They wanted us to use commercial libraries and software so we could get formal support in case of issues.
Additionally, some organizations have specific lists of approved technologies for building software. They do this for various reasons, like reducing the variety of technologies they need to manage, maintain, operate, and purchase licenses for.
Integrating with some existing systems

In the past, I worked on a product mainly designed for large organizations. One crucial aspect our clients were concerned about was how well our product could work with their existing systems, such as HR systems and knowledge base systems, etc. To address this vital requirement, we began modifying our product. We exposed certain APIs and developed a UI framework that allowed external teams to create custom widgets and pages.

Target deployment platform

When it comes to Cloud versus On-premises, imagine this scenario: You're working on a frontend solution, and naturally, you're using some third-party libraries hosted on Content Delivery Networks (CDNs). Additionally, you're relying on an external service to get some information, like a weather forecasting service or a currency rate service.
Now, here's the plot twist: One of your clients - and this is a real one with some huge government entities - has a strong distrust for cloud services. And they insist that you deploy this software on servers located within their own network (On-premises).

I faced this situation 3 times with 3 different products. Clients had their own internal network and one of them had his own cloud without internet access!, except for critical software and operating system updates. This posed several challenges.
For example, how to update your deployed software application periodically. Is it by using VPN access or by using a flash drive? Another challenge arises when dealing with third-party libraries - you have to download them separately and include them in your solution.
For the external services, we have two options, deprecate these features or make an exceptional policy through the firewall to enable access to them.

Fear from the Unknown

Some organizations and even some people, and they are a lot, fear of latest technologies, libraries, or frameworks, The comfort zone here is controlling the situation, and fear of the unknown is the engine, they are used to working with certain technologies and frameworks and they don't want to take the risk for trying new things even if these things will make their life easier.

I remember when I began my career as a frontend engineer and first started working with React. This was back in 2016, and I was employed at a software company with nearly 300 developers. Interestingly, my team mate and I were the only ones using React, while the entire company primarily used Microsoft Technologies, Angular, and a few teams were working with Java technologies. We sort of felt like we were outcasting people.
Also, in 2013, I had some experience with a UI library called knockout.js. I recommended it to my team leader at the time, especially since we were creating a Proof of Concept (POC) for one of our clients. The POC involved a Mobile Web App, a listing, and two forms. My team leader, however, insisted on using asp.net web forms to build this POC, while I created my part, the page, with knockout.js. It was quite an unusual experience

Internal intellectual property

When you need to find a library or framework to solve some problem you are facing, there is a high probability there is an open-source or commercial product out there that suits your needs. But this is not good enough for some people though, and it is not uncommon to find organizations with their own internal libraries, frameworks, and code generators that you must use, despite whether they actually work properly. Back in 2012, I used an internal code generator tool - used internally in my previous organization and built by senior developers and was like CodeSmith Generator - for generating some pages with CRUD operations from UI to the database, but I remember that the UI option was not working fine, and you need to alter some columns in the database, some copy/paste here and there.

People constraints

One of the main constraint from my point of view is your capability of your work mate. For Example

How large is your development team?
What skills do they have?
How quickly can you scale your development team if needed?
Are you able to provide training, consulting, and specialists if needed?
If you are handing over your software after delivery, will the supporting team have the same skills as your development team or you will handle both sides?
Is there a mentor or a senior engineer you can consult in case you are using a new technology?

There will be an overhead if you ask a React team to build an Angular project, so you need to take people into account whenever you are architecting a frontend project.

Organizational constraints

There are sometimes other constraints that you will need to be aware of, including:

Is the software system part of a strategic implementation? The answer to this question can either add or remove constraints.
Organizational politics can sometimes prevent you from implementing the solution that you really want to.

I have something funny here to talk about, One of the products I was working on, was very successful, and we already have five clients using it. It was based on React and .Net Technologies. Due to some politics and top-management decisions, we should be a partner with a very well-known Enterprise company that developing an enterprise platform, The top management decided to close our successful product, terminated all contracts with the five clients, and re-built our product again from scratch based on this Enterprise platform and they offered to the five clients to upgrade to the new product but they should pay 20x (literally it was 20x without exaggeration), and of course, all clients rejected this "upgrade"!.

Final Word

Generally, constraints usually seem "bad", but they are often imposed for a good reason. For example, large organizations want to limit the number of tools and technologies because they don't want to support and maintain all these technologies.

You should know most of the constraints as early as you can because these constraints will impact your architecture directly and will make you take significant decisions. Also, the constraints are like the non-functional, some constraints are more important than others.

In the end, constraints are usually obstacles that you need to work around but sometimes you can trade off against one other.

Frontend Architecture: The Architecture (Part. 4)

Hamed Farag — Sun, 27 Aug 2023 17:42:06 +0000

2. Architectural Drivers (Part 2)

2. Non-Functional Requirements (Quality Attributes)

11. Usability

Usability is all about how easy it is for people to use a website or app and get the results they want. Think of it like this: when someone uses a platform, it should work well, be efficient, and make them happy.

For example, let's say you are building a website using React, like a travel blog where you showcase your landscape photography. Usability in this context means that visitors to your website should be able to easily navigate through your posts, see your pictures, and find the information they're looking for without getting frustrated.

Now, the technical side of usability involves making your website accessible to everyone, including those with disabilities. You can do this by using things like assistive technology, which helps people who use screen readers or other tools to access your site. Also, it's important to provide text descriptions for images and any multimedia content you have. This way, even if someone can't see the images, they'll still understand what's going on.

12. Responsiveness

Responsiveness can indeed refer to both aspects in the context of web development.

Responsive Web Design: It's about making websites that work well on different devices like phones, tablets, and computers. So when you open a website on your phone, it looks good and works smoothly.
Quick and Smooth: It also means that when you use a website, like clicking buttons or typing things, it should respond quickly without any delays. Imagine using an app that feels really fast and doesn't make you wait, and so on.

We've already covered ways to make your app run smoothly and perform better in general. Now, let's talk about Responsive Web Design.

Responsive Web Design (RWD) is a web design approach to make web pages render well on all screen sizes and resolutions while ensuring good usability. It is the way to design for a multi-device web.

Around 10 years ago, you might have come across this method while using Facebook on your phone's browser. Back then, web developers used to make a separate website for small screens. These sites usually started with m. or mobile. in the domain. So, as a web developer, you had to take care of two websites - the main one for desktop computers and another for small devices like phones.

Things changed when Ethan Marcotte published an article on Responsive Web Design. This article illuminated the entire industry by building upon existing disciplines and concepts. He introduced these principles to guide the creation of websites that could adapt to the user's device size and shape themselves according to the viewport.

Responsive Web Design was not some new or emerging technology, but it just is collection of tools and techniques as follow:

Fluid grids: Use percentage-based widths rather than fixed pixel dimensions.
Flexible images: image to be 100%-width to fill the container, and the container will adapt it with the viewport.
Media queries: specify different styles for different viewport sizes.

Before Ethan wrote his article about responsive web design (RWD), the methods he talked about were already present in web browsers for many years. However, Ethan's explanation of RWD made the solution that everyone was urgently seeking very clear and understandable.

13. Compatibility

In this context (Frontend Architecture) we will focus on the Browser Compatibility.

Browser compatibility is the ability of a website or web application to function across different web browsers and operating systems. Moreover, having a cross-browser-compatible website ensures you’re providing a consistent and optimal user experience across different browsers. Users should be able to access and interact with a website or web application regardless of the browser they prefer.

I remember back when I worked as a .Net developer. I had a client who insisted that their web application had to work perfectly on Internet Explorer 8 and 9. It was quite a tough task. But nowadays, Internet Explorer is no longer used because it couldn't keep up with the latest web standards and caused compatibility issues. Getting rid of it was definitely one of the best decisions in the field of web development.

But now, browser compatibility has become easier to handle in recent years due to several factors:

Standardization: The development and adoption of web standards by major browser vendors have improved consistency across different browsers. Organizations like the World Wide Web Consortium (W3C) help create and maintain these standards, ensuring that browser behavior aligns more closely.
Modern Browsers: Modern browsers are built with better compliance to web standards, which reduces the need for complex workarounds or browser-specific code.
Polyfills and Transpilers: Tools like Babel and polyfills help bridge the gap between older and newer browser versions by enabling the use of new features in older browsers.
Developer Tools: Modern browsers offer comprehensive developer tools that help identify and fix compatibility issues more efficiently.
Testing Tools: There are various testing tools available that simulate different browsers and platforms, making it easier to catch compatibility problems during development.
Community Resources: The web development community actively shares best practices, guides, and solutions for browser compatibility challenges, making it easier for developers to find help when needed.
Component Libraries and Frameworks: Frameworks like React offer abstractions that help manage browser inconsistencies, enabling developers to focus on building features rather than worrying about compatibility.
Feature Detection: Developers can use feature detection techniques to determine whether a certain browser supports a specific feature before implementing it, reducing the likelihood of compatibility issues.

14. Testability

Testability refers to how easily developers and others can test the application.

I've personally encountered codebases where the design didn't prioritize making it easy to test, especially when it comes to React-based components. A lot of developers tend to build these components as one big piece to handle many business needs, instead of breaking them into smaller parts that can be tested more easily. For Example, Creating a Table component that lists data by fetching it from an external resource (API), and also contains a form to add a new item in the table and to be synced with the backend through another API. We can break this puffy component by creating a component for listing, component for the form, and service functions for each API so that we can create some unit testing for all of them without much pain.

So, to achieve testability, It's a good idea to make sure that a big part of your frontend code is tested – aiming for around 70% to 80% coverage is ideal. These tests are meant to check individual parts, like components and functions, all on their own. This helps ensure everything works well.

15. Reliability

Reliability refers to the quality of being trustworthy and consistent over time. It often pertains to the ability of a system, product, or process to consistently perform its intended functions without failures or errors.

Sometimes, we call this MTBF/MTTF, which stands for Mean Time Between/To Failures. It's about how consistent software behaves. When software doesn't do what we expect, it becomes unreliable.

A common way to check reliability is by counting software problems (bugs) and comparing them to the amount of code.

To make software better and more reliable, the key is to test it a lot. So, software that's easy to test is usually more dependable than software that's harder to test.

16. Disaster Recovery

What steps would you take if access to your files (assets) was restricted in certain locations, or if you experienced data loss due to a hard disk failure or server issues? How would you go about developing a disaster recovery plan to minimize potential risks that could arise at any moment?

A while ago, we faced a strange problem. Some third-party libraries we used in our project, which we get from a certain place (CDN Provider), were suddenly not working in a certain country. We couldn't change where we got these third-party libraries from right then. So, we fixed this problem by changing the addresses of these libraries (pointing to a custom proxy server) in our frontend project, and we used this proxy server to route these URLs to the CDN provider again!

One way to prevent your project from failing due to unexpected errors or new updates is to have a backup plan. This means having a plan to go back to a stable version of your project if something goes wrong.

There are different ways to do this. One method is to use versioning and create labels (tags) for each update. This way, if there's a problem with the latest update, you can go back to the previous stable version of your project.

It's also important to store your code in a safe place. You can use a cloud service like GitHub or BitBucket to keep your code safe. It's a good idea to have a clear process for adding your code to these services, like creating different branches for different features. This helps prevent loss of code in case of server failures or other problems.

I have a story to share: In a previous company, we used a tool called TFS (Team Foundation Server) to store our code before using Git. TFS was hosted on our own servers. Once, one of the servers had a hard disk failure, and we lost the source code of one of our projects. We had to gather the latest code from developers' machines, manually combine it, and found out that six days of work was lost. We had to redo everything from scratch! This situation taught us the importance of proper code storage and backup plans.

Working with Non-fucntional requirements

After listing a set of quality attributes that could be relevant to a frontend project, what should I pay attention to? Should I aim to incorporate all of them into my next project? Are these attributes equally important?

Firstly, it's important to note that these quality attributes don't hold the same level of importance. Some might be more suitable than others based on your work environment and the nature of the frontend project you're working on. To begin with, familiarize yourself with the prevalent quality attributes in your field. Prioritize those when you begin on creating a new system or making changes to an existing one.

Non-functional requirements (Quality Attributes) can be a bit challenging, as they differ in nature from functional requirements. When you're collecting requirements, your client typically provides a wish-list of what they want the software system to accomplish. There are established methods for capturing this information, such as user stories, use cases, traditional requirement specifications, acceptance criteria, and more. But, this is not the case with Quality attributes though.

There are three phases to get the actual non-functional requirements from the client

Capture
Filter & Refine
Challenge

Capture

Usually, clients give a lot of requests for what they want a software system to do. But they often forget to mention things about Quality Attributes, like wanting the system to load pages in less than 2 seconds, which is about performance. You have to ask about these Quality Attributes to know what they want. But it can be tricky. For example, if you ask about how easy it should be to use the system, they might just say "make it as easy as possible" and not give you more details. So, you need to ask the right questions

Throughout my career, there was only one case where someone directly asked for a non-functional requirement. This request was related to performance. The requirement was quite demanding: "Ensure that all pages of the system load in less than one second!" This was a challenging task since the project, built on a pre-existing product, naturally had performance issues and loaded pages rather slowly.

Refine

Back again to ask the right questions, these questions must be tricky enough to get the non-functional requirements or you might be lucky enough to receive this information within the functional requirements. Once you receive the these non-functional requirements, you have to discuss them with the client to make sure that the client understand these requirements and also to set the expectations.
For Example, the client may access to support the accessibility and that is it. So it is a wide requirement and we need to ask some question to refine it

What are the categories of users with disabilities that need to be considered to ensure accessibility support?
What are the recommended screen resolutions that a system should be designed to support?
Do you have existing accessibility guidelines?
Can we prioritize accessibility features?
Can we include accessibility in QA testing?

Consequently, we now have a foundation for initiating discussions. Should you be able to assign specific measures to the non-functional aspects, you can then formulate acceptance criteria and assess them in an objective manner.

Challenge

The "Trade-Off" is the secret key, imagine the following scenario, you are asking the client about a specific feature, and without any hesitation, his answer will be "Yes"! so one by one every user stories will be important and will be hard for the team to set the priority for each one. In the end, everything will be very important and should be included in the product in the first release!

Indeed, the concept of "Trade-Off" holds significance here. For example, when a client requests a particular feature, after your assessment and team deliberation, the feature might come with a cost of X. However, there's a possibility to provide a simpler version in phases, reducing the cost to X/2. Upon presenting this option to the client, they might agree to proceed with this approach.

In our domain, nearly everything can be achieved, but each choice involves a trade-off. By explaining these trade-offs, we can determine the optimal solution for a given situation.

Frontend Architecture: The Architecture (Part. 3)

Hamed Farag — Sat, 19 Aug 2023 16:11:19 +0000

2. Architectural Drivers

Once we know what Frontend Architecture means, we must consider what we need when designing a frontend project. No matter the approach we take, whether it's traditional and planned or more flexible and adaptable, certain common factors influence the final Frontend Architecture. These factors guide how we structure and build the frontend part of a software project.

Architectural drivers are important things that we must consider when designing a software system (Significant decisions). They have a big impact on how the software will be built. These drivers help shape and guide the design of the software's architecture. They basically tell us what we need to do and why we need to do it. When we create the software's architecture, we make sure it meets these important drivers. By doing that, we ensure that the software will work well and meet the goals we have set for it.

1. Functional Requirements

The technical functions that represent the main product features. These functions describe how the system behaves and what it should do.

For Example, we have web-based to-do list application as the product, and we'll focus on the frontend technical functions that represent its main features:

User Interface (UI): The frontend should provide a user-friendly and visually appealing interface for users to interact with the to-do list application. It should have a clear layout with sections for displaying tasks, adding new tasks, marking tasks as completed, and deleting tasks.

Task Display: The frontend should fetch and display the list of tasks from the backend server or local storage. Each task should show relevant details such as title, due date, and status (completed or pending).

Add Task: The frontend should allow users to enter new tasks with titles and optional due dates. It should validate the input and prevent users from adding empty tasks.

Task Completion: The frontend should provide a way for users to mark tasks as completed. Completed tasks should be visually distinguished from pending tasks.

Task Deletion: The frontend should enable users to delete tasks they no longer need. It should prompt users for confirmation before permanently removing a task.

Task Editing: The frontend could allow users to edit task details, such as updating the title or due date. It should provide a smooth and intuitive editing experience.

Task Filtering and Sorting: The frontend could include options for users to filter tasks based on completion status (completed/pending) or due date. It could also allow users to sort tasks based on different criteria, such as alphabetical order or due date.

Error Handling: The frontend should handle errors gracefully and display meaningful error messages if something goes wrong, such as failed server requests or validation errors.

Responsive Design: The frontend should be designed to work well on different devices and screen sizes, such as desktops, tablets, and mobile phones.

2. Non-Functional Requirements (Quality Attributes)

Non-Functional Requirements (NFRs), also known as Quality Attributes or quality concerns, are a set of criteria that describe how a software system should behave and perform rather than specifying specific functionalities or features. While functional requirements deal with what the system should do, non-functional requirements address how well it should do it. These requirements are essential for defining the overall quality, usability, and performance of a software application. NFRs help ensure that the system meets the desired levels of reliability, scalability, maintainability, security, and other crucial aspects.

Here are some common Non-Functional Requirements as follow:

1. Performance

Performance is about loading something fast, without lagging and without much time to load.
We have two main thing we can talk about within this topic, Rendering the Web Page and load data and files (assets).

Web Page Rendering

If you are concerned with an application that targets low-performance machines, you should take care of rendering your website at a minimum cost.
The Key here is the** Critical Rendering Path (CRP)**. CRP cares about converting the HTML, CSS, and JavaScript into pixels on the screen. And by optimizing the critical render path we can improve render performance.

Load Data and Files

Back again to the Performance definition - about loading something fast - usually we are talking about the response time or the latency.

Response Time: Response time refers to the time it takes for a system to respond to a user's action or request.
Latency: Latency refers to the delay or time lag between sending a request and receiving a response.

Lets explain it in simple example, Imagine there are 2 people who want to print something using a printer. The printer takes 10 seconds to print each paper.
The first person's paper gets printed right away, so he wait for 10 seconds. he don't have to wait before their paper starts printing.
The second person waits for 10 seconds for his turn and then his paper takes 10 seconds to print. So, they wait a total of 20 seconds (10 seconds for waiting and 10 seconds for printing).
So, We conclude that that Response Time = Latency + Process Time.

Based on the above explanation we have a lot of areas we can enhance and optimize as follow

Optimize Images: Use compressed and appropriately sized images to reduce load times without sacrificing quality. Consider using responsive images and modern formats like WebP.
Minimize HTTP Requests: Reduce the number of external resources (CSS, JavaScript, fonts) to minimize the number of HTTP requests the browser needs to make.
Use CSS and JavaScript Minification: Minify your CSS and JavaScript files to remove unnecessary whitespace and comments, reducing their file size and improving loading times.
Leverage Browser Caching: Set proper cache headers for static assets to enable browser caching, allowing returning visitors to load the page faster.
Prioritize Above-the-Fold Content: Load critical above-the-fold content first to provide users with a fast initial rendering experience while other assets load in the background.
Lazy Loading: Implement lazy loading for images and other non-essential resources. This defers loading until the user scrolls to the content, saving bandwidth and improving performance.
Reduce Render-Blocking Resources: Minimize the use of render-blocking CSS and JavaScript that can delay the rendering of the page content.
Use Content Delivery Networks (CDNs): Distribute assets across geographically distributed CDNs to reduce latency and ensure faster delivery to users around the world.
Server-Side Rendering (SSR) or Static Site Generation (SSG): Consider implementing SSR or SSG techniques for faster initial rendering and improved SEO.
Performance Audits and Monitoring: Regularly perform performance audits using tools like Lighthouse or PageSpeed Insights to identify bottlenecks and monitor performance over time.
Progressive Web Apps (PWAs): Explore building PWAs to provide an app-like experience, including offline access and fast loading even in low network conditions.
Reduce Third-Party Dependencies: Minimize the number of third-party scripts and services, as they can introduce additional HTTP requests and potential performance issues. 13.** Optimize Fonts**: Use web-safe fonts or consider loading fonts asynchronously to prevent font rendering delays.

2. Extensibility

Extensibility refers to the ability of the codebase to be easily extended and modified without causing significant disruptions or requiring major rework. There are some principles regarding the extensibility as follows

Modular Architecture: Design the frontend using modular components that can be added, removed, or replaced without affecting other parts of the application. This allows for easy integration of new features or changes.
Use of Design Patterns: Implement design patterns such as the Module Pattern or Component-Based Architecture (like React components) that promote code reusability and clear separation of concerns. This makes it easier to introduce new functionality without impacting existing parts.
Well-Structured Code: Write clean, well-documented, and maintainable code that adheres to best practices and coding standards. This helps other developers (or your future self) to understand and extend the codebase effectively.
Plugin System: Consider implementing a plugin system that allows third-party developers to create and integrate extensions into your application. This can be especially useful if you're developing web applications that might need customizable features for different clients.
APIs and Interfaces: Define clear APIs and interfaces for different modules or components. This helps establish a contract between different parts of the application and ensures that changes can be made without breaking existing functionality.
Testing and Testability: Maintain a strong suite of automated tests that cover different aspects of the application. This ensures that new extensions or modifications don't introduce regressions and can be confidently integrated.
Version Control and Collaboration: Use version control systems (e.g., Git) effectively to manage changes and collaborate with other team members. Proper branching and merging strategies can help keep the codebase extensible while managing feature development.
Documentation: Document your codebase, including its architecture, design decisions, and guidelines for extending it. This helps new developers quickly understand how to work within the project's framework.

3. Scalability

Scalability refers to the ability of the application's user interface to handle increased load and demand without compromising performance. Scalability ensures that your application can accommodate growing user bases and increased traffic while maintaining responsiveness and user experience.

When designing for scalability, you might consider:

Performance Optimization: Implement techniques such as lazy loading, code splitting, and caching to ensure that the application loads quickly and efficiently even as it grows in complexity.
Responsive Design: Create layouts that work seamlessly across various screen sizes and devices to cater to a diverse user base.
Browser Compatibility: Test your application across various browsers to ensure consistent performance and functionality.
Scalable Architecture: Choose a modular and maintainable architecture (like component-based architecture in React) that allows for easy addition of new features and components.
Load Balancing: If your project is part of a larger application ecosystem, ensure that the load is distributed evenly among servers to prevent bottlenecks.
Caching and CDN: Utilize Content Delivery Networks (CDNs) to distribute static assets and cached content closer to users, reducing server load and improving performance.
Horizontal Scaling: Design your application so that you can scale out horizontally by adding more frontend servers as the user base grows.
Optimized Assets: Optimize images, fonts, and other assets to minimize loading times and bandwidth usage.
Real-time Updates: If your application requires real-time updates (e.g., social media feeds), consider implementing efficient techniques like WebSocket connections.
Monitoring and Analytics: Set up monitoring tools to track performance metrics, identify bottlenecks, and proactively address issues as the application scales.

4. Availability

Availability is about the degree to which your software is operational and available to service the users. Maybe it is an infrastructure concern to publish or deploy the frontend application on a stable infrastructure but still, we have some concerns we should care about, for example:

Fault Tolerance: Designing the frontend to gracefully handle errors, crashes, and other issues without causing a complete disruption to users' experience.
Caching: Utilizing caching mechanisms to store and deliver frequently requested content, reducing the load on the backend and improving response times.
Monitoring and Alerting: Implementing monitoring tools that track the health and performance of the frontend application and provide alerts to administrators in case of anomalies or outages.
Use Content Delivery Networks (CDNs): Distribute assets across geographically distributed CDNs to reduce latency and ensure faster delivery to users around the world.
Downtime Maintenance: Planning and communicating scheduled maintenance windows to minimize the impact on users while performing necessary updates or maintenance tasks.
User Feedback and Support: Providing channels for users to report availability issues and ensuring a responsive support system to address any concerns promptly.

5. Flexibility

Flexibility is to enable your application to perform more than one task or perform that single task in a number of different ways.

For Example, enable your application the ability for non-techincal people to modify the business rules used within the software.

For Example, Imagine you're developing a task management application using React. Users can create tasks, set deadlines, and assign priority levels. Flexibility in this context could involve allowing users to customize their task management experience in different ways:
In your application, you can offer users the flexibility to sort their tasks in multiple ways to suit their preferences. Here's how you could implement this:

Due Date Sorting: Users can choose to sort tasks based on their due dates. This would help users prioritize tasks that are approaching their deadlines.

Priority Sorting: Users can opt to sort tasks by priority, displaying the most critical tasks at the top of their list.

Creation Date Sorting: Users can also sort tasks based on when they were created. This can be useful for reviewing recently added tasks.

Custom Sorting: Provide an option for users to manually reorder their tasks by dragging and dropping them. This way, users can create their own customized task order.

6. Monitoring

Monitoring is important as it concerns how your user interacts and accesses your entire application. For example, if your users can't make use of your website's features because of a UI error, then your application has failed to fulfill its purpose regardless of how performant it is. We can achieve that by integrating the application with platform-specific monitoring capabilities.
We have several platforms we can integrate with, like Sentry, one of the most used tools that allows you to report rendering errors by wrapping your component tree within the Sentry error-reporting service.

7. Security

Security is the degree to which the software protects information and data so that people, other products, or systems have data access appropriate to their types and levels of authorization.

Here are some ways you can apply security measures:

Input Validation and Sanitization: Ensure that user inputs are properly validated and sanitized to prevent common security vulnerabilities like Cross-Site Scripting (XSS) attacks. Implement client-side validation and use frameworks or libraries that offer built-in protection against such attacks.
Data Encryption: When transmitting sensitive data between the client and the server, use encryption protocols like HTTPS to ensure that the data remains confidential and cannot be easily intercepted or tampered with.
Secure Coding Practices: Follow secure coding practices, such as avoiding hardcoded secrets in your code, escaping user-generated content, and using libraries with a good security track record.
Regular Updates and Patching: Keep your frontend libraries and frameworks up to date with the latest security patches. Vulnerabilities can be discovered over time, so staying current is crucial.
Secure Dependency Management: Be cautious when including third-party dependencies in your project. Only use well-maintained and trusted libraries, and regularly audit them for vulnerabilities.
Error Handling: Avoid exposing sensitive information in error messages that could potentially aid attackers. Provide generic error messages to users and log detailed error information securely on the server.
Secure Design Reviews: Conduct regular security design reviews to identify potential vulnerabilities in your frontend architecture and codebase.

8. Maintainability

Maintainability is a crucial aspect and it is hard to quantify, but we can guarantee somehow the maintainability by following some strategies:

Code Structure and Organization:
- Follow a modular and component-based architecture, like React components. Divide your code into smaller, reusable components with clear responsibilities.
- Use meaningful names for files, folders, and components. This makes it easier for both you and other developers to understand the codebase.
Consistent Coding Standards:
- Establish and enforce coding standards and guidelines for the project. This ensures a consistent coding style throughout the codebase, making it easier for developers to read and maintain.
Documentation:
- Write thorough and up-to-date documentation for your codebase. This includes high-level architecture diagrams, component documentation, and inline comments.
- Document the purpose of each component, its props, and any expected behaviors. This helps new developers understand and modify the codebase more effectively.
Version Control:
- Utilize version control systems like Git to track changes and collaborate with other developers. Follow a branching strategy (like Gitflow) to manage feature development, bug fixes, and releases.
Testing and Test Automation:
- Implement a comprehensive testing strategy using tools like Jest and React Testing Library. Write unit tests, integration tests, and end-to-end tests to catch bugs early and prevent regressions.
- Set up automated testing pipelines to run tests on each code commit and before deploying to production.
Code Reviews:
- Conduct regular code reviews to ensure code quality and maintainability. Code reviews provide opportunities to catch issues, share knowledge, and maintain consistent coding standards.
Refactoring:
- Regularly revisit your codebase to identify areas that need refactoring. Refactoring helps eliminate technical debt, improve performance, and enhance maintainability.
Dependency Management:
- Keep track of third-party libraries and dependencies used in the project. Regularly update them to the latest versions to benefit from bug fixes, security patches, and performance improvements.
Performance Optimization:
- Optimize the performance of your frontend application. This includes minimizing the use of costly operations, optimizing network requests, and handling memory efficiently.
Error Handling and Logging:
- Implement robust error handling mechanisms to gracefully handle unexpected situations. Use logging to capture errors and debugging information, which aids in diagnosing issues.
Design Patterns:
- Familiarize yourself with design patterns relevant to frontend development, like MVC, MVVM, or Flux. These patterns can provide a structured approach to building maintainable applications.
Continuous Learning:
- Stay updated with the latest frontend technologies, best practices, and tools. Continuous learning helps you adapt to changes and incorporate new techniques into your projects.

9. i18n & l10n

How can you make your application work with different languages, including those that are written from right to left? This is called internationalization (i18n). And what about localization (l10n)? Localization means showing things like numbers, money, and dates in ways that make sense to the user's culture. When you put these together, it's called "Globalization".

10. Accessibility

Accessibility usually refers to things like the W3C accessibility standards, which refer to designing and building digital products, such as websites and applications, in a way that ensures they can be used and navigated by people with disabilities.
It's about creating a user experience that is inclusive and accommodating to individuals who may have visual, auditory, motor, or cognitive impairments. This involves using proper HTML semantics, providing alternative text for images, ensuring keyboard navigation, and incorporating ARIA roles and attributes to make your web applications usable by a diverse range of users, including those who rely on assistive technologies. By making your frontend projects accessible, you contribute to a more inclusive online environment and enhance the user experience for everyone.

Frontend Architecture: The Architecture (Part. 2)

Hamed Farag — Thu, 17 Aug 2023 07:11:54 +0000

Architecture Vs Design

What is the difference between Architecture and Design?

Most people think that the two words are the same or lead to the same thing.
But there is a trick here. When I share a problem with different developers, they think differently and each one of them has a valid solution for my problem, and this is normal. Each one has his own experience and based on that; he offers a solution.

Grady Booch says,

All architecture is design but not all design is architecture.

And this makes sense because creating a solution and "architecting" is essentially a design exercise. It is about filtering the options that you have and making decisions.

And also, regarding this point, Grady Booch says,

Architecture represents the significant design decisions that shape a system, where significance is measured by the cost of change.

What is that mean?
The Significant decisions are "architecture" and anything else is "design". I know it is still not clear enough the distinction between "architecture" and the "design", but we have some examples that may help us to understand the difference.

Frameworks **and **languages (here it will be JS or TS), are "architectural" decision.
Choosing the suitable File Structure is "architectural" not just "design" decision.
Http Manager - the centralize block that helps us to consume APIs - is "design" decision not "architectural".
Styling is "architectural" decision, CSS, SASS, LESS, CSS-in-JS or CSS utility library.
Micro-frontend or Monolith Solution is "architectural" decision.
Documentation tool is "architectural" decision.
Passing Data through layers is "architectural" decision.

I think you have now an image of how to differentiate the "architectural" or "design" decision when you have to take a decision to solve a problem.
But in the end, we can say that Architectural decisions are those that you cannot reverse without some degree of effort, in other words, they are the things that you would find hard to refactor in an afternoon.

Why Software Architecture important in general?

Let's ask some questions and based on you answer you will know,

Does your application have a well-defined structure (File Structure, Design Pattern, etc.)?
Is everybody in your team implementing features in a consistent way?
Is there a consistent level of quality across the codebase?
Do your team members share the same vision for how the application will be built?
Does everybody on your team have the necessary amount of technical guidance?
Is there an appropriate amount of technical guidance and leadership?

If your answer is no for any point, and already delivered some applications, I think there will be a re-writing process that will be happening or already happening. Or it might be you already delivered an application for a client, and you will not support it again or not doing any changes in the future, so it is fine to not care about some points already mentioned above.

The technical guidance or leadership is very important at any level (code level and above it) because most software projects and products start with the best of intentions, and it is easy for them to veer off the track.

Personally, I worked on some projects without anyone caring about the architecture, just someone caring about it in the early phase of the project, adding the structure and the technology, then disappearing. Here it is, some of the problems I list in points.

File Structure not predictable.
Many methods to consume APIs (Axios, fetch).
Heavy usage of redux for every single component.
A cocktail of CSS and LESS styles.
Two different libraries for handling dates and times.
"Any" as a type is used everywhere.
Sensitive keys pushed to the repository (.env file).
Different components with the same logic and functionalities.
Zero Documentation.
Very huge files (some files reached +1000 lines of code).
Unbelievable Git flow, deploying code into an environment then creating PR with these changes!

So, without technical leadership, many codebases also end up looking like the stereotypical "big ball of mud" or "spaghetti code". And no one want to work with these codebases.

Most of these problems are relatively easy to solve with the application of some good technical leadership, resulting in a team that therefore understands and thinks about the software architecture and even ask some questions that will affect the project in general. In summary, this can provide:

A clear vision and roadmap for the team to follow.
Technical leadership and better coordination.
Encouragement to talk to people in order to ask questions relating to significant decisions, non-functional requirements, constraints, and other cross cutting concerns.
Standards and guidelines, leading to a well-structured codebase.
A set of firm foundation for the project being built.
A structure with which to communicate the solution at different levels of abstraction to different audiences.

Let's consider the architecture of an e-commerce website as an example for the last previous point. The different levels of abstraction and the audiences they cater to might be:

High-Level Abstraction: For non-technical stakeholders (e.g., business executives, investors):

The frontend of the e-commerce website is the user interface that customers interact with when browsing and purchasing products.

It provides a visually appealing and user-friendly design, creating a positive user experience.

The architecture emphasizes how the frontend contributes to increasing customer engagement and conversion rates.

Medium-Level Abstraction: For project managers and design team leads:

The frontend architecture follows a component-based design approach, where different UI elements are encapsulated into reusable components.

It uses popular frontend frameworks like React, Angular, or Vue.js, allowing efficient development and maintenance.

The architecture includes details about responsive design principles, ensuring optimal performance on various devices.

Low-Level Abstraction: For frontend developers and technical team members:

The frontend employs a state management library (e.g., Redux) to manage the application's state and data flow.

It uses RESTful APIs to communicate with the backend and fetch product data, user information, and other relevant data.

The architecture discusses the implementation of client-side routing to enable smooth navigation between different pages.

Developer Toolkit: For developers with a focus on implementation details:

The frontend codebase is structured following best practices, such as organizing files by feature or module.

It employs build tools like Webpack or Parcel to bundle and optimize the code for production deployment.

The architecture highlights the use of testing frameworks (e.g., Jest or Cypress) to ensure code quality and robustness.

So, what do you think, does every software project need software Architect?

The short answer is "yes", Why? because every software team should look at a number of factors in order to assess how much software architecture thinking, a degree of which manifests itself as up-front design, is necessary.

I have experience working on various frontend projects. However, we didn't have proper technical design or architectural meetings to plan the projects. Instead, we simply used a familiar framework that the team already knew, so we could save time on learning new things and quickly set up the file structure. Unfortunately, this approach led to some challenges. We faced difficulties in communicating with each other about new components introduced by team members. Additionally, we lacked clear guidelines for documentation and a structured process for code reviewing. These important aspects were overlooked, causing some issues along the way.
Also, I believe you noticed that, in backend development, where planning and scalability are key, software architects are highly valued. They are invited onto a project long before development begins and they have discussions with clients about architectural needs (functional, non-functional requirements, etc.)
Where is the frontend time? We were being asked to do all our work piece by piece, as an afterthought.

There are two approaches to handling up-front design meetings.

Too many up-front design meetings with the team trying to answer all of the questions and solve the problems before writing a single line of code.
The Opposite, is too few up-front design meetings.
- From my point of view, we can go with this approach, but for every big problem, we have to set up a meeting with the team members to solve it in a proper way and all team members agree on one solution, also a proper communication way should be setup from day one, so by the time, we can build a solid solution, may it, not the best solution, but at least there is consistency, clear file structure, and not a spaghetti code.

Dave Thomas once said:

Big design up-front is dump, but doing no design-up-front is even dumber.

Frontend Architecture: The Architecture (Part. 1)

Hamed Farag — Thu, 17 Aug 2023 07:10:05 +0000

1. What is "Frontend Architecture"?

What is the first definition that will be popped into your mind when you hear "Frontend Architecture"?
I know that the definition may be a little bit vague, but let's try to think about some definitions we can conclude from our experiences and the books.

Skeleton and File Structure
The Big Picture
Communications.
Building Blocks
A plan
A blueprint
Strategy and Vision
Frameworks, Tools and Technical Direction.
Blocks that are expensive to change later
Technical Leadership
Foundations
Awareness of Constraints and Restrictions
Business
Standard and Guidelines
Processes (e.g. Code Review, Git Flow, CICD)
Path to achieve the Goal.
Elegant (e.g. clean code, components design)

So, what do you think? Is there another definition you think about but not listed here?

It is hard to find once and for good definition for the "Frontend Architecture" but in general we can say there are two common themes for the "Frontend Architecture". Frontend Architecture as a noun and Frontend Architecture as a verb.

Frontend Architecture as a noun

We can summarize as being about structure and the skeleton. It's about the decomposition of a product into a collection of smaller building blockers and the interactions/relationships between these building blocks.
e.g. Building the main blocks like cross-cutting blocks that will communicate with other blocks like pages, containers and components. Cross-cutting blocks here like logging and exception handling blocks, http block, main managers or helpers like storage manager, etc. The file structure or the skeleton you will build by following some well-known patterns, like feature-first, component-first, type-first, MVC pattern, atomic pattern, etc.

Frontend Architecture as a verb

As a verb, the process of creating the architecture, is about translating the architectural drivers (functional requirements, non-functional requirements, constraints and principles) into a technical solution, technical roadmap, communicating the vision to a number of stakeholders both inside and outside the software development team and introducing the technical leadership.

Generally, the Frontend Architecture is a collection of tools and processes that aims to improve the quality of frontend code while creating a more efficient and sustainable workflow.

Frontend (Application) Architecture

In General, the Application Architecture is what we as software developers are probably the most familiar with.
We have today different kinds of applications, like, Mobile apps, Backend apps, Frontend apps, and some other types of Apps. we can define an application as a single solid unit developed in a single technology or language.

Yes, we may have an "application" developed with different languages and technologies, for example, a micro-frontend application or a micro-service application. But in the end, we can say that each is a single unit.
Application Architecture is about looking inside the app to understand how it is designed and built. This includes how this application has been broken down into small building blocks, and understanding the patterns, frameworks, and libraries in use.

In the end, the application architecture cares about what is happening deep inside this single-unit (a.k.a. application) and how it is built.

Frontend Architecture: Introduction

Hamed Farag — Thu, 17 Aug 2023 07:08:41 +0000

An Introduction

Over the last few years, the frontend evolved very fast, and many topics, frameworks, libraries, and techniques were introduced.

I remember when the frontend developer/engineer used to be called a "UI Developer", and receive a design screen from the designer as a PSD (Photoshop Document File), and with his skills, he should extract the assets by slicing the needed icons, background or whatever he wants and then use these extracted images into the HTML and adjust them using the CSS, and of course, writes some JavaScript code (jQuery Code, to be more accurate) to add some interactivity to some elements like an open popup or confirmation dialogs and so on. And also write some CSS to add some padding, margin, and a lot of floats to match the design.

I can remember if someone writes some styles using any CSS Preprocessor like LESS or SASS, he will be categorized as a Geek Developer.

But Now, do you think it is easy to create a simple frontend project without using any framework or library? The answer is *YES *, of course, you can create a new one using the basics (HTML, CSS, and JavaScript), but do you dare to do that?

Can you count, do you? okay, we have tons of libraries and frameworks, and each one of them resolves a problem in the real world or a problem in another library or framework. Also, a lot of techniques you should choose one of them, a simple example.

Choose one of the following to write your styles in your next project, (CSS, LESS, SASS, CSS-IN-JSS, or utility-first CSS).
mmmmh
Okay, whatever your choice, your choice is based on what?
🤔🤔

So, in the series, we will talk about a lightweight guideline for Frontend Architecture and the aspects you should think about and consider while building your next project.

Upgrade a React Project!

Hamed Farag — Sat, 06 Apr 2019 17:49:32 +0000

A few days ago, I was engaged in a challenge to upgrade a project written in React and Redux libraries maintained for more than 2 years and we still maintain it and add new features to extend its functionalities. From React 15.4 to 16.8 there are a lot of updates and upgrades in React itself and its ecosystem.

I will list below all what I did to make the project working again after a lot of upgrades and workarounds.

1- Upgrade React and React DOM

The first step ever, just install React 16.8 and React DOM 16.8, then tried to run the application. Boom, a shiny white screen opened in my browser and with a lot of error but the main error is

React.PropTypes.string.isRequired cannot read property isRequired of undefined

2- Install PropTypes package

So the second step was installing the PropTypes package because based on React Documentation, PropTypes extracted into its own package since React 15.5.0. Woow 😄

So I revisited all the components that use PropTypes and Adjust it based on PropTypes package.

2.1 The "Refs"

What is the "Refs"? Refs provide a way to access DOM nodes or React elements created in the render method.

When to use "Refs"?

Managing focus, text selection, or media playback.
Triggering imperative animations.
Integrating with third-party DOM libraries.

Where is the problem? In my project, we were used "Refs" with an old API where ref attribute is a string, like "textInput", and the DOM node is accessed as this.refs.textInput. [React Documentation]

My Project was used this Legacy API, the String Refs, so in React Documentation they recommend to use callback pattern or createRef API instead.

So, we revisited the whole project and replace the Legacy API with createRef API

2.2 Redux with refs

I remember well those 3 days to know why parent component cannot access the ref of its child, Why? Because parent was contain button if user click on it, a textbox in the child will be focused 😄 and the child for some reason was connected with redux 😓.

Note:

If you remember well how we connect react component with redux, the connect method will be written in your mind that introduced by react-redux library.

The new wrapper component that out from the connect method, will not return the instance of the wrapped component by default and you need to tell him that you need to return an instance so you can access any method you created it inside this wrapper component.

So to resolve this problem, connect accepts four different parameters, all optional. By convention, they are called:

mapStateToProps?: Function

mapDispatchToProps?: Function | Object

mergeProps?: Function

options?: Object

and the fourth parameter is an object and you can send {withRef: true} [forwaredRef] to solve the problem.

Because of the upgrading of redux, withRef was deprecated and replaced with forwardRef, and this mean the accessing of this wrapper component changes too.

Showcase

// Old code and remember, i am react v.15.4
import React from "react";
import ReactDOM from 'react-dom';
import { connect } from "react-redux";

export default class Parent extends React.Component {
    _onClick = () => {
        this.refs["childComponent"].getWrappedInstance()._handleFocus();
    }

    render(){
        return(
            <div>
                <input type="button" value="focus" onClick={() => this._onClick()} />
                <Child ref="childComponent" />
            </div>
        )
    }
}

class ChildComponent extends React.Component {

    _handleFocus = () => {
        var elementToFocus = this.refs["inputToFocus"];
        var commentDOM = ReactDOM.findDOMNode(elementToFocus);
        var elementPosition = commentDOM.getBoundingClientRect()
        elementToFocus.focus();
    }

    render(){
        return <input type="text" ref="inputToFocus" />
    }
}

const Child = connect(null, null, null, { withRef: true })(ChildComponent);

// Old code and remember, i am react v.15.4
import React from "react";
import ReactDOM from 'react-dom';
import { connect } from "react-redux";

export default class Parent extends React.Component {
    _onClick = () => {
        // The new ref access
        this.child._handleFocus();
    }

    render(){
        return(
            <React.Fragment>
                <input type="button" value="focus" onClick={() => this._onClick()} />
                {/*the new usage of ref */}
                <Child ref={ele => this.child = ele} />
            </React.Fragment>
        )
    }
}

class ChildComponent extends React.Component {
    _handleFocus = () => {
        this.inputToFocus.focus();
    }

    render(){
        {/*the new usage of ref */}
        return <input type="text" ref={ele => this.inputToFocus = ele} />
    }
}

const Child = connect(null, null, null, { forwardRef: true })(ChildComponent);

A lot of changes, especially in accessing the wrapper component.

3. Upgrade most of packages

Because of most of the following packages using the PropTypes from React package, I updated them to latest as they Use the PropTypes package directly.

"draft-js": "^0.10.5",
"draft-js-mention-plugin": "^3.1.3",
"draft-js-plugins-editor": "^2.1.1",
"slick-carousel": "^1.8.1",
"react-appinsights": "^2.0.2",
"react-click-outside": "^3.0.1",
"react-dropzone": "^10.0.6",
"react-notification-system": "^0.2.17",
"react-notification-system-redux": "^2.0.0",
"react-router-dom": "^5.0.0",
"react-select": "^2.4.2",
"react-textarea-autosize": "^7.1.0",
"react-tooltip": "^3.10.0",

But the most painful packages were redux-form 5.3.3 and redux-form-validation 0.0.8 😞

3.1 Redux-form 5.3.3

I tried to upgrade redux-form 5.3.3 and redux-form-validation 0.0.8 normally like the other packages but this project has almost 6 forms and if I upgrade them I will totally rewrite these forms because redux-form has been completely rewritten for v6, because of a fundamental design change.

So what is the workaround? Simply I downloaded redux-form 5.3.3 and upgrade it manually by install PropTypes and change the React.PropTypes to be PropTypes directly and thanks for redux-form team for creating unit tests to make sure that everything is okay. Of course, I included redux-form code into my project until I rewrite the 6 forms and of course I installed extra packages that redux-form depends on them.

"is-promise": "2.1.0"
"react-lazy-cache": "3.0.1"
"valid-url": "1.0.9"

4. React-router

The biggest nightmare, React Router v4 is a complete rewrite, not just enhancements added to the previous version, and react-router changed to be react-router-dom, huge changes happened from v.3 to v.5

I followed to main articles to upgrade from react-router v.3 to react-router v.5

These two articles are great to follow them if you want to upgrade your react-router.

Of course, there are some crashes after this upgrade, I upgraded some packages too like react-dropzone and so on due to some configurations changes and its usage.

This upgrade costed me more than 30hr in 3 days continuously. When I was working on this upgrade I was thinking a lot to take a step back because of a lot of crashes.

Original post: https://hamed-farag.github.io/blog/react-upgrade-v1/