Forem: Joseph Mukorivo

I Got Tired of Jira. So I Built an Agentic Project Management Tool — and Open-Sourced It

Joseph Mukorivo — Sat, 10 Jan 2026 09:17:19 +0000

I’m open sourcing FortyOne, an agentic project management tool built around a simple idea:

Most project tools are great at tracking work.

Very few help you move work forward.

FortyOne ships with Maya, an AI teammate that’s designed to work alongside you: drafting stories, helping shape sprint scope, connecting OKRs to execution, and surfacing what’s stuck before it becomes a fire drill.

If you just want to try it first, the hosted version is here: https://www.fortyone.app

Frontend repo: https://github.com/complexus-tech/fortyone.app

Backend repo: https://github.com/complexus-tech/api.fortyone.app

What I mean by “agentic project management”

There’s a lot of “AI for project management” content out there, and most of it is basically:

You ask a question → you get a summary.

That’s useful, but it’s not agentic.

When I say agentic, I mean the AI is built to help with action inside your workflow, not just commentary about the workflow.

A few examples of the kind of work Maya is meant to support:

Turn rough thoughts into structured stories

You give a messy paragraph, you get a story with a clear title, description, and the right structure to start execution.
Help plan sprints using context

Instead of guessing sprint scope from scratch, Maya can help propose a sprint plan based on backlog context and what your team is trying to ship.
Connect OKRs to actual day-to-day work

It’s easy to write goals. It’s hard to make sure the backlog reflects them. FortyOne is designed to keep that relationship visible.
Surface risks early

Work gets stuck quietly. The goal is to make “quietly stuck” obvious, so you can respond before deadlines do it for you.

That’s the “AI teammate” framing I’m pushing for: less chatbot, more “help me execute.”

What is FortyOne today

FortyOne is a modern project management platform that focuses on:

Stories (task tracking with real workflows)
Sprints (planning and velocity)
Objectives and OKRs (goal tracking tied to execution)
Real-time collaboration (your team stays in sync)

It’s designed to feel clean, fast, and easy to adopt.

What’s open source

FortyOne is split into two main codebases:

Frontend (monorepo)

Repo: https://github.com/complexus-tech/fortyone.app
Backend API (Go)

Repo: https://github.com/complexus-tech/api.fortyone.app

I’m sharing both because I want this to be genuinely useful for builders who want to learn from it, extend it, self-host it, or contribute features back.

Frontend overview (fortyone.app)

The frontend is a Turborepo monorepo built for a real product, not a demo. It includes:

A marketing and auth app
The main project management app
A docs site
A React Native mobile app (in progress)

The stack leans modern and practical:

Next.js 15 + React 19
TypeScript
Tailwind CSS
Radix UI + Framer Motion
PostHog for analytics
NextAuth for authentication

Monorepo structure (high level)

You’ll find a structure like:

apps/
1. landing/ (marketing + auth)
2. docs/ (documentation)
3. projects/ (core app)
4. mobile/ (React Native)
packages/
1. shared UI components
2. shared utilities
3. icons
4. shared configs

Backend overview (api.fortyone.app)

The backend is a Go application that powers the core product workflows.

It’s designed with a clear architecture so it’s easier to maintain, test, and extend.

Backend architecture (the important part)

The API follows a hexagonal/layered approach with a few clear layers:

Transport layer

HTTP, routing, input validation.
Domain layer

Business logic and interfaces.
Data layer

Storage implementations (PostgreSQL via SQLx).
Platform / pkg layer

Shared utilities and integrations.

There’s also a worker process for background jobs.

A few backend highlights

Migrations with golang-migrate
Database seeding for quick dev setup
A worker process (useful for background work)
Brevo integration for onboarding and transactional emails

Local development

I wanted the project to be something you can actually run locally without a week of archaeology.

Frontend: run locally

Clone the repo
git clone https://github.com/complexus-tech/fortyone.app
Install dependencies
pnpm install
Copy environment files
cp apps/landing/.env.example apps/landing/.env
cp apps/projects/.env.example apps/projects/.env
cp apps/mobile/.env.example apps/mobile/.env
Start dev
pnpm dev

Backend: run locally

Clone the repo
git clone https://github.com/complexus-tech/api.fortyone.app
Copy env file
cp .env.example .env
Run the API (hot reload)
make dev
Run the worker (in another terminal)
make worker

Migrations

Install migrate CLI if you want to work with migrations:

go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@v4.18.3

Then you can run:

make migrate-up
make migrate-down n=1

Seeding

If you want a working workspace quickly, the backend includes a seeder:

Default seed
make seed
Custom seed
make seed name="My Project" slug="my-project" email="me@example.com" fullname="Your Name"

Why I open sourced it

A few reasons, honestly:

I want builders to learn from a real product codebase

Not a “todo app,” but something with real trade-offs, real constraints, and real structure.
I want contributions

Not just PRs, but feedback on architecture, UX decisions, and what people want from agentic workflows.
I want to build in public

It’s easier to grow something when people can see it, use it, and improve it with you.
I think agentic UX is the next big frontier

We’ve had a decade of dashboards. The next step is software that can actually help you execute.

About the license

Both repos include a license file in the root.

The intent is:

Free for personal and non-commercial use
Commercial licensing required for larger businesses (as defined in the license)

If you’re building something commercial on top of it, read the license first and reach out if needed.

What I’d love help with

If you want to contribute, here are the kinds of contributions that are genuinely helpful:

Bugs and rough edges (especially around local setup)
UI/UX polish and accessibility improvements
Better docs and examples for Maya-style workflows
Integrations (GitHub, Slack, webhooks)
Performance improvements and profiling notes
Mobile app progress (React Native)

Even if you don’t want to write code, opening issues with clear reproduction steps and screenshots helps a lot.

Try it, star it, break it

If you’re curious about agentic workflows in a real project tool:

Try the hosted version: https://www.fortyone.app
Star the repos if you want to follow progress
Open an issue if something feels off
If you have ideas for what an “AI teammate” should do inside a PM tool, I want to hear them

This is the direction I’m betting on: project management that helps you ship, not just report.

See you in the issues.

[Boost]

Joseph Mukorivo — Thu, 08 Jan 2026 10:52:53 +0000

Open Sourcing FortyOne: Agentic Project Management With an AI Teammate

Joseph Mukorivo ・ Jan 8

#nextjs #go #typescript #startup

Can One Person Really Build a Complex System from Scratch?

Joseph Mukorivo — Fri, 01 Aug 2025 11:28:03 +0000

Introduction

When I started building complexus, I wasn’t trying to ship just a side project. I wanted to create a real system, one that could replace how modern teams plan, track, and align their work, and replace tools like Monday, Notion, and Jira, but fully centered around OKRs.

I have always built software with teams. I wanted to find out whether one person could tackle something this complex, so I built Complexus by myself. Complexus is a production ready ai project management platform with OKR tracking, real time collaboration, AI powered automation, background processing, engagement email workflows, multi tenant authentication, analytics, GitHub integration, and more. It consists of a frontend monorepo containing multiple Next.js applications and a separate backend service written in Go.

This post breaks down how I built it all. I’ll go deep into architecture, tooling decisions, background processing, AI tools, and the small details that made the system feel fast and cohesive. If you’re thinking about building a complex platform by yourself or leading the architecture of one, I hope this gives you a clear picture of what it actually takes.

The Frontend

Monorepo Setup with Turborepo

I chose Turborepo to house every part of the Complexus frontend in a single repository. This makes it trivial to share code and configuration across the various web applications. The top level structure looks like this:

/complexus.tech
  apps/
    landing/        # Next.js marketing site
    docs/           # MDX-driven documentation
    projects/       # Core project management app
  packages/
    ui/             # Shared components built with Tailwind and Radix
    tailwind-config/# Design tokens and Tailwind configuration
    lib/            # Shared helpers (cn, date formatters, Zod schemas)
    eslint-config-custom/ # Consistent linting rules
  turbo.json       # Pipeline definitions and cache settings
  tsconfig.json    # Base TypeScript configuration
  package.json     # Workspace dependencies and scripts

Each package declares its own TypeScript project reference so that changes to packages/ui or packages/lib immediately type check across all apps. Turborepo pipelines in turbo.json ensure only affected projects rebuild. Remote caching in CI restores build artifacts from previous runs, cutting pipeline times by over fifty percent. Locally, I run turbo run dev and get all three apps running in parallel with hot reload.

Shell and Layouts with Next.js

The core application under apps/projects is a Next.js App Router project. I rely on nested layouts to compose global UI elements and context providers. The root layout is minimal, setting up the HTML shell, fonts, and essential providers like SessionProvider for auth and a custom Providers component that wraps the app in QueryClientProvider, PostHogProvider, and ThemeProvider.

// apps/projects/src/app/layout.tsx
import type { Metadata } from "next";
import { Instrument_Sans as InstrumentSans } from "next/font/google";
import { type ReactNode } from "react";
import "../styles/global.css";
import { SessionProvider } from "next-auth/react";
import { auth } from "@/auth";
import { Providers } from "./providers";
import { Toaster } from "./toaster";
// ...

export default async function RootLayout({
  children,
}: {
  children: ReactNode;
}) {
  const session = await auth();

  return (
    <html className={font.className} lang="en" suppressHydrationWarning>
      <body>
        <SessionProvider session={session}>
          <Providers>
            {children}
            <Toaster />
          </Providers>
        </SessionProvider>
        {/* ... */}
      </body>
    </html>
  );
}

A second layout at src/app/(workspace)/layout.tsx is a server component that fetches critical workspace data. A third, nested layout at src/app/(workspace)/(app)/layout.tsx wraps everything in the main ApplicationLayout, which contains the resizable sidebar and the main content area. This layered approach keeps data fetching and UI rendering cleanly separated.

Data Fetching and Optimistic Updates with React Query

React Query is the backbone of all data operations. I define query keys in a shared file and co-locate data fetching hooks with their respective features under src/modules. For mutations, I implement optimistic updates to give users instant feedback. When a user performs an action, like creating a new sprint, the UI updates instantly while the network request happens in the background.

// apps/projects/src/modules/sprints/hooks/create-sprint-mutation.ts
import { useMutation, useQueryClient } from "@tanstack/react-query";
import { sprintKeys } from "@/constants/keys";
import { useTracking } from "@/hooks";
import { createSprint } from "../actions/create-sprint";
import type { NewSprint } from "../types";

export const useCreateSprint = () => {
  const queryClient = useQueryClient();
  const { track } = useTracking();

  return useMutation({
    mutationFn: async (sprint: NewSprint) => createSprint(sprint),
    onSuccess: (newSprint) => {
      queryClient.invalidateQueries({
        queryKey: sprintKeys.all,
      });

      track("sprint_created", {
        sprintId: newSprint.id,
        sprintName: newSprint.name,
      });
    },
    onError: (error) => {
      // Handle error, e.g., show a toast notification
    },
  });
};

on some of these operations i am also tracking the user actions with a custom useTracking hook and i use this data to understand how users are interacting with my platform and use this data to provide customised experiences.

Real Time Synchronization with Server Sent Events

To keep multiple users in sync, a dedicated ServerSentEvents component, rendered in the workspace layout, establishes a connection to a secure, workspace specific endpoint on the Go backend.

// apps/projects/src/app/server-sent-events.tsx
"use client";

import { useQueryClient } from "@tanstack/react-query";
import { useSession } from "next-auth/react";
// ... other imports

export const ServerSentEvents = () => {
  const { data: session } = useSession();
  const { workspace } = useCurrentWorkspace();
  const queryClient = useQueryClient();

  // ... handleNotification and handleWorkspaceUpdate callbacks

  useEffect(() => {
    // The endpoint URL is constructed dynamically using the workspace ID and session token
    const eventSource = new EventSource(/* ... secure endpoint ... */);

    eventSource.onmessage = (event) => {
      const data = JSON.parse(`${event.data}`);
      if (data.type === "story.workspace_update") {
        handleWorkspaceUpdate(data);
      } else {
        handleNotification(data);
      }
    };
    // ... error handling
    return () => eventSource.close();
  }, [session?.token, workspace /* ... */]);

  return null;
};

When an event arrives from the server, the client intelligently updates the React Query cache. For a story update, it patches the changed fields in both the main story list and the detailed story view using queryClient.setQueryData, ensuring all visible components update instantly without refetching entire lists.

Authentication Across Subdomains with NextAuth.js

NextAuth.js handles authentication. I use magic links and social auth system with secure tokens instead of storing passwords. A key architectural decision was to enable a single login session to work across all workspace subdomains, like acme.complexus.app and corp.complexus.app. This is achieved by scoping the authentication cookie to a shared parent domain, .complexus.app. When a user signs in, NextAuth.js issues a session cookie with this domain setting. The browser then automatically sends the cookie with requests to any subdomain, creating a seamless authentication experience.

AI Assistant Maya with the Vercel AI SDK

Maya, the AI assistant, is powered by the AI SDK and mostly OpenAI models. In the projects app, a chat component posts messages to an endpoint like /api/maya. For this i also collect some telemetry data with posthog to understand how users interact with Maya.

// apps/projects/src/app/api/maya/route.ts
import { createOpenAI } from "@ai-sdk/openai";
import { streamText } from "ai";
import { withTracing } from "@posthog/ai";
import { navigation, theme /* ... many other tools */ } from "@/lib/ai/tools";
// ...

export async function POST(req: NextRequest) {
  const { messages /* ... other context */ } = await req.json();
  const session = await auth();
  const phClient = posthogServer();

  const openaiClient = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
  const model = withTracing(openaiClient("gpt-4o-mini"), phClient, {
    posthogDistinctId: session?.user?.email ?? undefined,
    // ...
  });

  const result = streamText({
    model,
    messages,
    tools: {
      navigation,
      theme,
      // ... all other tools
    },
    system: systemPrompt + userContext,
    async onFinish({ response }) {
      await saveChat({
        id,
        messages: appendResponseMessages({
          messages,
          responseMessages: response.messages,
        }),
      });
    },
  });
  return result.toDataStreamResponse();
}

The key to Maya's effectiveness is the comprehensive set of tools defined in apps/projects/src/lib/ai/tools. These tools allow the AI to interact with the application's state, performing actions like creating stories, navigating the user, changing the theme, searching for items, and much more. This makes Maya a powerful, context aware assistant rather than just a simple chatbot.

Frontend Analytics with PostHog

PostHog is integrated across the frontend to capture events, run A/B tests, and allow users to opt into beta features. A custom useTracking hook makes it easy to send events from any component.

// apps/projects/src/hooks/tracking.ts
import { usePostHog } from "posthog-js/react";

export const useTracking = () => {
  const posthog = usePostHog();

  const track = (eventName: string, properties?: Record<string, any>) => {
    posthog.capture(eventName, properties);
  };

  return { track };
};

This hook is used throughout the application to track key user interactions, such as creating a story or completing a walkthrough.

The Backend

Backend Architecture in Go

The backend is a standalone Go service built with a clean, layered architecture. It relies heavily on the standard library, with sqlx for database access and asynq for background jobs. Code is organized by domain under the internal directory in a separate repository.

/projects-api
  cmd/
    api/main.go      # API server entry point
    worker/main.go   # Asynq worker entry point
  internal/
    core/            # Core business logic and types
    handlers/        # HTTP endpoint handlers
    repo/            # Database queries and repository pattern
    sse/             # Server-Sent Events hub
    web/mid/         # Middleware (auth, logging, etc.)
  pkg/               # Shared packages (database, cache, etc.)

The service layer in internal/core contains the business logic. Updating a story, for example, involves fetching the current state, applying the updates, recording the changes for the audit log, and publishing an event to notify other systems and send the SSE events to other connected users for real-time updates.

// internal/core/stories/stories.go
func (s *Service) Update(ctx context.Context, storyID, workspaceID uuid.UUID, updates map[string]any) error {
    ctx, span := web.AddSpan(ctx, "business.core.stories.Update")
    defer span.End()

    actorID, _ := mid.GetUserID(ctx)
    story, err := s.repo.Get(ctx, storyID, workspaceID)
    if err != nil {
        // ... error handling
        return nil
    }

    if err := s.repo.Update(ctx, storyID, workspaceID, updates); err != nil {
        span.RecordError(err)
        return err
    }

    // Record activities for the update
    var activities []CoreActivity
    for field, value := range updates {
        // ... create activity objects ...
    }
    if _, err := s.repo.RecordActivities(ctx, activities); err != nil {
        span.RecordError(err) // Log but don't fail the operation
    }

    // Publish event for real time sync and notifications
    payload := events.StoryUpdatedPayload{ /* ... */ }
    event := events.Event{
        Type:    events.StoryUpdated,
        Payload: payload,
        ActorID: actorID,
    }
    if err := s.publisher.Publish(context.Background(), event); err != nil {
        s.log.Error(ctx, "failed to publish story updated event", "error", err)
    }

    return nil
}

The repository packages under internal/repo contains raw SQL queries, which allows for precise tuning and indexing. I use sqlx to map query results to Go structs. OpenTelemetry instruments handlers and service calls, sending traces to Jaeger for end to end observability. Here is an example of adding a trace event within a handler:

// internal/handlers/storiesgrp/stories.go
func (h *Handlers) List(ctx context.Context, w http.ResponseWriter, r *http.Request) error {
ctx, span := web.AddSpan(ctx, "business.core.stories.List")
    defer span.End()
    // ...
    if err := h.cache.Get(ctx, cacheKey, &cachedStories); err == nil {
        // Cache hit
        span.AddEvent("cache hit", trace.WithAttributes(
            attribute.String("cache_key", cacheKey),
        ))
        web.Respond(ctx, w, toAppStories(cachedStories), http.StatusOK)
        return nil
    }
    // ...
}

Background Jobs with Asynq

Asynq runs scheduled and ad hoc tasks. I define jobs in internal/taskhandlers and register them in the worker's main entry point.

// cmd/worker/main.go
func main() {
    // ... setup ...
    srv := asynq.NewServer(
        asynq.RedisClientOpt{Addr: redisAddr, Password: redisPassword},
        asynq.Config{ /* ... */ },
    )

    mux := asynq.NewServeMux()
    mux.Handle(tasks.TypeOnboardingEmail, taskhandlers.NewOnboardingEmailHandler(log, brevoService))
    mux.Handle(tasks.TypeCleanupDeletedStories, taskhandlers.NewCleanupDeletedStoriesHandler(log, db))
    // ... other handlers

    if err := srv.Run(mux); err != nil {
        log.Fatal("could not run server: ", err)
    }
}

A daily cleanup job deletes soft deleted stories older than 30 days. Archiving jobs flag inactive boards. Notification jobs send transactional emails for unread notifications. Retry policies and dead letter queues prevent silent failures.

Emails and Onboarding with Brevo

Brevo handles both transactional and marketing emails via a single integration defined in pkg/brevo/emails.go.

// pkg/brevo/emails.go
import (
    "context"
    brevo "github.com/getbrevo/brevo-go/lib"
)

func (s *Service) SendTransactionalEmail(ctx context.Context, subject, toName, toEmail, htmlContent string) error {
    _, _, err := s.client.TransactionalEmailsApi.SendTransacEmail(ctx, sib.SendSmtpEmail{
        Sender:      &brevo.SendSmtpEmailSender{Name: "Complexus", Email: "no-reply@complexus.app"},
        To:          []brevo.SendSmtpEmailTo{{Name: toName, Email: toEmail}},
        Subject:     subject,
        TemplateId: 4,
    })
    return err
}

On signup, an Asynq task subscribes the user to a Brevo list. A five step onboarding automation then sends emails introducing features over two weeks.

CI/CD and Infrastructure

The frontend apps deploy on Vercel, with each apps/* folder detected as its own project, generating preview URLs for pull requests. The backend service builds a Docker image in a GitHub Actions workflow and deploys to Azure Container Apps.

# .github/workflows/deploy-backend.yml
name: Build and Deploy API

on:
  push:
    branches: [main]
    paths: ["projects-api/**"]

jobs:
  build_and_deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: "Login to Azure"
        uses: azure/login@v1
        with:
          creds: ${{ secrets.AZURE_CREDENTIALS }}

      # ... docker build and push commands ...

      - name: "Deploy to Azure Container Apps"
        uses: azure/container-apps-deploy-action@v1
        with:
          appName: [your_app_here]
          resourceGroup: [your_resource_group]
          imageToDeploy: [container_name].azurecr.io/projects-api:${{ github.sha }}

GitHub Integration

Complexus includes a GitHub App that listens for issue events. When installed on a repo, it sends webhooks to a dedicated endpoint in the Go backend. The handler creates or updates stories based on issue actions, linking development work directly to project planning. Daily Asynq jobs prune old webhook event logs to keep the system clean.

Closing Thoughts

Solo building a platform of this scale demands modular architecture, shared tooling, clear boundaries, and disciplined iteration. Complexus works because each layer integrates seamlessly. The frontend feels instant thanks to optimistic updates and SSE. The backend stays reliable through clean architecture patterns and raw SQL. Background jobs automate maintenance. AI tools extend functionality without bloating the core code. Authentication and feature flags keep everything secure and testable. Deployment pipelines ensure smooth releases.

Of course, this post doesn't cover everything. I've left out details on the comprehensive testing strategy, which includes end to end tests with Playwright and a suite of unit and integration tests for both the frontend and backend. The goal was to provide a high level map of the system.

If you are considering a solo build, invest heavily in your foundational architecture, automate what you can, and keep everything in one coherent workspace. I invite you to try the platform for yourself at www.complexus.app. Share your experiences or ask questions in the comments below. I look forward to hearing about your own complex one person builds.

Building Complexus: How I am Building a Modern Enterprise Frontend Architecture with Next.js and Turborepo

Joseph Mukorivo — Wed, 23 Apr 2025 20:05:34 +0000

Introduction: Crafting a Modern Project Management System

Building a sophisticated, feature-rich application like a project management system demands more than just choosing a popular framework. It requires a deliberate architectural approach to handle complexity, ensure maintainability, and enable efficient scaling. This article chronicles the journey of architecting the frontend for Complexus (complexus.app), a project management system designed for modern workflows.

Drawing inspiration from the principles outlined in my previous article on structuring enterprise frontends, this article dives deeper into the specific choices made for Complexus. We'll explore how a combination of Turborepo, a custom UI library, Domain-Driven Design (DDD) principles adapted for the frontend, Next.js, NextAuth.js v5 for shared authentication, and a robust tooling suite come together to create a scalable and maintainable frontend architecture.

Whether you're building your own complex application or simply curious about modern frontend practices, this detailed exploration of the Complexus frontend architecture aims to provide practical insights and patterns.

The Foundation: Turborepo Monorepo for Structure and Speed

For a project like Complexus, involving multiple distinct applications (the core project management app, a marketing site, documentation) and shared libraries, a monorepo structure offers significant advantages over managing multiple separate repositories. It simplifies dependency management, streamlines code sharing, enables atomic commits across related parts, and enforces consistency.

I chose turborepo as the build system and monorepo manager due to its focus on performance. Its key strengths lie in:

Intelligent Caching: Turborepo caches the output of tasks (builds, tests, linting), ensuring work isn't repeated unnecessarily, both locally and potentially remotely (Remote Caching). This dramatically speeds up CI/CD pipelines and local development loops.
Efficient Task Orchestration: It understands the dependency graph between packages and tasks, running them in parallel whenever possible and in the correct order.
Turbopack Integration (for Development): Leveraging Turbopack with Next.js during development (next --turbopack) provides near-instantaneous updates, further enhancing the developer experience.

Complexus Monorepo Structure

The Complexus monorepo follows a standard Turborepo structure, separating applications from shared packages

complexus-monorepo/
├── apps/
│   ├── projects/         # The core Next.js project management system
│   ├── landing/          # The Next.js landing page
│   └── docs/             # Documentation site (using Nextra)
├── packages/
│   ├── ui/               # Custom UI component library
│   ├── icons/            # Shared SVG icons package
│   ├── lib/              # Shared utilities (e.g., cn function)
│   ├── tailwind-config/  # Shared Tailwind CSS configuration
│   ├── eslint-config/    # Shared ESLint configuration preset
│   └── tsconfig/         # Shared TypeScript base configurations
├── package.json          # Root dependencies and scripts
├── pnpm-workspace.yaml   # Defines workspace locations (using pnpm)
└── turbo.json            # Turborepo pipeline configuration

This clear separation isolates deployable units (apps/) from reusable code (packages/), promoting modularity and making the codebase easier to navigate and maintain.

Streamlining Development: Shared Packages (`packages/`)

The packages/ directory is the heart of code sharing and consistency within the Complexus monorepo.

ui: Contains the custom-built UI component library. In Atomic design these are the atoms that can be used for build other features:
icons: Manages and exports SVG icons used across the applications.
lib: Shared utility functions. Includes cn, a function combining clsx and tailwind-merge to handle Tailwind class conflicts.
tailwind-config: Base Tailwind CSS theme used across all apps/packages an the ui package.
eslint-config: Base ESLint configuration preset for consistent linting rules.
tsconfig: Base tsconfig.json files that other packages extend.

Using these shared packages ensures consistency, reduces boilerplate, and simplifies dependency and configuration updates.

Structuring Logic: Domain-Driven Modules in `apps/projects`

While the UI library provides the visual building blocks, structuring the application logic within the main projects app (apps/projects/) requires a different approach. Simply grouping files by type (e.g., top-level hooks/, services/) quickly becomes unmanageable in a complex application.

Complexus adopts principles from Domain-Driven Design (DDD), specifically organizing code by feature or domain within a modules/ directory. Each subdirectory within modules/ represents a distinct business capability or feature set of the project management system.

apps/projects/src/
├ app/                       # Next.js App Router (layouts, pages, route handlers)
├ components/              # Truly global components (rarely needed)
├ lib/                         # App-specific core utilities, API client, global context
├modules/                    # Domain/Feature-specific code
│   ├sprints/                # Example: Sprints feature/domain
│   │   ├ components/    # UI components specific to Sprints (using `ui`)
│   │   ├ hooks/           # React hooks for Sprint-related logic/state
│   │   ├ queries/         # Data fetching queries (e.g., using React Query)
│   │   ├ mutations/       # Data mutation logic
│   │   ├ lib/               # Utility functions specific to Sprints
│   │   └ types/           # TypeScript types specific to Sprints
│   ├ tasks/                 # Example: Tasks feature/domain
│   │   └..                   
│   ├ settings/             # Example: Project Settings feature/domain
│   │   └...
│   └──...                   # Other features/domains
├── styles/                   # Global styles
└──...

Advantages of Feature-Based Structure

Cohesion: Related code lives together.
Modularity: Features are self-contained.
Scalability: Easy to add new modules.
Team Collaboration: Teams can own modules.

Within each module, React hooks (hooks/) are heavily used to encapsulate logic, state management, and interactions with data fetching libraries (like React Query, managing queries/ and mutations/). Components specific to the module (components/) compose reusable elements from ui to build the feature's interface.

Seamless Access: Shared Authentication Across Subdomains

Complexus uses subdomains (e.g., workspace-a.complexus.app, workspace-b.complexus.app). A critical requirement is that users authenticating on any valid subdomain (*.complexus.app) should remain authenticated across all others without needing to log in again.

This is achieved using NextAuth.js v5 and careful cookie configuration. The core challenge is ensuring the session cookie set by NextAuth.js is accessible across all relevant subdomains.

The key lies in setting the domain attribute for the session cookie within the NextAuth configuration. Below is an example config:

cookies: {
    sessionToken: {
      name: "__Secure-next-auth.session-token",
      options: {
        httpOnly: true,
        sameSite: "lax",
        path: "/",
        // CRUCIAL: Set domain for cross-subdomain access
        domain: ".example.com",
        secure: true
      },
    },

This configuration, combined with hosting on a platform like Vercel which handles subdomain routing, allows Complexus to provide a seamless authentication experience across its different workspaces.

Documenting with Nextra

To ensure Complexus is well-understood by users, a dedicated documentation site is maintained within the apps/docs application.

Nextra integrates smoothly with Next.js and allows writing documentation using Markdown (MDX), making it easy to embed React components directly into the documentation pages. It provides excellent defaults for documentation sites, including sidebar navigation, search, and theming.

Conclusion: Building for Complexity and Scale

Architecting the frontend for Complexus (complexus.app)[www.complexus.app] involved a series of deliberate choices aimed at managing complexity, fostering consistency, and ensuring the application can scale effectively. The combination of:

A Turborepo monorepo for structure and build performance.
Shared packages for UI components, configuration, and utilities.
Domain-Driven Design principles guiding the feature-based module structure in the main application.
NextAuth.js v5 configured for seamless cross-subdomain authentication.
Nextra for comprehensive documentation.
A consistent tooling suite (TypeScript, ESLint, Tailwind).

This architecture prioritizes developer experience through fast builds (Turborepo, Turbopack) and clear organization, while ensuring the end product is maintainable and scalable. While this specific setup is tailored for Complexus, the underlying principles of modularity, clear boundaries, shared foundations, and efficient tooling are applicable to many large-scale frontend projects.

Deep Dive into Go Reflection: Crafting a Dynamic Open Source Config Package

Joseph Mukorivo — Fri, 26 Jan 2024 09:40:20 +0000

In the dynamic world of Go development, configuration management plays a crucial role in tailoring applications to their specific environments. While traditional approaches often rely on static configuration files, a more versatile and powerful alternative emerges: reflection. By harnessing this introspective capability, we can craft a configuration package that seamlessly molds to your application's needs, reading values from environment variables directly into your structs. Buckle up, as we embark on a detailed exploration of this reflection-based approach, dissecting its inner workings and uncovering its advantages.

What is reflection anyway🤔?

Reflection in Go is a feature that allows a program to examine its own structure, particularly the types and values of variables during runtime. The reflect package in Go provides a set of functions and types for performing reflection.

Before we dive deeper into reflection, we need to understand interfaces, they are the backbone of reflection and golang in general. Interfaces play a significant role in reflection as they provide a way to work with values of different types in a unified manner. In Go, an interface is a collection of method signatures, and a value satisfies an interface if it implements all the methods declared by that interface.

Let's explore how reflection and interfaces are intertwined in Go:

Type Assertion and Reflection:

Go allows you to use type assertions to convert an interface value to a concrete type. Reflection builds upon this concept by providing tools to dynamically inspect the type of an interface value during runtime.

var x interface{} = 42
value, ok := x.(int) // Type assertion

With reflection, you can achieve a similar result:

var x interface{} = 42
valueType := reflect.TypeOf(x)

Working with Interface Values

Reflection provides a set of functions to work with interface values dynamically: reflect.ValueOf: Returns a reflect.Value representing the interface value. reflect.TypeOf: Returns a reflect.Type representing the dynamic type of the interface value.

var x interface{} = 42
value := reflect.ValueOf(x)
valueType := reflect.TypeOf(x)

These functions are fundamental in understanding and working with the dynamic aspects of an interface.

You can do more with reflection, like inspecting methods, calling them, and creating instances via interfaces. I recommend checking the docs for more information. Now that we have a basic understanding of reflection and interfaces let's start the development of our config package.

Config Package structure.

config
├── .github
│   └── workflows
│       └── go.yml
├── .gitignore
├── LICENSE
├── README.md
├── config.go
├── config_test.go
└── go.mod

config.go: Houses the core functionality for parsing configuration values from environment variables into a provided struct.
config_test.go: Contains comprehensive tests to ensure the package's correctness and robustness.

Key Functions:

Parse(prefix string, cfg any) error:
- Accepts a prefix for environment variable names and a pointer to a struct intended to hold configuration values.
- Employs reflection to iterate through struct fields, extracting configuration values from environment variables.
- Supports various data types (strings, integers, booleans, floats, and time.Duration).
- Handles nested structs, enabling hierarchical configuration structures.
- Provides mechanisms for setting default values and enforcing required fields.

Usage Example:

package main

import (
    "fmt"

    "github.com/josemukorivo/config"
)

type ServerConfig struct {
    Host string `env:"SERVER_HOST"`
    Port int    `env:"SERVER_PORT" default:"8080"`
}

type DatabaseConfig struct {
    Username string `env:"DB_USER" required:"true"`
    Password string `env:"DB_PASSWORD"`
}

type AppConfig struct {
    Server  ServerConfig
    Database DatabaseConfig
}

func main() {
    var cfg AppConfig
    config.MustParse("app", &cfg)

    fmt.Println("Server configuration:")
    fmt.Println("- Host:", cfg.Server.Host)
    fmt.Println("- Port:", cfg.Server.Port)

    fmt.Println("Database configuration:")
    fmt.Println("- Username:", cfg.Database.Username)
    fmt.Println("- Password:", cfg.Database.Password)
}

Code walkthrough

Before we proceed with the walkthrough, let me provide you with the current code for the config.go file as of my last update. Please note that the code in the repository may have undergone significant changes since then.

package config

import (
    "errors"
    "fmt"
    "os"
    "reflect"
    "strconv"
    "strings"
    "time"
)

var ErrInvalidConfig = errors.New("config: invalid config must be a pointer to struct")
var ErrRequiredField = errors.New("config: required field missing value")

type FieldError struct {
    Name  string
    Type  string
    Value string
}

func (e *FieldError) Error() string {
    return fmt.Sprintf("config: field %s of type %s has invalid value %s", e.Name, e.Type, e.Value)
}

func Parse(prefix string, cfg any) error {
    if reflect.TypeOf(cfg).Kind() != reflect.Ptr {
        return ErrInvalidConfig
    }
    v := reflect.ValueOf(cfg).Elem()
    if v.Kind() != reflect.Struct {
        return ErrInvalidConfig
    }
    t := v.Type()

    for i := 0; i < v.NumField(); i++ {
        f := v.Field(i)
        if f.Kind() == reflect.Struct {
            newPrefix := fmt.Sprintf("%s_%s", prefix, t.Field(i).Name)
            err := Parse(newPrefix, f.Addr().Interface())
            if err != nil {
                return err
            }
            continue
        }
        if f.CanSet() {
            var fieldName string

            customVariable := t.Field(i).Tag.Get("env")
            if customVariable != "" {
                fieldName = customVariable
            } else {
                fieldName = t.Field(i).Name
            }
            key := strings.ToUpper(fmt.Sprintf("%s_%s", prefix, fieldName))
            value := os.Getenv(key)
            // If you can't find the value, try to find the value without the prefix.
            if value == "" && customVariable != "" {
                key := strings.ToUpper(fieldName)
                value = os.Getenv(key)
            }

            def := t.Field(i).Tag.Get("default")
            if value == "" && def != "" {
                value = def
            }

            req := t.Field(i).Tag.Get("required")

            if value == "" {
                if req == "true" {
                    return ErrRequiredField
                }
                continue
            }

            switch f.Kind() {
            case reflect.String:
                f.SetString(value)
            case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
                var (
                    val int64
                    err error
                )
                if f.Kind() == reflect.Int64 && f.Type().PkgPath() == "time" && f.Type().Name() == "Duration" {
                    var d time.Duration
                    d, err = time.ParseDuration(value)
                    val = int64(d)
                } else {
                    val, err = strconv.ParseInt(value, 0, f.Type().Bits())
                }
                if err != nil {
                    return &FieldError{Name: fieldName, Type: f.Kind().String(), Value: value}
                }
                f.SetInt(val)
            case reflect.Bool:
                boolValue, err := strconv.ParseBool(value)
                if err != nil {
                    return &FieldError{Name: fieldName, Type: f.Kind().String(), Value: value}
                }
                f.SetBool(boolValue)
            case reflect.Float32, reflect.Float64:
                floatValue, err := strconv.ParseFloat(value, f.Type().Bits())
                if err != nil {
                    return &FieldError{Name: fieldName, Type: f.Kind().String(), Value: value}
                }
                f.SetFloat(floatValue)
            default:
                return &FieldError{Name: fieldName, Type: f.Kind().String(), Value: value}
            }
        }
    }
    return nil
}

func MustParse(prefix string, cfg any) {
    if err := Parse(prefix, cfg); err != nil {
        panic(err)
    }
}

The custom error types

In our config package, we've added special error types – ErrInvalidConfig, ErrRequiredField, and FieldError – to better handle issues with configuration settings. The FieldError type gives us detailed information about a field's name, type, and the specific problem with its value. This helps us create clear error messages when we're reading and setting up configurations. If the configuration provided is not correct, like passing a string or a struct value instead of a pointer, we get an ErrInvalidConfig error. The ErrRequiredField error is returned when a required field does not have a value. In the future, we might add the ErrRequiredField error as an extra field of the FieldError struct.

var ErrInvalidConfig = errors.New("config: invalid config must be a pointer to struct")
var ErrRequiredField = errors.New("config: required field missing value")

type FieldError struct {
  Name  string
  Type  string
  Value string
}

The Parse Function

The heart of our configuration package is the Parse function. It takes a prefix and a configuration struct pointer as input, populating the struct fields based on corresponding environment variables. The first lines of the function ensure that the provided configuration is a valid pointer to a struct; otherwise, it returns ErrInvalidConfig.

func Parse(prefix string, cfg any) error {
  if reflect.TypeOf(cfg).Kind() != reflect.Ptr {
    return ErrInvalidConfig
  }

  v := reflect.ValueOf(cfg).Elem()

  // ...
}

We use reflect.TypeOf to check if the provided configuration is a pointer. If not, we return an error. reflect.ValueOf then gives us a Value representing the variable's underlying value, and .Elem() allows us to access the struct's fields.

Handling Nested Structs

One fascinating aspect of the Parse function is its ability to handle nested structs. When encountering a struct field, it creates a new prefix by combining the current prefix and the struct field's name. It then recursively calls itself with the new prefix and the struct field's address.

if f.Kind() == reflect.Struct {
  newPrefix := fmt.Sprintf("%s_%s", prefix, t.Field(i).Name)
  err := Parse(newPrefix, f.Addr().Interface())
  if err != nil {
    return err
  }
  continue
}

This recursive approach allows us to navigate through the entire structure of the configuration, handling nested structs at any level.

Extracting Field Metadata from Struct Tags

Struct tags play a crucial role in providing additional metadata for fields. In our configuration package, we use tags to specify environment variable names, default values, and whether a field is required.

customVariable := t.Field(i).Tag.Get("env")
// ...

def := t.Field(i).Tag.Get("default")
req := t.Field(i).Tag.Get("required")

We extract this metadata using Tag.Get and use it to customize the behavior of the Parse function. If an environment variable name is specified in the tag, it takes precedence over the field name.

Assigning Values Based on Type

Once we have the environment variable name and other metadata, we fetch the corresponding value from the environment using os.Getenv. The next step is to convert and assign this value to the struct field based on its type.

switch f.Kind() {
case reflect.String:
  f.SetString(value)
// ... (similar cases for int, bool, float, and custom types)
}

Here, we use a switch statement to handle different types, from strings to integers, booleans, floats, and even custom types like time.Duration. The conversion is done using functions like strconv.ParseBool, strconv.ParseInt, and time.ParseDuration.

MustParse: A Panicking Alternative

The MustParse function provides a more aggressive approach. If parsing fails, it panics, ensuring immediate attention to configuration issues during development. This function is particularly useful in scenarios where configuration errors should be addressed promptly.

func MustParse(prefix string, cfg any) {
  if err := Parse(prefix, cfg); err != nil {
    panic(err)
  }
}

Adding Tests for Robustness

Ensuring the reliability of our configuration package is crucial. The accompanying config_test.go file provides a suite of tests covering various scenarios:

Valid configuration parsing.
Handling invalid configurations, including non-struct types and non-pointer types.
Applying default values when environment variables are missing.
Checking for required fields and raising errors when necessary.
Parsing time.Duration values.

package config

import (
    "os"
    "testing"
)

type Config struct {
    Host string
    Port int    `config:"default=8080"`
    User string `env:"config_user" default:"joseph" required:"true"`
}

func TestParse(t *testing.T) {
    os.Clearenv()
    os.Setenv("APP_HOST", "localhost")
    os.Setenv("APP_PORT", "8080")

    var cfg Config

    err := Parse("app", &cfg)
    if err != nil {
        t.Fatal(err)
    }

    if cfg.Host != "localhost" {
        t.Fatalf("expected host to be localhost, got %s", cfg.Host)
    }

    if cfg.Port != 8080 {
        t.Fatalf("expected port to be 8080, got %d", cfg.Port)
    }
}

You can check more the tests from the repo.

Conclusion

In this extensive exploration of reflection in Go, we've built a dynamic configuration package that adapts to various struct types and parses environment variables with finesse.

By leveraging reflection, Go developers can create flexible and generic solutions, enhancing code reusability and adaptability. The config package presented in this blog serves as an example of how reflection can be harnessed to achieve dynamic behavior in a statically-typed language.

As you continue to navigate the Go programming landscape, keep reflection in your toolkit for situations that demand a deeper understanding of types and runtime manipulation. The journey into reflection might be complex, but the rewards in terms of code flexibility and adaptability are well worth the exploration. Happy coding!

How I approach and structure Enterprise frontend applications after 4 years of using Next.js

Joseph Mukorivo — Sat, 09 Sep 2023 13:09:00 +0000

Introduction

In the fast-paced world of frontend development, staying ahead of the curve is essential for building successful enterprise applications. After four years of using Next.js and a powerful toolkit that includes Tailwind CSS, TypeScript, TurboRepo, ESLint, React Query, and more, I have gained valuable insights and best practices to share with fellow developers. In this blog post, we will explore how to architect and structure frontend applications for large-scale enterprises, maximizing performance, maintainability, and scalability.

NB This article expresses personal viewpoints, and the methods I advocate may not be suitable for your specific situations.

Guiding Principles of Effective Enterprise Frontend Architecture

When it comes to architecting frontend solutions for enterprise-scale applications, having a well-defined set of principles can be the North Star that keeps your development efforts on course. In this section, I'll share the guiding principles that have emerged from my experience with Next.js in enterprise environments.

Modularity and Componentization

Principle: Divide and Conquer

In the sprawling landscape of enterprise applications, code can quickly become an unruly beast. Embrace modularity and componentization to break down your frontend into manageable pieces. Think of components as Lego blocks, each serving a specific purpose. This not only enhances code reusability but also simplifies maintenance and collaboration within your development team. Consider not only the segmentation of your application into smaller components, but also the possibility of breaking it down into smaller standalone applications. This is an area where tools like Turbo repo excel.

Separation of Concerns (SoC)

Principle: Keep Your Codebase Neat

To maintain code sanity, adhere to the Separation of Concerns (SoC) principle. Ensure that your components focus on their respective responsibilities, whether it's rendering UI, handling business logic, or managing state. This segregation not only makes code easier to understand but also facilitates testing and debugging.

Scalability by Design

Principle: Plan for Growth

Enterprise applications aren't static; they evolve. Design your frontend architecture with scalability in mind. This means selecting patterns and tools that can accommodate increased traffic, data volume, and feature complexity. Next.js's scalability-friendly design can be a valuable ally in this endeavor.

Maintainability and Code Quality

Principle: Craft with Care

Code is your product's foundation. Prioritize maintainability and code quality from day one. Enforce coding standards, conduct code reviews, and invest in automated testing. A well-maintained codebase is not only easier to work with but also less prone to bugs and regressions. At work I recently developed a component library and a basic style guide to enforce standards on our frontend applications. Don't mind the docs they are not yet done😂.

Accessibility by Default

Principle: Inclusive from the Start

Accessibility is a non-negotiable aspect of modern web development. Make it a default practice from the beginning. Ensure your application is usable by all, regardless of disabilities. Leverage Next.js's support for accessibility standards and tools to create inclusive user experiences. I use tools like Radix UI for some components that require accessibility like the tabs, dropdowns, etc.

Performance-Oriented Development

Principle: Speed Matters

Enterprise users expect snappy experiences. Prioritize performance at every turn. Optimize assets, minimize unnecessary requests, and leverage Next.js's performance features like automatic code splitting, streaming with suspense and image optimization. A fast application not only pleases users but also positively impacts SEO.

Security First

Principle: Guard Your Castle

Security should be woven into the fabric of your frontend architecture. Protect against common vulnerabilities like Cross-Site Scripting (XSS) and Cross-Site Request Forgery (CSRF). Stay vigilant with security updates and best practices, and consider Next.js's built-in security features as an extra layer of defense.

Internationalization (i18n) and Localization (l10n)

Principle: Think Globally

In our interconnected world, thinking globally is essential. Implement internationalization (i18n) and localization (l10n) from the outset to cater to a diverse user base. Next.js provides excellent support for these features, making it easier to create multilingual applications.

These guiding principles form the bedrock of an effective enterprise frontend architecture when working with Next.js. They act as a compass, ensuring that your development efforts align with the demands of large-scale applications, making them robust, maintainable, and user-friendly. In the following sections, we'll delve deeper into how these principles can be translated into actionable strategies and best practices.

Folder and file structure

In React, organizing your project with a well-thought-out folder structure is crucial for maintainability and scalability. A common approach is to arrange files based on their functionality and purpose. Here's the sample folder structure I typically use for my applications:

├─ src/
│ ├─ components/
│ │ ├─ ui/
│ │ │ ├─ Button/
│ │ │ ├─ Input/
│ │ │ ├─ ...
│ │ │ └─ index.tsx
│ │ ├─ shared/
│ │ │ ├─ Navbar/
│ │ └─ charts/
│ │ │ ├─ Bar/
│ ├─ modules/
│ │ ├─ HomePage/
│ │ ├─ ProductAddPage/
│ │ ├─ ProductPage/
│ │ ├─ ProductsPage/
│ │ │ ├─ api/
│ │ │ │ └─ useGetProducts/
│ │ │ ├─ components/
│ │ │ │ ├─ ProductItem/
│ │ │ │ ├─ ProductsStatistics/
│ │ │ │ └─ ...
│ │ │ ├─ utils/
│ │ │ │ └─ filterProductsByType/
│ │ │ └─ index.tsx
│ │ ├─ hooks/
│ │ ├─ consts/
│ │ └─ types/
│ │ └─ lib/
| | └─ styles/
│ │ │ ├─ global.css
│ │ └─ ...
│ ├─ public/
│ │ ├─ ...
│ │ └─ index.tsx
│ ├─ eslintrc.js
│ ├─ package.json
│ └─ tsconfig.json
└─ ...

src/components: This directory contains your UI components. It's further subdivided into ui for generic UI components and shared for components that might be reused across different parts of your application.
src/modules: This directory houses your application's different modules or pages. Each module might have its own folder, containing subdirectories for API calls, components and utility functions.
src/pages: If you are using Next.js this folder should only be used as the entry point to your application. No business logic should reside here. Components in the pages folder should only render pages from the modules folder.
src/modules/ProductsPage: This module is related to products, and it contains subdirectories for API calls, components (like ProductItem and ProductsStatistics), and utility functions (filterProductsByType).
src/lib: This folder may contain utility functions that can be converted later into packages that are used across multiple applications. It's different from src/utils which may contain utility functions that do not make sense to convert into packages later.
src/styles: This directory holds global styles (global.css) and possibly other style-related files.
src/public: This folder contains static assets that don't go through the build process. It might include images, fonts, and the index.html file.
src/consts, src/types: These directories likely contain constants and TypeScript type definitions respectively.
src/hooks: This directory may house custom hooks that are used throughout your application.
eslintrc.js: This is a configuration file for ESLint, a popular JavaScript linting tool. It's used to enforce coding conventions and catch potential errors in your code.

The tsconfig file is configured such that if you for example want to import a Button component you can do it like so import { Button } from '@/components/ui'. Below is a snippet of how to configure that from tsconfig.json.

{
  ...
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

TypeScript coding conventions

The conventions I follow are inspired by this guide here. I highly recommend you read it and the code snippets below are coming from that guide.

All types must be defined with type alias

// ❌ Avoid interface definitions unless you need to extend or implement them
interface UserRole = 'admin' | 'guest'; // invalid - interface can't define (commonly used) type unions

interface UserInfo {
  name: string;
  role: 'admin' | 'guest';
}

// ✅ Use type definition
type UserRole = 'admin' | 'guest';

type UserInfo = {
  name: string;
  role: UserRole;
};

Avoid using multiple arguments

// ❌ Avoid having multiple arguments
transformUserInput('client', false, 60, 120, null, true, 2000);

// ✅ Use options object as argument
transformUserInput({
  method: 'client',
  isValidated: false,
  minLines: 60,
  maxLines: 120,
  defaultInput: null,
  shouldLog: true,
  timeout: 2000,
});

Naming Conventions

Although determining the optimal name can be challenging, try to enhance code readability and maintain consistency for future developers by adhering to established conventions:

Variables

Locals Camel case products, productsFiltered
Booleans Prefixed with is, has etc. isDisabled, hasProduct
Constants Capitalized PRODUCT_ID
Object constants

Singular, capitalized with const assertion and optionally satisfies type (if there is one).

  const ORDER_STATUS = {
    pending: 'pending',
    fulfilled: 'fulfilled',
    error: 'error',
  } as const satisfies OrderStatus;

Functions

Camel case

filterProductsByType, formatCurrency

Generics

A name starts with the capital letter T TRequest, TFooBar (similar to .Net internal implementation).

Avoid (popular convention) naming generics with one character T, K etc., the more variables we introduce, the easier it is to mistake them.

// ❌ Avoid naming generics with one character
const createPair = <T, K extends string>(first: T, second: K): [T, K] => {
  return [first, second];
};
const pair = createPair(1, 'a');

// ✅ Name starts with the capital letter T
const createPair = <TFirst, TSecond extends string>(
  first: TFirst,
  second: TSecond
): [TFirst, TSecond] => {
  return [first, second];
};
const pair = createPair(1, 'a');

Packages and tools.

In application development, it's common practice to leverage third-party tools to avoid unnecessary duplication of work. Here are some of the packages I utilize when building scalable applications.

React Query/Tanstack Query

React Query is highly beneficial in managing data fetching and synchronization in complex enterprise applications. It provides a unified approach to fetching data from APIs, caching, and handling mutations. In enterprise settings, applications often need to interact with multiple APIs and services. React Query can streamline this process by centralizing data management and reducing boilerplate code.

React Context

React Context is instrumental in managing global state across various components without the need for prop drilling. This is particularly valuable in enterprise applications where shared state, such as user authentication or preferences, needs to be accessible throughout the application.

I generally reserve the use of React Context or other state management tools as a last resort. It's advisable to minimize reliance on global state. Instead, aim to keep your state closer to where it's specifically required.

Cypress

Cypress is an excellent tool for end-to-end (E2E) testing. In enterprise applications, ensuring that critical workflows and features function correctly across different screens and components is paramount. Cypress is by far my favourite tool. Whenever my tests pass it gives me confidence that the code I introduced did not break the application. As enterprise applications evolve, it's crucial to conduct regression testing to catch any unintended side effects of new code changes. Cypress facilitates this by automating the testing process.

React Testing Library:

React Testing Library is essential for unit and integration testing of React components. In enterprise applications, verifying that individual components work as expected is crucial for a robust application. React Testing Library allows for thorough testing of each component in isolation, as well as in conjunction with others.

NextAuth.js:

NextAuth.js simplifies the implementation of authentication and authorization in Next.js applications. In enterprise settings, secure user management is non-negotiable. Enterprises often employ Single Sign-On (SSO) solutions to streamline user authentication across multiple applications. NextAuth.js supports various SSO providers, making it an excellent fit for enterprise authentication needs. NextAuth.js also offers the flexibility to implement custom authentication flows.

I have a blog here that shows you how to customise default User model in NextAuth.js with TypeScript using module augmentation.

Turbo Repo

This is also my favourite tool. Turbo Repo is a valuable tool for managing monorepos. In large enterprise applications, codebases can be extensive, with various modules, services, and shared code. Turbo Repo aids in organizing, versioning, and deploying these codebases efficiently. In enterprise settings, code sharing across different teams and projects is common. Turbo Repo enables effective code sharing, allowing teams to collaborate on shared libraries and components.

Storybook

Storybook allows developers to isolate UI components and showcase them in a controlled environment. This makes it easy to demonstrate how individual components look and behave without the need to navigate through the entire application. In large enterprise applications, different developers or teams may be responsible for different parts of the UI. Storybook provides a centralized platform for showcasing and discussing UI components, fostering efficient collaboration and ensuring a consistent design language. Here is a sample component library I developed and documented using storybook.(It's still a work in progress btw)

In an enterprise context, these tools collectively provide a comprehensive toolkit for building, testing, and maintaining large-scale applications, addressing critical aspects like data management, state handling, testing, authentication, and code organization.

Coding style for reusable components

When I develop reusable components like inputs, dialogs, etc I try to follow some best practices.

Let's try some best practices for developing a Button component together and you will see that its more than just the visual design.

Component Reusability

Ensure that your button component is designed to be reusable across different parts of your application. It should be flexible enough to accommodate various use cases.

Props for Customization

Provide props for common customization options like size, color, variant (e.g., primary, secondary), and disabled state. This allows developers to easily adapt the button to fit different UI contexts.

Accessibility Considerations

Implement proper accessibility features such as aria-label, aria-disabled, and focus management. This ensures that users of assistive technologies can interact with the button effectively.

Semantic HTML

Use semantic HTML elements (e.g., ) for your button component. This enhances accessibility and SEO, and ensures proper behavior across different devices.

Mimic the native button element

All these best practices we are following forces us to write predictable code. If you develop a custom button component, make it work and behave like a button. You will see from the example component we will write together that I try to include all props a button can take by extending the native button element.

Error Handling

If the button can potentially lead to an error state (e.g., submitting a form), provide a way to handle and communicate these errors to the user.

Testing

Write unit tests to verify that the button component behaves as expected in different scenarios. Test cases should cover various props and event handlers.

Documentation

Document the usage of the button component, including available props, event handlers, and any specific use cases. Provide examples and code snippets to guide developers. This is where storybook shines.

Cross-Browser Compatibility:

Test the button component in different browsers to ensure consistent behavior and appearance.

Versioning and Changelog

If the button component is part of a shared library, implement versioning and maintain a changelog to keep developers informed of updates and changes.

Coding

For my components I usually have files like these. Button.tsx, Button.stories.tsx, Docs.mdx, Button.test.ts. If you are using CSS you may have something like Button.module.css.

components/ui/Button.tsx
This is the main component and the cn function merges the classes and handles conflicts. It's a wrapper around the tw-merge library.

import React from 'react';
import {
  forwardRef,
  type ButtonHTMLAttributes,
  type JSXElementConstructor,
  type ReactElement,
} from 'react';
import { AiOutlineLoading3Quarters } from 'react-icons/ai';
import type { VariantProps } from 'cva';
import { cva } from 'cva';
import Link from 'next/link';
import { cn } from '@/lib';

const button = cva(
  'flex w-max items-center border-[1.5px] gap-2 transition duration-200 ease-linear focus:outline-0 focus:ring ring-offset-1 dark:ring-offset-blue-dark',
  {
    variants: {
      variant: {
        outline: '...',
        solid: '...',
        naked: '...',
      },
      rounded: {
        none: 'rounded-none',
        sm: 'rounded',
        md: 'rounded-lg',
        lg: 'rounded-xl',
        full: 'rounded-full',
      },
      color: {
        primary: '...',
        danger: '...',
        info: '...',
        warning: '...',
        light: '...',
        secondary: '...',
      },
      size: {
        xs: '...',
        sm: '...',
        md: '...',
        lg: '...',
      },
      disabled: {
        true: '...',
      },
      active: {
        true: '...',
      },
      loading: {
        true: '...',
      },
      fullWidth: {
        true: '...',
      },
      align: {
        center: '...',
        left: '...',
        right: '...',
        between: '...',
      },
    },
    compoundVariants: [
      {
        variant: 'solid',
        color: ['secondary', 'warning', 'danger', 'info'],
        className: '...',
      },
      {
        variant: 'solid',
        color: 'primary',
        className: '...',
      },
      {
        variant: 'outline',
        color: ['primary', 'secondary', 'warning', 'danger', 'info'],
        className: '...',
      },
      {
        variant: 'outline',
        color: 'light',
        className:
          '...',
      },
      {
        variant: 'naked',
        color: ['primary', 'secondary', 'warning', 'danger', 'info'],
        className:
          '...',
      },
      {
        disabled: true,
        variant: ['solid', 'outline', 'naked'],
        color: ['primary', 'secondary', 'warning', 'danger', 'info', 'light'],
        className: '...',
      },
      {
        variant: 'outline',
        color: ['primary', 'secondary', 'warning', 'danger', 'info', 'light'],
        className: '...',
      },
      {
        variant: 'naked',
        color: 'primary',
        className: '...',
      },
    ],
    defaultVariants: {
      size: 'md',
      variant: 'solid',
      color: 'primary',
      rounded: 'lg',
      align: 'center',
    },
  }
);

interface BaseProps
  extends Omit<
      ButtonHTMLAttributes<HTMLButtonElement>,
      'color' | 'disabled' | 'active'
    >,
    VariantProps<typeof button> {
  href?: string;
  loadingText?: string;
  target?: '_blank' | '_self' | '_parent' | '_top';
  as?: 'button' | 'a' | JSXElementConstructor<any>;
}

export type ButtonProps = BaseProps &
  (
    | {
        rightIcon?: ReactElement;
        leftIcon?: never;
      }
    | {
        rightIcon?: never;
        leftIcon?: ReactElement;
      }
  );

export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
  (props, ref) => {
    const {
      as: Tag = 'button',
      variant,
      color,
      rounded,
      size,
      target = '_self',
      loading,
      fullWidth,
      align,
      loadingText,
      href,
      active,
      rightIcon,
      leftIcon,
      className,
      disabled,
      children,
      ...rest
    } = props;

    const classes = cn(
      button({
        variant,
        color,
        size,
        disabled,
        loading,
        active,
        rounded,
        fullWidth,
        align,
      }),
      className
    );

    return (
      <>
        {href ? (
          <Link className={classes} href={href} target={target}>
            {leftIcon}
            {children}
            {rightIcon}
          </Link>
        ) : (
          <Tag className={classes} disabled={disabled} ref={ref} {...rest}>
            {loading ? (
              <>
                <AiOutlineLoading3Quarters className='animate-spin' />
                {loadingText || 'Loading...'}
              </>
            ) : (
              <>
                {leftIcon}
                {children}
                {rightIcon}
              </>
            )}
          </Tag>
        )}
      </>
    );
  }
);

Button.displayName = 'Button';

components/ui/Button.stories.tsx

This file has the button stories for storybook.

import { Meta, StoryObj } from '@storybook/react';
import React from 'react';
import { FaRegSmileWink, FaThumbsUp, FaYinYang } from 'react-icons/fa';
import { FiArrowUpRight } from 'react-icons/fi';
import { Button } from './Button';

export default {
  title: 'Components/Button',
  component: Button,
  parameters: {},
  args: {
    children: 'Click me!',
  },
  argTypes: {
    children: {
      description: 'This is the text of the button, can be a node.',
      control: { type: 'text' },
    },
    color: {
      options: ['primary', 'danger', 'info', 'warning', 'secondary', 'light'],
      control: { type: 'select' },
      description: 'This controls the color scheme of the button',
      table: {
        defaultValue: { summary: 'primary' },
      },
    },
    variant: {
      options: ['solid', 'outline', 'naked'],
      control: { type: 'select' },
      description: 'This controls the variant of the button',
      table: {
        defaultValue: { summary: 'solid' },
      },
    },
    size: {
      options: ['sm', 'md', 'lg'],
      control: { type: 'radio' },
      description: 'This controls the size of the button',
      table: {
        defaultValue: { summary: 'md' },
      },
    },
    loading: {
      control: { type: 'boolean' },
      description: 'This controls the loading state of the button',
      table: {
        defaultValue: { summary: false },
      },
    },
    href: {
      control: { type: 'text' },
      description:
        'If this is set, the button will be rendered as an anchor tag.',
    },
    className: {
      control: { type: 'text' },
      description: 'Classes to be applied to the button',
    },
    disabled: {
      control: { type: 'boolean' },
      description: 'If true, the button will be disabled',
      table: {
        defaultValue: { summary: false },
      },
    },
    rightIcon: {
      options: ['Smile', 'ThumbsUp', 'YinYang'],
      mapping: {
        Smile: <FaRegSmileWink />,
        ThumbsUp: <FaThumbsUp />,
        YinYang: <FaYinYang />,
      },
      description:
        'If set, the icon will be rendered on the right side of the button',
    },
    leftIcon: {
      options: ['Smile', 'ThumbsUp', 'YinYang'],
      mapping: {
        Smile: <FaRegSmileWink />,
        ThumbsUp: <FaThumbsUp />,
        YinYang: <FaYinYang />,
      },
      description:
        'If set, the icon will be rendered on the left side of the button',
    },
    loadingText: {
      control: { type: 'text' },
      description:
        'If set, the text will be rendered while the button is in the loading state',
    },
    target: {
      control: { type: 'text' },
      description:
        'If set, the target will be rendered as an attribute on the anchor tag',
      table: {
        defaultValue: { summary: '_self' },
      },
    },
    as: {
      options: ['button', 'a'],
      control: { type: 'select' },
      description:
        'If set, the button will be rendered as the specified element',
      table: {
        defaultValue: { summary: 'button' },
      },
    },
  },
} as Meta<typeof Button>;

type Story = StoryObj<typeof Button>;

export const Primary: Story = {
  args: {},
};

export const Secondary: Story = {
  args: {
    color: 'secondary',
  },
};

export const Danger: Story = {
  args: {
    color: 'danger',
  },
};

export const Warning: Story = {
  args: {
    color: 'warning',
  },
};

export const Light: Story = {
  args: {
    color: 'light',
  },
};

export const Info: Story = {
  args: {
    color: 'info',
  },
};

export const Custom: Story = {
  args: {
    className: 'bg-[yellow] text-[black] border-[orange]',
    style: { borderRadius: '3.5rem' },
  },
};

export const WithRightIcon: Story = {
  args: {
    rightIcon: <FiArrowUpRight className='h-5 w-auto' />,
  },
};

export const WithLeftIcon: Story = {
  args: {
    leftIcon: <FiArrowUpRight className='h-5 w-auto' />,
  },
};

export const Disabled: Story = {
  args: {
    disabled: true,
  },
};

export const OutlineVariant: Story = {
  args: {
    variant: 'outline',
    color: 'danger',
  },
};

export const NakedVariant: Story = {
  args: {
    variant: 'naked',
    color: 'danger',
  },
};

export const Loading: Story = {
  args: {
    loading: true,
  },
};

export const CustomLoadingText: Story = {
  args: {
    loading: true,
    loadingText: 'Processing...',
  },
};

export const AsLink: Story = {
  args: {
    href: 'https://fin.africa',
    children: 'Visit fin website',
    rightIcon: <FiArrowUpRight className='h-5 w-auto' />,
  },
};

export const FullWidth: Story = {
  args: {
    fullWidth: true,
    children: 'Visit fin website',
    rightIcon: <FiArrowUpRight className='h-5 w-auto' />,
  },
};

components/ui/Docs.mdx

The stories file is OK for documenting how the component works but a markdown file can have more extensive documentation.

The conventions I used to develop the Button component are the same conventions I try to follow for all my components.

Key takeaways

Have a design system of some sort, weather its an open source solution or you spin up your own.
Make TypeScript your friend. Use TypeScript to your advantage, use it to enforce how you want people to consume your components. A good example on this is on our Button component. It has 2 props leftIcon and rightIcon. We have used TypeScript to make sure that only one of these is set otherwise it errors to the developer.

export type ButtonProps = BaseProps &
  (
    | {
        rightIcon?: ReactElement;
        leftIcon?: never;
      }
    | {
        rightIcon?: never;
        leftIcon?: ReactElement;
      }
  );

Document your code and components. Use tools like storybook.
Have some sort of a style guide to make sure that you speak the same language with your team.
Write dump code. Keep your codebase straightforward and focused. Each piece of code should have a single, clear purpose.
Understand how things work under the hood. I published an article here after I found out how React checks if two values are the same.

Conclusion

We've explored some of the methods and tools I utilize. Although I haven't covered all the tools at my disposal, I suggest identifying what suits your particular requirements. It's advisable to stick to technologies you're skilled in, rather than adopting something solely for its novelty.

In the end, clients are most concerned with the final product, not the specific technologies you employ. Whether it's React, Vue, or another tool, prioritize the use of tools and workflows that enable quick deployment for the benefit of your users.

Resources

Unlock Next-Level Authentication in Next.js with Next Auth and TypeScript Module Augmentation

Joseph Mukorivo — Sat, 08 Apr 2023 11:33:37 +0000

Next.js is a popular React framework for building web applications. When building authentication features in Next.js, developers often use NextAuth.js as it provides a simple way to implement authentication, authorization and session management. NextAuth.js supports a variety of authentication providers such as Google, Facebook, Twitter, etc.

In some cases, developers may want to extend the functionality of the User and Session objects provided by NextAuth.js. Fortunately, TypeScript module augmentation allows us to do just that.

TypeScript module augmentation is a way of extending the types of an existing module. In our case, we will be using module augmentation to add additional fields to the User and Session objects provided by NextAuth.js.

Step 1: Create a custom User and Session interface

You'll need to create a custom interface for your User and Session objects. This will allow you to add additional fields to the objects using TypeScript module augmentation.

Create a new file in the root of your project called next-auth.d.ts. This file will contain the custom User and Session interfaces. Add the following code to the file:

import NextAuth from "next-auth"

declare module "next-auth" {
  interface User {
    name: string
  }

  interface Session {
    user: {
      name: string
    }
  }
}

In this example, we're adding a name field to both the User and Session objects. You can add any additional fields that you need.

Step 2: Update your authentication provider

Now that you've defined your custom User and Session interfaces, you'll need to update your authentication provider to include the new fields.

In your [...nextauth].ts file, add the following code to the options object:

import NextAuth from 'next-auth';
import type { NextAuthOptions } from 'next-auth';
import CredentialsProvider from 'next-auth/providers/credentials';
import { signIn } from '@/services/auth';

const MINUTE = 60;
const HOUR = 60 * MINUTE;

export const authOptions: NextAuthOptions = {
  providers: [
    CredentialsProvider({
      credentials: {},
      async authorize(credentials, req) {
        const { email, password, tenant } = credentials as {
          email: string;
          password: string;
        };
        const { user, token, error } = await signIn(
          { email, password }
        );
        if (user) {
          return {
            id: +user.id,
            name:
              `${user.firstName} ${user.lastName}`,
            email: user.email,
            jwt: token,
          };
        }
        if (error) {
          throw new Error(error);
        }
        return null;
      },
    }),
  ],
  jwt: {
    secret: process.env.NEXTAUTH_SECRET,
  },
  session: {
    maxAge: 8 * HOUR, // 8 hours
  },
  pages: {
    signIn: '/login',
  },
  callbacks: {
    async jwt({ token, user }) {
      if (user) {
        token.id = +user.id;
        token.jwt = user.jwt;
        token.name = user.name;
        token.email = user.email;
      }
      return token;
    },
    session: async ({ session, token }) => {
      session.user.id = token.id;
      session.jwt = token.jwt;
      session.user.name = token.name;
      session.user.email = token.email;
      return session;
    },
  },
};

export default NextAuth(authOptions);

In this example, we're adding a callbacks object to the options object. This object includes a session function that is called when a new session is created. In the session function, we're adding the name field to the user object in the session.

Step 3: Use the custom fields in your application

Now that you've added the custom fields to your User and Session objects, you can use them in your application. Here's an example of how to use the name field in a React component:

import { useSession } from "next-auth/react"

export default function Home() {
  const { data: session } = useSession()

  return (
    <div>
      <h1>Welcome, {session?.user.name ?? "guest"}!</h1>
    </div>
  )
}

In this example, we're using the useSession hook to get the user's session object.The code displays a greeting that includes the user's name if they are logged in, or "guest" if they are not. The ?. operator is used to safely access the name property of the user object within the session object. If session is undefined or user is undefined, the ?? operator provides a fallback value of "guest".

Getting started with python Data classes(Part 1)

Joseph Mukorivo — Mon, 28 Nov 2022 08:47:41 +0000

Have you seen a @dataclass decorator in some python code and still don't understand what it does? Hang in there we are going to cover it here.

The @dataclass decorator comes from from the dataclasses module and what this module does is to provide a decorator and functions for adding special/dunder methods to you class such as __init__() and __repr__().

Let's start with a simple example here:

from dataclasses import dataclass

@dataclass
class Programmer:
    """Class for keeping track of programmer information."""
    name: str
    age: int

    def total_friends(self) -> int:
        return self.age - self.age

The above example will add a __init__() method that looks like this:

def __init__(self, name: str, age: int):
    self.name = name
    self.age = age

This method is automatically added for you unless you specify it.
You might be wondering what might be the benefit of this, well to answer that let's look at what are special/dunder methods and what they do.

Special methods

Special/dunder methods are methods that are preceded and succeeded by double underscores, hence the name dunder. They are predominantly used for operator overloading which means that a predefined operator is provided with extended meaning.

Below is an example of operator overloading.

class Vector:

    def __init__(self, x, y):
        self.x = x
        self.y = y

    # this allows us to add Vectors
    def __add__(self, other):
        return self.__class__(self.x + other.x, self.y + other.y)

v1 = Vector(1, 4)
v2 = Vector(5, 3)

v3 = v1 + v2 # v3.x == 6 and v3.y == 7

The above __add__() method allows us to add Vectors and if we try to add them without overriding add we will get an error.

The most recognized special method is the __init__() method, which enables a class to be initialized with specific attributes.

class Programmer:
    """Class for keeping track of programmer information."""
    def __init__(self, name: str, age: int):
        self.name = name
        self.age = age

To instantiate an instance of the Programmer class, we must specify the instance's name and age. For example:

john = Programmer(name='John', age=29)

What dataclasses does for you

The dataclass() decorator examines the class to find fields. A field is defined as a class variable that has a type annotation. The order of the fields in all of the generated methods is the order in which they appear in the class definition.

The dataclass() decorator also takes some arguments and below are the default arguments from the function's signature.

@dataclasses.dataclass(*, init=True, repr=True, eq=True, order=False, 
unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False, 
weakref_slot=False)

By default the dataclass() decorator adds the __init__(), __repr__() and the __eq__() methods.

In general data classes helps getting rid of boilerplate code. All the methods generated for you by the dataclass() decorator can be overridden if you want to alter the behavior.

In my next post about data classes I will get into more advanced features and give a useful real world example.

Photo by Rubaitul Azad on Unsplash

How we developed our company website using NextJS

Joseph Mukorivo — Mon, 17 Oct 2022 06:17:51 +0000

I sat down with my close friends that I had been working with for a while at the start of 2022 to discuss about starting a software company that merged aesthetics and functionality. We made the decision to combine our various skill sets to form that business, and complexus was established.

We completed a few projects for other clients before deciding to concentrate on our website. We began by conducting research on our target market, and then the team began to work on the initial iteration of the site's design.

Overview

In this article, I'll primarily discuss the tools we utilized and how we used them to create our dynamic website. These are the tools we typically employ for our clients' projects.

Design

The design team used figma to create the site's design, and a screenshot of the initial version is seen below. The design was finished after four iterations, the first of which was a low-fidelity wireframe. Almost everyone contributed to the design in some way.

Content

We had someone in charge of copywriting for the site's material, and they collaborated with the design team to ensure that what they were writing was consistent with the design.

Development

We went on to build the website after creating the design and the content. Let me list some of the things that the website is powered by before I get into the technicalities.

React for the UI
NextJS for SSG/SSR/ISSG
Tailwind css for styling
CSS modules styling without class name collision
GSAP JavaScript animations
Mailchimp for the mailing list
Vercel CI/CD and hosting
Framer motion JavaScript animations
TypeScript for adding type safety to our codebase

I will probably spend a little more time at this stage because development was the most fascinating phase. Reactjs is the foundation of the website and all the components were built upon it. Below is a sample reusable Button component and its styles.

Button.tsx

import {
  FC,
  forwardRef,
  ButtonHTMLAttributes,
  JSXElementConstructor,
  ReactElement,
} from 'react';
import Link from 'next/link';
import { motion } from 'framer-motion';
import cn from 'classnames';

import s from './Button.module.scss';

interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  href?: string;
  className?: string;
  disabled?: boolean;
  rightIcon?: ReactElement;
  leftIcon?: ReactElement;
  active?: boolean;
  target?: '_blank' | '_self' | '_parent' | '_top';
  size?: 'sm' | 'md' | 'lg';
  variant?:
    | 'primary'
    | 'secondary'
    | 'white'
    | 'black'
    | 'naked'
    | 'outlineBlack'
    | 'outlineWhite'
    | 'square';
  as?: 'button' | 'a' | JSXElementConstructor<any>;
}

export const Button: FC<ButtonProps> = forwardRef((props, buttonRef) => {
  const {
    as: Tag = 'button',
    variant = 'primary',
    size = 'md',
    target = '_self',
    href,
    active,
    rightIcon,
    leftIcon,
    className,
    disabled,
    children,
    ...rest
  } = props;
  const classes = cn(
    s.root,
    {
      [s.primary]: variant === 'primary',
      [s.outlineBlack]: variant === 'outlineBlack',
      [s.outlineWhite]: variant === 'outlineWhite',
      [s.secondary]: variant === 'secondary',
      [s.white]: variant === 'white',
      [s.naked]: variant === 'naked',
      [s.black]: variant === 'black',
      [s.square]: variant === 'square',
      [s.md]: size === 'md',
      [s.sm]: size === 'sm',
      [s.lg]: size === 'lg',
      'flex items-center gap-3': (rightIcon || leftIcon) && size === 'md',
      [s.dFlex]: (rightIcon || leftIcon) && size === 'lg',
      [s.active]: active,
    },
    className
  );

  return (
    <motion.span
      className='inline-block'
      initial={{ y: 10, opacity: 0 }}
      transition={{
        duration: 1,
        type: 'spring',
        damping: 5,
      }}
      whileInView={{ opacity: 1, y: 0 }}
      viewport={{ once: true, amount: 0.5 }}
    >
      {href ? (
        <Tag {...rest}>
          <Link href={href}>
            <a className={classes} target={target}>
              {leftIcon}
              <span>{children}</span>
              {rightIcon}
            </a>
          </Link>
        </Tag>
      ) : (
        <Tag disabled={disabled} className={classes} {...rest}>
          {leftIcon}
          <span>{children}</span>
          {rightIcon}
        </Tag>
      )}
    </motion.span>
  );
});

Button.displayName = 'Button';

Button.module.scss

.root {
  @apply mb-1 transition duration-200 ease-linear;
}

.dFlex {
  @apply flex items-center gap-5;
}

.primary {
  @apply relative overflow-hidden border border-primary bg-primary text-white;

  span,
  svg {
    @apply relative z-[2];
  }

  &::after {
    content: '';
    @apply absolute top-0 left-0 block h-full w-0 bg-white transition-[width] duration-300 ease-linear;
  }

  &:hover {
    @apply text-primary;
  }

  &:hover::after {
    @apply w-full;
  }
}

.naked {
  @apply bg-transparent;
}

.black {
  @apply relative border border-black bg-black text-white;

  &::after {
    content: '';
    @apply absolute top-0 left-0 block h-full w-0 bg-white mix-blend-difference transition-[width] duration-300 ease-linear;
  }
  &:hover::after {
    @apply w-full;
  }
}

.white {
  @apply border border-white bg-white text-primary;
}

.secondary {
  @apply border border-secondary bg-secondary text-white;
}

.outlineBlack {
  @apply relative border border-black;

  &::after {
    content: '';
    @apply absolute top-0 left-0 block h-full w-0 bg-white mix-blend-difference transition-[width] duration-300 ease-linear;
  }
  &:hover::after {
    @apply w-full;
  }
}

.square {
  @apply relative flex h-12 w-12 items-center justify-center rounded-full border border-black p-0 hover:scale-110 3xl:h-20 3xl:w-20 3xl:border-2 #{!important};
}

.outlineWhite {
  @apply relative border border-white text-white;

  &::before {
    content: '';
    @apply absolute left-[20%] -bottom-[1px] h-[1px] w-7 bg-black transition-[left];
  }

  &::after {
    content: '';
    @apply absolute right-[20%] -top-[1px] h-[1px] w-7 bg-black transition-[right];
  }

  &:hover::before {
    @apply left-[30%];
  }
  &:hover::after {
    @apply right-[30%];
  }

  &:hover {
    @apply opacity-100;
  }
}

.sm {
  @apply px-4 py-2;
}

.md {
  @apply px-4 py-[10px] xl:px-6;
}

.lg {
  @apply px-5 py-4 text-sm font-medium xl:py-[1.1rem] xl:px-8 xl:text-base 3xl:px-16 3xl:py-6 3xl:text-lg;
}

The components were code using TypeScript for type safety. TypeScript also helps with writing code that is self documenting. For styling we went with tailwindcss but note that classes in our react components are clean because the tailwind utility classes are in a separate css file which is a CSS module. CSS modules helps in avoiding namespace collision for CSS classes. Below will be how the Button can be used.

<Button
  variant='black'
  size='lg'
  href='/contact'
  className='relative ml-2'
  rightIcon={<Line />}
>
  Get in touch
</Button>

All of our reusable components are coded this way.

These small components like the Button, Text, Link and Box are located in the components/ui/ folder and exported using using a single index.ts file so that they can be imported like so

import { Text, Box, Container, Link, Button } from '@components/ui';

Common elements like the Navigation and Footer are in the components/shared/ folder and elements that are specific to a page are in the components/pages/[page-name] folder.

SEO

We had to make sure that our website is search engine friendly so we created a Page component that takes some SEO data as props and every page on the site uses it as a parent.

Page.tsx

import { FC } from 'react';
import Head from 'next/head';

interface Props {
  title: string;
  description: string;
  image: string;
  canonicalURL?: string;
}

export const Page: FC<Props> = ({
  children,
  title,
  description,
  image,
  canonicalURL,
}) => {
  return (
    <>
      <Head>
        <title>{title}</title>
        <meta name='description' content={description} />
        <meta name='author' content='Complexus Technologies' />
        <meta name='image' content={image} />
        <meta name='og:title' content={title} />
        <meta name='og:description' content={description} />
        <meta name='og:image' content={image} />
        <meta name='og:url' content='https://complexus.tech' />
        <meta name='og:site_name' content='Complexus Technologies' />
        <meta name='og:type' content='website' />
        <meta name='twitter:card' content='summary_large_image' />
        <meta name='twitter:title' content={title} />
        <meta name='twitter:alt' content={title} />
        <meta name='twitter:description' content={description} />
        <meta name='twitter:image' content={image} />
        <meta name='theme-color' content='#f43f5e' />
        <meta name='twitter:site' content='@complexus_tech' />
        <meta name='twitter:creator' content='@complexus_tech' />
        {canonicalURL && <link rel='canonical' href={canonicalURL} />}
      </Head>
      <main>{children}</main>
    </>
  );
};

Example Page usage

import type { NextPage } from 'next';
import { Page, HowMuch } from '@components/shared';
import { Hero, Intro, Team } from '@components/pages/about';

const Home: NextPage = () => {
  return (
    <Page
      title='About | Complexus Technologies'
      description='Complexus helps you achieve your business goals through effective planning, design, and development.'
      image='https://complexus.tech/images/banner.jpg'
      url='https://complexus.tech/about/'
      canonicalURL='https://complexus.tech/about/'
      keywords='complexus, complexus technologies, complex, zimbabwe sofware company, mobile development, it consultancy'
    >
      <Hero />
      <Intro />
      <Team />
      <HowMuch />
    </Page>
  );
};

export default Home;

We also used other tools like Google Analytics, Google My Business and Google search console for SEO.
We also used some open graph tags to make sure that the site has some nice priviews when we share it on social media.

Mailing list

In order to share some information about events at Complexus, we are running a mailing list using Mailchimp. If you subscribe we'd be grateful😎.

Hosting

The website is hosted on Vercel and it rebuilds every time we push to the main branch on github.

CTA

If your organization would like to have a website similar to ours, please contact us here or email us at hello@complexus.tech. We also do custom software development check our services here.

How I developed my modern open source portfolio 👨🏾‍💻

Joseph Mukorivo — Sun, 10 Apr 2022 09:45:00 +0000

For quite some time now I have been working on my portfolio website www.josemukorivo.com. The portfolio I was using before this one was developed back in 2018 when I was doing my internship. Recently I felt it was outdated, in fact the site was never updated after the launch.

Old website hero section

Overview

I like to think of a portfolio as a developer playground so sometimes you can even see a portfolio that is running on kubernetes with 10 replicas 😃 simply because the developer wanted to test out some cool kubernetes features. My point here is that the stack I choose may be an overkill for a portfolio, but hey why not😎?

This post is also available as a video here

Design

Before I started developing the portfolio I started by creating wireframes of what I wanted my portfolio to look like. I created these wireframes using a pen and a small book. Below is a sample wireframe for the portfolio.

After designing the wireframes I headed over to figma for the actual design I used for development. Please note that not everything on the portfolio was designed in figma some things were added during development, there are also some things that were designed on figma that were not coded because I changed the design. Below is how the first iteration of the design looked like in figma.

Content

The next thing after the design was generating content for the website. For me that was one of the difficult stages but luckily I didn't want too much content. Can you believe that GitHub Copilot helped me out with some of the content 🤔, I mean the AI is that good👌🏼.

Development

After designing and generating content I started the development of the portfolio. Before I go into the details let me give you a list of some of the things powering the portfolio.

React for the UI
NextJS for SSG/SSR/ISSG
Tailwind css for styling
CSS modules styling without class name collision
Dev.to API
Mailchimp
Vercel
GitHub
Framer motion
TypeScript

Development was the most interesting stage so I am probably going to spent slightly more time here. At the core of this portfolio there is ReactJS. I used React to create all the components. Below is a sample reusable Button component and its styles.

Button.tsx

import {
  FC,
  forwardRef,
  useRef,
  ButtonHTMLAttributes,
  JSXElementConstructor,
} from 'react';
import Link from 'next/link';
import cn from 'classnames';

import s from './Button.module.scss';
import { mergeRefs } from '@utils/index';

interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  href?: string;
  className?: string;
  disabled?: boolean;
  loading?: boolean;
  target?: '_blank' | '_self' | '_parent' | '_top';
  size?: 'sm' | 'md' | 'lg';
  type?: 'button' | 'submit' | 'reset';
  variant?: 'primary' | 'secondary' | 'naked';
  as?: 'button' | 'a' | JSXElementConstructor<any>;
}

export const Button: FC<ButtonProps> = forwardRef((props, buttonRef) => {
  const {
    as: Tag = 'button',
    variant = 'naked',
    size = 'md',
    type = 'button',
    target = '_self',
    href,
    className,
    disabled,
    children,
    ...rest
  } = props;
  const ref = useRef<typeof Tag>(null);
  const classes = cn(
    s.root,
    {
      [s.primary]: variant === 'primary',
      [s.secondary]: variant === 'secondary',
      [s.naked]: variant === 'naked',
      [s.sm]: size === 'sm',
      [s.md]: size === 'md',
      [s.lg]: size === 'lg',
      [s.disabled]: disabled,
    },
    className
  );

  return (
    <>
      {href ? (
        <Tag ref={mergeRefs([ref, buttonRef])} {...rest}>
          <Link href={href}>
            <a className={classes} target={target}>
              {children}
            </a>
          </Link>
        </Tag>
      ) : (
        <Tag
          ref={mergeRefs([ref, buttonRef])}
          disabled={disabled}
          className={classes}
          {...rest}
        >
          {children}
        </Tag>
      )}
    </>
  );
});

Button.displayName = 'Button';

Button.module.scss

.root {
  @apply mb-1 inline-block transition duration-200 ease-linear;
}

.primary {
  @apply bg-rose-500 text-white ring-rose-500 ring-offset-2 hover:bg-rose-600 hover:ring dark:ring-offset-slate-900 2xl:ring-offset-4;
}

.secondary {
  @apply bg-slate-800 text-white ring-slate-800 ring-offset-2 hover:bg-slate-900 hover:ring dark:bg-slate-700 dark:ring-slate-700 dark:ring-offset-slate-900 2xl:ring-offset-4;
}

.naked {
  @apply bg-white text-slate-900;
}

.md {
  @apply px-6 py-2;
}

.lg {
  @apply px-7 py-4 text-sm md:px-8;
}

.disabled {
  @apply cursor-not-allowed opacity-30;
}

The components were code using TypeScript for type safety. TypeScript also helps you with writing code that is self documenting. For styling I used tailwindcss but note that classes in react components are clean because the tailwind utility classes are in a separate css file which is a CSS module. CSS modules helps in avoiding namespace collision for CSS classes. Below will be how the Button can be used.

<Button
   variant='primary'
   size='lg'
   href='/blog'
   className='uppercase'
  >
   Read my blog
</Button>

Almost all of my reusable components are coded this way.

These small components like the Button, Text, Link and Box are located in the components/ui/ folder and exported using using a single index.ts file so that they can be imported like so

import { Text, Box, Container, Link, Button } from '@components/ui';

Sections like the hero section are located in the components/sections/ folder and common elements like the Navigation and Footer are in the components/common/ folder.

Dark mode

This portfolio has both a light and a dark mode, this was made simple by the dark mode support of tailwind. When you first visit the site I check if you have dark mode enabled in your system preferences, if so you get the site in dark otherwise you get it in light mode. There is also a button that allows you to switch between dark and light mode. I even created a custom hook for toggling the theme let me show you the code for that.

useTheme hook

import { useEffect, useState } from 'react';

export const useTheme = () => {
  const getTheme = (): 'light' | 'dark' => {
    // Check user preference for theme first
    if (
      window.localStorage.theme === 'dark' ||
      (!('theme' in window.localStorage) &&
        window.matchMedia('(prefers-color-scheme: dark)').matches)
    ) {
      return 'dark';
    } else {
      return 'light';
    }
  };

  const [theme, setTheme] = useState('');

  const toggleTheme = () => {
    if (theme === 'light') {
      setTheme('dark');
      window.localStorage.setItem('theme', 'dark');
    } else {
      setTheme('light');
      window.localStorage.setItem('theme', 'light');
    }
  };

  useEffect(() => {
    setTheme(getTheme());
    if (theme === 'dark') {
      document.documentElement.classList.add('dark');
    } else {
      document.documentElement.classList.remove('dark');
    }
  }, [theme]);

  return { theme, toggleTheme };
};

Example Usage

import { BiSun, BiMoon } from 'react-icons/bi';
import { useTheme } from 'hooks';

export const Example = () => {

const { theme, toggleTheme } = useTheme();

  return (
    <Box>
     <Button onClick={toggleTheme}>
       {theme === 'dark' ? (
          <BiSun className='h-4 w-auto' />
        ) : (
          <BiMoon className='h-4 w-auto' />
        )}
        {theme === 'dark' ? 'Switch to light mode' : 'Switch to dark mode'}
     </Button>
    </Box>
  );
};

SEO

Even though this was a simple portfolio website I had to make sure that it is search engine friendly. I created a Page component that takes some SEO data as props and every page on the site uses it as a parent.

Page.tsx

import { FC } from 'react';
import Head from 'next/head';

interface Props {
  title: string;
  description: string;
  image: string;
  canonicalURL?: string;
}

export const Page: FC<Props> = ({
  children,
  title,
  description,
  image,
  canonicalURL,
}) => {
  return (
    <>
      <Head>
        <title>{title}</title>
        <meta name='description' content={description} />
        <meta
          name='keywords'
          content='Joseph, Mukorivo, Joseph Mukorivo, software engineer, Harare, Zimbabwe, Harare software developer, zimbabwe developer blog, software development blog, DevOps blog, Cloud Computing blog, React Developer, React Blog'
        />
        <meta name='author' content='Joseph Mukorivo' />
        <meta name='image' content={image} />
        <meta name='og:title' content={title} />
        <meta name='og:description' content={description} />
        <meta name='og:image' content={image} />
        <meta name='og:url' content='https://josemukorivo.com' />
        <meta name='og:site_name' content='Joseph Mukorivo' />
        <meta name='og:type' content='website' />
        <meta name='twitter:card' content='summary_large_image' />
        <meta name='twitter:title' content={title} />
        <meta name='twitter:alt' content={title} />
        <meta name='twitter:description' content={description} />
        <meta name='twitter:image' content={image} />
        <meta name='theme-color' content='#f43f5e' />
        <meta name='twitter:site' content='@josemukorivo' />
        <meta name='twitter:creator' content='@josemukorivo' />
        {canonicalURL && <link rel='canonical' href={canonicalURL} />}
      </Head>
      <main>{children}</main>
    </>
  );
};

Example Page usage

import { About, Hero, LatestBlogs, TechStack } from '@components/sections';
import { Footer, Nav, Page } from '@components/common';

export default function Home({ articles }) {
  return (
    <Page
      title='Joseph Mukorivo | Software Engineer'
      description='Joseph Mukorivo is a Software Engineer, Blogger and DevOps Enthusiat based in Harare, Zimbabwe.'
      image='https://josemukorivo.com/images/me.jpeg'
    >
      <Nav className='absolute py-3 md:py-5' />
      <Hero />
      <About />
      <LatestBlogs articles={articles} />
      <TechStack />
      <Footer />
    </Page>
  );
}

I also used other tools like Google Analytics, Google My Business and Google search console for SEO. Right now a simple google search of my name Joseph Mukorivo gives the user more information about me.
I also used some open graph tags to make sure that the site has some nice priviews when I share it on social media.

Blogs

My blogs are coming straight from the dev.to api and I am using NextJS to build pages with blog content at build time like so. More on NextJS can be found here

export async function getStaticProps() {
  const res = await fetch(
   `https://dev.to/api/articles?username=${DEV_TO_USERNAME}&per_page=5`
  );
  const articles = await res.json();

  return {
    props: {
      articles,
    },
    revalidate: 60,
  };
}

Cool Feature

I added a widget for customising the website. That is what the user uses to toggle between light and dark mode, they can also use it to to turn the website into black and white, apply the hue filter or change text alignment which might be useful for people who read from right to left. This widget is still under development once I get other features to work I am going to open source it as a separate component. The idea for this widget came from a friend of mine.

Mailing list

I am also running a mailing list where I will be sharing some tips about web development and some cloud technologies. Will be glad if you subscribe😎. The mailing list is run using mailchimp.

Hosting

This portfolio is hosted on Vercel and it rebuilds every time I push to the main branch on github.

Final site hero section in dark mode

Repository

I have open sourced my portfolio so that other people can learn from it and also help to improve. You are free to fork and star the repo and always welcome to submit a pull request with improvements and other cool features😎.

Here is the link to the repository

Please

Do not copy the code and host it without modifications, I spent some time doing this project would love it to be unique. Make sure you change the design and other things so that it doesn't look exactly like mine and crediting me by linking back to www.josemukorivo.com is always appreciated.

I hope this article helped you with something. You can follow me on twitter or subscribe to my mailing list to get some information on what I am working on.

How I developed a modern JAMStack website

Joseph Mukorivo — Tue, 15 Feb 2022 11:22:04 +0000

Overview

In 2021 I started working on a rebranding project for a company that I was working for in 2020. Here is a link to the project. The company already had a nice website but they have been using that website since 2018 and they wanted something new and modern that is also easy to manage for non-developers. For this project to be a success I was working with a designer friend. We sat down and started planning how we were going to go about it because even if this was a company website it had a lot of moving parts so it needed some planning.

Figma Design

We used figma for every single component that we developed.

Homepage Design

Myself and my friend already had some experience with scrum for project management, so we decided to use scrum for this project since it was good fit, so we started to create a product backlog, prioritized features and divided the work into sprints. We were working very closely with the product owners to make sure that we were developing what the user really wanted.

Tech stack choice

So this was one of the interesting stages in the development of the project. We decided to use the JAMStack on this project for quite a number reasons. The design for the project was done using figma then I started the development of the UI using React for the UI. I decided to use tailwind css for styling because it makes it super fast to style components. I did not like the idea of having a bunch of classes on my markup so I used tailwind with css modules(I will show the snippets for some of the code). Because we wanted this website to be performant and SEO friendly I decided to use NextJS(The authors call it a React framework for production and they are right). NextJS has many features for performance and SEO out of the box like Server side rendering, Code splitting, optimized images, routing and many more. On this project it didn't make sense to spin up a custom api for the backend so I decided to use a modern CMS which in this case was strapi. All of the backend stuff on this site is coming from strapi.

There are also number of other tools I used but I will not go into the details of those. Below I will give a summary of key things I used.

Key things used in the project

React for the UI
NextJS for SSR/CSR/Routing and more
Tailwindcss for UI styling
Strapi as CMS
Docker for application containerization
nginx as a web server and reverse proxy
git for version control
mailchimp for managing a mailing list

Project Structure

For project structure I followed this structure with some improvements but was good as a starting point. Here is a high level overview.

Creating components

I tried to make the components that I developed reusable, Below are sample files for the Text component.

Text.css

.root {
  @apply mb-4;
}
.root:is(h1, h2, h3, h4, h5, h6) {
    @apply mb-7 2xl:mb-10 leading-tight dark:text-slate-200;
 }

.p {
  @apply text-lg 2xl:text-xl;
}
.span {
  @apply text-lg;
}

.h1 {
  @apply text-4xl md:text-5xl font-heading font-medium uppercase;
}

.h2 {
  @apply text-2xl md:text-4xl font-heading uppercase;
}

.h3 {
  @apply text-3xl;
}

.h4 {
  @apply text-2xl;
}

.h5 {
  @apply text-xl;
}

.h6 {
  @apply text-lg;
}

Text.tsx

import { FC, CSSProperties, ReactNode } from 'react';
import cn from 'classnames';

import s from './Text.module.scss';

type Variant = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'span';

interface Props {
  as?: Variant;
  className?: string;
  style?: CSSProperties;
  children?: ReactNode | any;
  html?: string;
}

export const Text: FC<Props> = ({
  as: Tag = 'p',
  className = '',
  style = {},
  children,
  html,
  ...rest
}) => {
  const classes = cn(
    s.root,
    {
      [s.p]: Tag === 'p',
      [s.span]: Tag === 'span',
      [s.h1]: Tag === 'h1',
      [s.h2]: Tag === 'h2',
      [s.h3]: Tag === 'h3',
      [s.h4]: Tag === 'h4',
      [s.h5]: Tag === 'h5',
      [s.h6]: Tag === 'h6',
    },
    className // make sure to add the className last so it overwrites the other classes
  );

  const htmlProps = html
    ? {
        dangerouslySetInnerHTML: { __html: html },
      }
    : {};

  return (
    <Tag className={classes} {...rest} {...htmlProps}>
      {children}
    </Tag>
  );
};

Example Usage

<Text as='h1'>
 Hi 👋🏼, I’m Joseph. Writer, Software Engineer, DevOps
</Text>

<Text className='cool'>
This is a sample paragraph
</Text>

Hosting and deployment

The company I developed this website for is not a big company and they don't have a big tech team so I used the tools that I thought were easy for someone else to maintain. Strapi is running as a docker container using docker-compose, the frontend is also running in a similar way. In the source code for both strapi and the frontend I created some Make files to run the project. Below is a sample Makefile.

down:
    docker-compose down

build:
    docker-compose up -d --build

redeploy:
    git pull && make down && make build

In this case if there are changes to the source code, the user does not need to know how to use docker, they just run make redeploy in the root of the project and all the code pulling and image building is done for them, of course this is clearly labelled in the README.

So these services are running on different ports on the server and I exposed them using nginx. Below is how one may configure their nginx file for strapi. Please Note on production you have to make sure that you do it in a secure way this is just to help you get started.

server {
   server_name example.com www.example.com;

    location / {
        keepalive_timeout 64;
        proxy_pass http://localhost:8080; # use your local port where strapi is running
        proxy_http_version 1.1;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Server $host;
        proxy_set_header X-NginX-Proxy true;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Host $http_host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_pass_request_headers on;
        proxy_max_temp_file_size 0;
        proxy_redirect off;
        proxy_read_timeout 240s;
    }

    listen 443 ssl; # managed by Certbot
    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; # managed by Certbot
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem; # managed by Certbot
    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot


}
server {
    if ($host = www.example.com) {
        return 301 https://$host$request_uri;
    } # managed by Certbot


    if ($host = example.com) {
        return 301 https://$host$request_uri;
    } # managed by Certbot


   server_name example.com www.example.com;
    listen 80;
    return 404; # managed by Certbot
}

I hope this article helped you. P.S you can follow me on twitter.

Photo by Hal Gatewood on Unsplash

How React checks if 2 values are the same value

Joseph Mukorivo — Mon, 14 Feb 2022 05:47:53 +0000

If you have ever wondered how react internally checks if two values are the same value this is the right blog for you. Well, before we even start looking at how React implements that lets first check to see if we already have a function in plain javascript that does that.

We already have this function Object.is() for that, and according to MDN Web docs Object.is() determines whether two values are the same value. Two values are the same if one of the following holds:

- both undefined
- both null
- both true or both false
- both strings of the same length with the same characters in the same order
- both the same object (meaning both values reference the same object in memory)
- both numbers and
   - both +0
   - both -0
   - both NaN
   - or both non-zero and both not NaN and both have the same value

Note that Object.is() is not the same as the == operator as it does not do any type coercion if the types of values are not the same. It's also not the same as the === operator because they treat NaNs and signed zeros differently. With the === or the == operators -0 and +0 are treated as equal. The === operator also treat NaN and Number.NaN as not equal.

Example usage from MDN Web docs

// Case 1: Evaluation result is the same as using ===
Object.is(25, 25);                // true
Object.is('foo', 'foo');          // true
Object.is('foo', 'bar');          // false
Object.is(null, null);            // true
Object.is(undefined, undefined);  // true
Object.is(window, window);        // true
Object.is([], []);                // false
var foo = { a: 1 };
var bar = { a: 1 };
Object.is(foo, foo);              // true
Object.is(foo, bar);              // false

// Case 2: Signed zero
Object.is(0, -0);                 // false
Object.is(+0, -0);                // false
Object.is(-0, -0);                // true
Object.is(0n, -0n);               // true

// Case 3: NaN
Object.is(NaN, 0/0);              // true
Object.is(NaN, Number.NaN)        // true

So this is how Object.is() works, but since we don't live in a perfect world React can't just use this implementation, they need to have some sort of a polyfill for environments like old browsers that don't support Object.is(). Let paste the polyfill code from React source code and go through it.

function is(x: any, y: any) {
  return (
    (x === y && (x !== 0 || 1 / x === 1 / y)) || (x !== x && y !== y) // eslint-disable-line no-self-compare
  );
}

This function is inline, but to make sure that everyone understands let me put it in a long format.

function is(x: any, y: any) {
      // SameValue algorithm
      if (x === y) {
        // return true if x and y are not 0, OR
        // if x and y are both 0 of the same sign.
        return x !== 0 || 1 / x === 1 / y;
      } else {
        // return true if both x AND y evaluate to NaN.
        // The only possibility for a variable to not be strictly equal to itself
        // is when that variable evaluates to NaN (example: Number.NaN, 0/0, NaN).
        return x !== x && y !== y;
      }
}

The if condition is hit if the values we pass are equal for example if we pass 2 and 2 the condition immediately returns with true because 2 is not equal to 0.

If we pass +0 and -0 the OR part of the return statement is evaluated and 1/0 which is equal to Infinity will be compared to 1/-0 which is -Infinity which will then evaluate to false. This makes sure that even if we pass zeros they are of the same sign.

All that can be refactored to what we have below. If this looks cryptic to you let me know in the comments.

(x === y && (x !== 0 || 1 / x === 1 / y))

For the else part of our function there is a possibility for the function to return true, that is if both x AND y evaluate to NaN, otherwise return false.

Below is the whole React source file for what we went through.

/**
 * Copyright (c) Facebook, Inc. and its affiliates.
 *
 * This source code is licensed under the MIT license found in the
 * LICENSE file in the root directory of this source tree.
 *
 * @flow
 */

/**
 * inlined Object.is polyfill to avoid requiring consumers ship their own
 * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is
 */
function is(x: any, y: any) {
  return (
    (x === y && (x !== 0 || 1 / x === 1 / y)) || (x !== x && y !== y) // eslint-disable-line no-self-compare
  );
}

const objectIs: (x: any, y: any) => boolean =
  typeof Object.is === 'function' ? Object.is : is;

export default objectIs;

Now the question you may have is where are we going to use this? Well, there is another function that uses this method in React called shallowEqual. The result from this function is what causes React to rerender. Let's say you pass a name prop to a component with value=Jose and then later on change the value to Joseph React compares these values using the shallowEqual function and if it returns false, react rerenders.

I am going to paste the code for this function as it is from React source code and go through it. Also note our objectIs function is imported as just is.

/**
 * Copyright (c) Facebook, Inc. and its affiliates.
 *
 * This source code is licensed under the MIT license found in the
 * LICENSE file in the root directory of this source tree.
 *
 * @flow
 */

import is from './objectIs';
import hasOwnProperty from './hasOwnProperty';

/**
 * Performs equality by iterating through keys on an object and returning false
 * when any key has values which are not strictly equal between the arguments.
 * Returns true when the values of all keys are strictly equal.
 */
function shallowEqual(objA: mixed, objB: mixed): boolean {
  if (is(objA, objB)) {
    return true;
  }

  if (
    typeof objA !== 'object' ||
    objA === null ||
    typeof objB !== 'object' ||
    objB === null
  ) {
    return false;
  }

  const keysA = Object.keys(objA);
  const keysB = Object.keys(objB);

  if (keysA.length !== keysB.length) {
    return false;
  }

  // Test for A's keys different from B.
  for (let i = 0; i < keysA.length; i++) {
    const currentKey = keysA[i];
    if (
      !hasOwnProperty.call(objB, currentKey) ||
      !is(objA[currentKey], objB[currentKey])
    ) {
      return false;
    }
  }

  return true;
}

export default shallowEqual;

This function accepts 2 arguments and if we pass them to objectIs and they return true, the function immediately returns with true. This is covered by the first if statement.

If any of the objects we pass is null, or its type is not equal to object the function returns with false. That's covered by the second if statement.

If the objects we pass have different number of properties, we also return false that means they are not equal. That's covered by the third if statement which checks the length of keys to see if they are not equal.

Now the last part is to check if the keys are the same for both objects. We use the Object.hasOwnProperty for that for each key. objA and objB may have the same number of keys and Object.hasOwnProperty makes sure that even if the number of keys is the same the keys also have the same names.

Please Note this is a shallow comparison so we don't compare the values in the objects so if you mutate an object and pass it React will not be able to see that change.

Thanks for reading, stay tuned for more articles about these small react functions.

Forem: Joseph Mukorivo

I Got Tired of Jira. So I Built an Agentic Project Management Tool — and Open-Sourced It

What I mean by “agentic project management”

What is FortyOne today

What’s open source

Frontend overview (fortyone.app)

Monorepo structure (high level)

Backend overview (api.fortyone.app)

Backend architecture (the important part)

A few backend highlights

Local development

Frontend: run locally

Backend: run locally

Migrations

Seeding

Why I open sourced it

About the license

What I’d love help with

Try it, star it, break it

[Boost]

Open Sourcing FortyOne: Agentic Project Management With an AI Teammate

Joseph Mukorivo ・ Jan 8

Can One Person Really Build a Complex System from Scratch?

Introduction

The Frontend

Monorepo Setup with Turborepo

Shell and Layouts with Next.js

Data Fetching and Optimistic Updates with React Query

Real Time Synchronization with Server Sent Events

Authentication Across Subdomains with NextAuth.js

AI Assistant Maya with the Vercel AI SDK

Frontend Analytics with PostHog

The Backend

Backend Architecture in Go

Background Jobs with Asynq

Emails and Onboarding with Brevo

CI/CD and Infrastructure

GitHub Integration

Closing Thoughts

Building Complexus: How I am Building a Modern Enterprise Frontend Architecture with Next.js and Turborepo

Introduction: Crafting a Modern Project Management System

The Foundation: Turborepo Monorepo for Structure and Speed

Complexus Monorepo Structure

Streamlining Development: Shared Packages (packages/)

Structuring Logic: Domain-Driven Modules in apps/projects

Advantages of Feature-Based Structure

Seamless Access: Shared Authentication Across Subdomains

Documenting with Nextra

Conclusion: Building for Complexity and Scale

Deep Dive into Go Reflection: Crafting a Dynamic Open Source Config Package

What is reflection anyway🤔?

Type Assertion and Reflection:

Working with Interface Values

Config Package structure.

Key Functions:

Usage Example:

Code walkthrough

The custom error types

The Parse Function

Handling Nested Structs

Extracting Field Metadata from Struct Tags

Assigning Values Based on Type

MustParse: A Panicking Alternative

Adding Tests for Robustness

Conclusion

How I approach and structure Enterprise frontend applications after 4 years of using Next.js

Introduction

Guiding Principles of Effective Enterprise Frontend Architecture

Modularity and Componentization

Separation of Concerns (SoC)

Scalability by Design

Maintainability and Code Quality

Accessibility by Default

Performance-Oriented Development

Security First

Internationalization (i18n) and Localization (l10n)

Folder and file structure

TypeScript coding conventions

All types must be defined with type alias

Avoid using multiple arguments

Streamlining Development: Shared Packages (`packages/`)

Structuring Logic: Domain-Driven Modules in `apps/projects`