DEV Community: orjinameh

How I Built a Real-Time Industrial PLC Monitoring Dashboard with Next.js and Modbus TCP(SCADA project)

orjinameh — Mon, 02 Mar 2026 02:21:57 +0000

How I Built a Real-Time Industrial PLC Monitoring Dashboard with Next.js and Modbus TCP

As a Mechatronics Engineering student with 4 years of web development experience, I've always wanted to build something that combines both worlds. This project is exactly that — a real-time industrial SCADA-like dashboard that reads data from a CODESYS virtual PLC via Modbus TCP and displays it on a Next.js web interface.

This is not a tutorial about blinking LEDs. This is how real industrial systems work.

What I Built

A full-stack industrial monitoring system with:

CODESYS virtual PLC running a simulated conveyor belt process
Modbus TCP communication between PLC and server
Node.js + WebSockets for real-time data streaming
Next.js dashboard with live charts and alarm management
MongoDB for historical data storage
JWT authentication to protect the dashboard

Why This Project Matters

In real factories, power plants and oil refineries, operators monitor industrial processes through SCADA systems (Supervisory Control and Data Acquisition). These systems read data from PLCs (Programmable Logic Controllers) via industrial protocols like Modbus TCP, OPC-UA or Profinet.

Most web developers have never heard of Modbus. Most Mechatronics engineers don't know React. This project sits exactly at that intersection.

System Architecture

CODESYS Virtual PLC
        ↓
Modbus TCP (port 502)
        ↓
Node.js Server
   ├── WebSocket Server (live data)
   ├── REST API (historical data)
   └── MongoDB (storage)
        ↓
Next.js Dashboard
   ├── Live status cards
   ├── Real-time charts (Recharts)
   ├── Alarm management
   └── Historical data page

What is Modbus TCP?

Modbus is an industrial communication protocol developed in 1979. It's still the most widely used protocol in industrial automation today.

Modbus TCP works over standard Ethernet using a simple request/response model:

Node.js (Master) → "Read registers 0-3" → PLC (Slave)
PLC (Slave) → "Values: 254, 120, 50, 142" → Node.js (Master)

Each register holds one 16-bit integer value. PLCs store sensor readings as integers because they don't support decimals natively:

Temperature 25.4°C → stored as 254 → divide by 10 → 25.4
Pressure 1.20 bar → stored as 120 → divide by 100 → 1.20

Setting Up CODESYS

CODESYS is a free industrial PLC programming environment used by Wago, Beckhoff, Phoenix Contact and many other PLC manufacturers. The same code runs on virtual and real PLCs.

Project structure:

Device (CODESYS Control Win V3 x64)
  └── Ethernet Adapter
        └── Modbus TCP Server (port 502)
  └── Application
        └── PLC_PRG (Structured Text)

PLC variables:

VAR
  Temperature : UINT := 254;  (* 25.4°C *)
  Pressure    : UINT := 120;  (* 1.20 bar *)
  BeltSpeed   : UINT := 50;   (* 50 rpm *)
  ItemCount   : UINT := 0;    (* items produced *)
  Counter     : UINT := 0;
END_VAR

Ladder logic to simulate a dynamic process:

// Simulate temperature rising and falling
Counter := Counter + 1;

IF Counter >= 100 THEN
  Counter := 0;
END_IF

Temperature := 240 + Counter;

// Pressure responds to temperature
IF Temperature > 270 THEN
  Pressure := 150;
ELSIF Temperature > 250 THEN
  Pressure := 130;
ELSE
  Pressure := 110;
END_IF

// Belt speed fluctuates
IF Counter MOD 20 = 0 THEN
  BeltSpeed := 40 + (Counter / 10);
END_IF

// Item count increases
IF Counter MOD 10 = 0 THEN
  ItemCount := ItemCount + 1;
END_IF

The variables are mapped to Modbus Input Registers via the I/O mapping table so our Node.js server can read them.

Node.js Server

Reading PLC data via Modbus TCP:

const ModbusRTU = require('modbus-serial')

const client = new ModbusRTU()

const connectModbus = async () => {
  await client.connectTCP('127.0.0.1', { port: 502 })
  client.setID(1)
  console.log('Modbus connected!')
}

const readPLCData = async () => {
  const registers = await client.readInputRegisters(0, 4)

  const data = {
    temperature: registers.data[0] / 10,  // 254 → 25.4°C
    pressure: registers.data[1] / 100,    // 120 → 1.20 bar
    beltSpeed: registers.data[2],         // 50 rpm
    itemCount: registers.data[3],         // 142 items
    alarms: getAlarms(registers.data),
    timestamp: new Date()
  }

  broadcast(data)           // send to dashboard via WebSocket
  await saveToDB(data)      // store in MongoDB
}

// Read every second
setInterval(readPLCData, 1000)

WebSocket broadcaster:

const broadcast = (data) => {
  const message = JSON.stringify(data)

  wss.clients.forEach((client) => {
    if (client.readyState === WebSocket.OPEN) {
      client.send(message)
    }
  })
}

Alarm detection:

const getAlarms = (data) => {
  const alarms = []

  if (data[0] / 10 > 80)  alarms.push('HIGH_TEMPERATURE')
  if (data[1] / 100 < 0.5) alarms.push('LOW_PRESSURE')
  if (data[2] === 0)        alarms.push('BELT_STOPPED')

  return alarms
}

Next.js Dashboard

Connecting to WebSocket:

export const connectWebSocket = (
  onData: (data: PlcData) => void,
  onConnect: () => void,
  onDisconnect: () => void
) => {
  const socket = new WebSocket('ws://localhost:4000')

  socket.onmessage = (event) => {
    const data: PlcData = JSON.parse(event.data)
    onData(data)
  }

  socket.onclose = () => {
    onDisconnect()
    // Auto reconnect after 3 seconds
    setTimeout(() => connectWebSocket(onData, onConnect, onDisconnect), 3000)
  }
}

Keeping last 60 seconds of data for charts:

const MAX_DATA_POINTS = 60

setTempHistory((prev) => [
  ...prev.slice(-MAX_DATA_POINTS),
  { time, value: data.temperature }
])

Status card with dynamic color:

const getStatus = (value, warnThreshold, dangerThreshold) => {
  if (value >= dangerThreshold) return 'danger'   // red
  if (value >= warnThreshold) return 'warning'    // yellow
  return 'normal'                                  // green
}

JWT Authentication

To protect the dashboard, I added JWT authentication:

// Login endpoint
const login = async (req, res) => {
  const user = await User.findOne({ username: req.body.username })
  const isValid = await user.comparePassword(req.body.password)

  if (!isValid) return res.status(401).json({ error: 'Invalid credentials' })

  const token = jwt.sign(
    { id: user._id, username: user.username, role: user.role },
    JWT_SECRET,
    { expiresIn: '24h' }
  )

  res.json({ token, username: user.username, role: user.role })
}

// Protect routes
const protect = (req, res, next) => {
  const token = req.headers.authorization?.split(' ')[1]
  const decoded = jwt.verify(token, JWT_SECRET)
  req.user = decoded
  next()
}

User roles: admin, operator, viewer — ready for role-based access control.

Key Lessons

1. Modbus TCP uses Input Registers for reading, Holding Registers for writing

I initially mapped variables to Holding Registers and got all zeros. The fix was using Input Registers for PLC → external device communication.

2. Read state before dispatching in real-time systems

When detecting transitions (alarm on/off), always compare old state vs new state before updating.

3. Industrial protocols are simpler than you think

Modbus is just: connect → set ID → read registers → disconnect. The modbus-serial npm package handles everything.

4. WebSockets beat REST for real-time data

Polling a REST endpoint every second creates unnecessary overhead. WebSockets maintain a persistent connection and push data only when it changes.

What's Next

Connect to a real PLC (Automation Direct Click Plus ~$100)
Add OPC-UA support (more modern than Modbus)
Add role-based access control
Deploy to a VPS with Docker

Tech Stack Summary

Layer	Technology
PLC Simulation	CODESYS Control Win V3
Protocol	Modbus TCP
Backend	Node.js + Express
Real-time	WebSockets (ws)
Database	MongoDB + Mongoose
Auth	JWT + bcryptjs
Frontend	Next.js + TypeScript
Charts	Recharts
Styling	Tailwind CSS

How I Added PWA Support to a Next.js App

orjinameh — Fri, 27 Feb 2026 16:59:11 +0000

While contributing to Accuguide — an open source platform that helps people discover accessible places and services — I implemented Progressive Web App (PWA) support so users can install it on their phone like a native app.

In this article I'll walk through exactly what a PWA needs, how Next.js handles it, and every file I created or modified.

What is a PWA?

A Progressive Web App is a website that can be installed on a device and behaves like a native app. When installed:

It gets its own icon on the home screen
It opens without browser UI (no address bar)
It can work offline
It loads faster on repeat visits

What a PWA Needs

Three things are required:

manifest.json — tells the browser the app's name, icons, and colors
Service Worker — handles caching and offline support
Meta tags — links the manifest and configures mobile display

Step 1: Create `public/manifest.json`

This file describes your app to the browser:

{
  "name": "Accuguide - Discover accessibility",
  "short_name": "Accuguide",
  "description": "Accuguide helps you discover accessible places and services near you.",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#ffffff",
  "orientation": "portrait",
  "icons": [
    {
      "src": "/images/logo.png",
      "sizes": "any",
      "type": "image/png",
      "purpose": "any maskable"
    }
  ]
}

Key fields explained:

Field	Purpose
`name`	Full app name shown on splash screen
`short_name`	Name shown under home screen icon
`start_url`	Page to open when app is launched
`display: standalone`	Hides browser UI when installed
`background_color`	Splash screen background
`theme_color`	Status bar color on mobile
`icons`	App icon for home screen

Step 2: Create `public/sw.js` (Service Worker)

The service worker runs in the background and handles caching:

const CACHE_NAME = 'accuguide-v1';

const STATIC_ASSETS = [
  '/',
  '/search',
  '/info/about',
  '/info/donate',
  '/info/volunteer',
  '/help/faq',
  '/help/resources',
];

// Install: cache static assets
self.addEventListener('install', (event) => {
  event.waitUntil(
    caches.open(CACHE_NAME).then((cache) => {
      return cache.addAll(STATIC_ASSETS);
    })
  );
  self.skipWaiting();
});

// Activate: clean up old caches
self.addEventListener('activate', (event) => {
  event.waitUntil(
    caches.keys().then((cacheNames) => {
      return Promise.all(
        cacheNames
          .filter((name) => name !== CACHE_NAME)
          .map((name) => caches.delete(name))
      );
    })
  );
  self.clients.claim();
});

// Fetch: network first, fallback to cache
self.addEventListener('fetch', (event) => {
  event.respondWith(
    fetch(event.request)
      .then((response) => {
        const responseClone = response.clone();
        caches.open(CACHE_NAME).then((cache) => {
          cache.put(event.request, responseClone);
        });
        return response;
      })
      .catch(() => {
        return caches.match(event.request);
      })
  );
});

Three lifecycle events:

install — runs once when SW is first registered. Caches all static pages.
activate — runs after install. Deletes old caches from previous versions.
fetch — intercepts every network request. Tries network first, falls back to cache if offline.

Why network first?
Since Accuguide shows real-time data (places, reviews), we always want fresh data when online. Cache is only a fallback when the user is offline.

Step 3: Update `src/app/layout.tsx`

Next.js handles meta tags through the metadata export. Add these fields:

export const metadata: Metadata = {
  // ... existing metadata ...
  manifest: '/manifest.json',
  appleWebApp: {
    capable: true,
    statusBarStyle: 'default',
    title: 'Accuguide',
  },
  formatDetection: {
    telephone: false,
  },
}

What each field does:

manifest — links the manifest.json file
appleWebApp.capable — enables "Add to Home Screen" on iOS
appleWebApp.statusBarStyle — controls iOS status bar appearance
formatDetection.telephone: false — prevents iOS from auto-linking phone numbers

Then register the service worker at the bottom of the layout:

<Script
  id="register-sw"
  strategy="afterInteractive"
  dangerouslySetInnerHTML={{
    __html: `
      if ('serviceWorker' in navigator) {
        window.addEventListener('load', function() {
          navigator.serviceWorker.register('/sw.js');
        });
      }
    `,
  }}
/>

Why afterInteractive?
This tells Next.js to load the script after the page is interactive — so it doesn't block the initial render.

Why check 'serviceWorker' in navigator?
Not all browsers support service workers. This check prevents errors on unsupported browsers.

How to Test It

Open Chrome DevTools → Application tab → Manifest to verify your manifest is loaded correctly.

You should see:

App name and short name
Icons
Display mode: standalone

Under Service Workers you should see your sw.js registered and running.

On mobile, Chrome will show an "Add to Home Screen" banner automatically!

The Key Lesson

PWA support in Next.js needs just 3 things:

public/manifest.json     ← describes the app
public/sw.js             ← handles caching and offline
src/app/layout.tsx       ← links manifest + registers SW

No external libraries needed! Next.js + native browser APIs are enough.

Summary

File	Change
`public/manifest.json`	Created — app metadata for browser
`public/sw.js`	Created — service worker for caching
`src/app/layout.tsx`	Updated — manifest link + SW registration

If you found this helpful, check out the Accuguide repo and my GitHub profile.

Have questions or spotted something I missed? Drop a comment below!

How I Added Screenshare Sound Notifications to an Open Source Chat App

orjinameh — Fri, 27 Feb 2026 16:46:29 +0000

While contributing to Sharkord — a self-hosted, Discord-like communication platform built with TypeScript — I implemented a feature where a sound plays when a remote user starts or stops screensharing in a voice channel.

In this article I'll walk through how I explored the codebase, matched the existing sound patterns, and wired everything together.

The Problem

Sharkord already had sounds for many voice channel events:

User joins/leaves a voice channel
Muting/unmuting mic
Enabling/disabling webcam
Own user starting/stopping screenshare

But there was no sound when a remote user (someone else) started or stopped screensharing. You'd have no audio feedback that someone else just started sharing their screen.

Exploring the Codebase

Before writing any code I searched for how existing sounds worked. I found the sound system in:

apps/client/src/features/server/sounds/actions.ts

The project uses the Web Audio API — no external sound files needed! All sounds are generated programmatically using oscillators.

Here's the pattern every sound follows:

const createOsc = (type: OscillatorType, freq: number) => {
  const osc = audioCtx.createOscillator()
  osc.type = type
  osc.frequency.setValueAtTime(freq, now())
  return osc
}

const createGain = (value = 1) => {
  const gain = audioCtx.createGain()
  gain.gain.setValueAtTime(value * SOUNDS_VOLUME, now())
  return gain
}

Every sound creates oscillators, connects them to gain nodes, and fades them out using exponentialRampToValueAtTime.

The Existing Screenshare Sounds

The own user screenshare sounds already existed:

// STARTED_SCREENSHARE — richer activation sequence
const sfxOwnUserStartedScreenshare = () => {
  const pulses = [
    { freq: 600, delay: 0 },
    { freq: 800, delay: 0.06 },
    { freq: 1000, delay: 0.12 }
  ]

  pulses.forEach(({ freq, delay }) => {
    const t = now() + delay
    const osc = createOsc('sine', freq)
    const gain = createGain(0.08)

    gain.gain.exponentialRampToValueAtTime(0.0001, t + 0.1)

    osc.connect(gain).connect(audioCtx.destination)
    osc.start(t)
    osc.stop(t + 0.1)
  })
}

The maintainer specifically asked that the new sound be consistent with existing ones. So I based the remote user sounds on the own user versions but made them slightly softer (gain 0.06 instead of 0.08).

What I Changed

1. Added new SoundType entries (`types.ts`)

export enum SoundType {
  // ... existing entries ...
  REMOTE_USER_STARTED_SCREENSHARE = 'remote_user_started_screenshare',
  REMOTE_USER_STOPPED_SCREENSHARE = 'remote_user_stopped_screenshare'
}

2. Added new sound functions (`sounds/actions.ts`)

// REMOTE STARTED SCREENSHARE — similar to own user but slightly softer
const sfxRemoteUserStartedScreenshare = () => {
  const pulses = [
    { freq: 600, delay: 0 },
    { freq: 800, delay: 0.06 },
    { freq: 1000, delay: 0.12 }
  ]

  pulses.forEach(({ freq, delay }) => {
    const t = now() + delay
    const osc = createOsc('sine', freq)
    const gain = createGain(0.06) // slightly softer than own user (0.08)

    gain.gain.exponentialRampToValueAtTime(0.0001, t + 0.1)

    osc.connect(gain).connect(audioCtx.destination)
    osc.start(t)
    osc.stop(t + 0.1)
  })

  const osc2 = createOsc('triangle', 1200)
  const gain2 = createGain(0.02)

  gain2.gain.exponentialRampToValueAtTime(0.0001, now() + 0.2)

  osc2.connect(gain2).connect(audioCtx.destination)
  osc2.start(now() + 0.08)
  osc2.stop(now() + 0.22)
}

Added the cases to the playSound switch:

case SoundType.REMOTE_USER_STARTED_SCREENSHARE:
  return sfxRemoteUserStartedScreenshare()
case SoundType.REMOTE_USER_STOPPED_SCREENSHARE:
  return sfxRemoteUserStoppedScreenshare()

3. Triggered the sound in voice actions (`voice/actions.ts`)

This was the trickiest part. I needed to detect when a remote user's sharingScreen state changed from false to true (or true to false).

The key was reading the current state before dispatching the update:

export const updateVoiceUserState = (
  userId: number,
  channelId: number,
  newState: Partial
): void => {
  const state = store.getState()
  const ownUserId = ownUserIdSelector(state)
  const currentChannelId = currentVoiceChannelIdSelector(state)

  if (userId !== ownUserId && channelId === currentChannelId) {
    const currentUserState = state.server.voiceMap[channelId]?.users[userId]

    if (newState.sharingScreen === true && !currentUserState?.sharingScreen) {
      playSound(SoundType.REMOTE_USER_STARTED_SCREENSHARE)
    } else if (newState.sharingScreen === false && currentUserState?.sharingScreen) {
      playSound(SoundType.REMOTE_USER_STOPPED_SCREENSHARE)
    }
  }

  store.dispatch(
    serverSliceActions.updateVoiceUserState({ userId, channelId, newState })
  )
}

Why read state before dispatching?

If I dispatched first and then checked, the state would already be updated and I couldn't compare old vs new. By reading state before dispatching I can compare:

currentUserState.sharingScreen — what it was
newState.sharingScreen — what it's becoming

This gives me a clean transition detection.

The Key Lesson

Read state before dispatching when you need to detect transitions.

This pattern is useful whenever you need to:

Play a sound when something changes
Show a notification when a value crosses a threshold
Log when a state transitions from one value to another

// ✅ Read current state BEFORE dispatch
const currentState = store.getState()
const oldValue = currentState.something.value

if (newValue === true && !oldValue) {
  // transitioning from false → true
  doSomething()
}

store.dispatch(updateSomething(newValue))

Summary

File	Change
`types.ts`	Added 2 new `SoundType` entries
`sounds/actions.ts`	Added 2 new sound functions + switch cases
`voice/actions.ts`	Added transition detection logic

If you found this helpful, check out the Sharkord repo and my GitHub profile.

Have questions or spotted something I missed? Drop a comment below!

How I Fixed a Geolocation Permission Bug in a Next.js App

orjinameh — Fri, 27 Feb 2026 16:39:24 +0000

While contributing to Accuguide — an open source platform that helps people discover accessible places and services — I came across an annoying bug where the browser was asking for location permission on every single page load, not just when it was actually needed.

In this article I'll walk you through what caused it, how I tracked it down, and how I fixed it.

The Problem

When you visit any page on Accuguide, the browser would immediately pop up:

"accuguide.org wants to know your location"

This happened even on pages like /info/about or /legal/privacy where location data is completely irrelevant. It was bad UX and also hurt the site's Lighthouse/PageSpeed score under the "Avoids requesting permissions on page load" audit.

The expected behavior was simple: only ask for location permission on the /search page, and only when the user has actually typed a search query.

Finding the Bug

The location logic lived in a React context called LocationProvider in app/contexts/location-context.tsx.

Inside it was this useEffect:

// ❌ The problem
useEffect(() => {
  requestLocationPermission()
}, [])

This runs on every page because LocationProvider was wrapped around the entire app in the root layout. The empty dependency array [] means it fires once on mount — but since it's in the root layout, "mount" happens on every page.

Understanding the Fix

The fix had two parts:

Part 1: Remove the auto-trigger from LocationProvider

Remove the useEffect that was automatically requesting location on mount:

// ✅ Remove this entirely from LocationProvider
useEffect(() => {
  requestLocationPermission()
}, [])

Now LocationProvider no longer automatically asks for location. It just provides the context — location must be requested explicitly.

Part 2: Request location only on the search page with a query

In app/search/page.tsx, add logic to request location only when:

The user is on the search page
There is an active search query

const searchParams = useSearchParams()
const query = searchParams.get('q')
const { requestLocationPermission, location } = useLocation()

useEffect(() => {
  if (query && !location) {
    requestLocationPermission()
  }
}, [query])

Breaking this down:

query — the search term from the URL (?q=coffee shops)
!location — only request if we don't already have location
[query] — only re-run when the query changes

Why This Matters

Before the fix:

❌ Location permission prompt appears on every page
❌ Lighthouse flags "Avoids requesting permissions on page load"
❌ Users get confused and deny permission unnecessarily
❌ Browser may block future permission requests after repeated denials

After the fix:

✅ Location permission only requested on /search page
✅ Only triggered when there's an active search query
✅ Lighthouse audit passes
✅ Users understand WHY location is needed (they're searching!)

The Key Lesson

Context providers run on every page. If you put side effects like requestLocationPermission() inside a provider that wraps your whole app, it will run everywhere.

Always ask: "Where does this actually need to happen?" Then put the logic there — not in a global provider.

// ❌ Don't do this in a global provider
useEffect(() => {
  doSomethingThatShouldOnlyHappenInOnePlace()
}, [])

// ✅ Do this in the specific component/page that needs it
useEffect(() => {
  if (conditionIsRight) {
    doSomethingThatShouldOnlyHappenInOnePlace()
  }
}, [dependency])

Real World Impact

This is a common mistake in React apps. I've seen it with:

Analytics tracking firing on pages it shouldn't
Cookie consent popups appearing multiple times
Auth checks running unnecessarily on public pages

The pattern is always the same: a side effect placed too high in the component tree.

Summary

	Before	After
Location prompt	Every page	Search page only
Trigger condition	On mount	When query exists
Lighthouse audit	❌ Fails	✅ Passes
User experience	Confusing	Intuitive

If you found this helpful, check out the Accuguide repo and my GitHub profile.

Have questions or spotted something I missed? Drop a comment below!

How I Fixed PageSpeed Insights Accessibility Issues in a Next.js App

orjinameh — Thu, 26 Feb 2026 03:03:11 +0000

Recently, I worked on fixing accessibility issues flagged by PageSpeed Insights across 13 pages of a production Next.js application called Accuguide — a platform that helps people discover accessible places and services.

In this article, I'll walk through the exact issues I found and how I fixed them. These are common mistakes that show up in many Next.js apps, so hopefully this saves you some debugging time.

The Problems PageSpeed Found

Running PageSpeed Insights on each page revealed 5 main categories of issues:

Low contrast text
Links relying on color alone to be distinguishable
Invalid <dl> element structure
Missing <main> landmark
Heading elements skipping levels

Let's go through each one.

1. Low Contrast Text

PageSpeed flagged several elements with insufficient contrast between text and background colors.

The culprit: A global .secondary-text CSS class using text-slate-500 which doesn't meet WCAG AA contrast requirements on a light background.

/* ❌ Before */
.secondary-text {
  @apply text-slate-500 dark:text-slate-400;
}

/* ✅ After */
.secondary-text {
  @apply text-slate-700 dark:text-slate-300;
}

The same issue appeared in footer navigation links which were using text-slate-500:

/* ❌ Before */
className="py-2 font-semibold text-slate-500 text-sm"

/* ✅ After */
className="py-2 font-semibold text-slate-700 text-sm dark:text-slate-300"

Also fixed amber and green status messages in a location component:

/* ❌ Before */
Location access denied.
Showing results near you

/* ✅ After */
Location access denied.
Showing results near you

Rule of thumb: Always check contrast ratios using tools like WebAIM Contrast Checker. Aim for at least 4.5:1 for normal text.

2. Links Relying on Color Alone

PageSpeed flagged a "Netlify" link in the footer that was only distinguishable by its blue color — no underline, no other visual indicator.

/* ❌ Before */

  Netlify

/* ✅ After */

  Netlify

I also added a global underline to all anchor tags in the global CSS to prevent this across the entire app:

a {
  @apply text-blue-600 hover:text-blue-500 dark:text-blue-400 dark:hover:text-blue-300 underline;
}

Why it matters: Users with color blindness or low vision cannot distinguish links from regular text if color is the only differentiator.

3. Invalid `<dl>` Element Structure

PageSpeed flagged this error:

<dl>'s do not contain only properly-ordered <dt> and <dd> groups

The app had a stats section using a <dl> element but the StatCard component inside it was using <div> and <p> tags instead of proper <dt> and <dd> tags.

/* ❌ Before */
export default function StatCard({ name, value, icon: Icon, color }) {
  return (





      {name}

  )
}

/* ✅ After */
export default function StatCard({ name, value, icon: Icon, color }) {
  return (





      {name}

  )
}

Two things changed:

<div> → <dd> for the value
<p> → <dt> for the label
Added aria-hidden="true" to the decorative icon

4. Missing `<main>` Landmark

PageSpeed flagged:

Document does not have a main landmark

Screen readers use landmark elements like <main>, <nav>, and <footer> to help users navigate pages efficiently. The app was missing a <main> wrapper around page content.

The fix was simple — add <main> in the root layout:

/* ❌ Before */

  {children}


/* ✅ After */


    {children}

One change, fixes every single page in the app at once.

5. Heading Elements Skipping Levels

PageSpeed flagged that footer section headings were <h3> elements appearing before any <h2> on several pages — skipping a heading level.

/* ❌ Before */
function FooterLinkList({ title, items }) {
  return (

      {title}
      ...

  )
}

/* ✅ After */
function FooterLinkList({ title, items }) {
  return (

      {title}
      ...

  )
}

Why it matters: Screen readers use heading levels to build a table of contents for the page. Skipping levels (h1 → h3) breaks the logical structure and confuses users.

Results

After these fixes, the accessibility score on PageSpeed Insights improved significantly across all 13 pages. The fixes were:

Globally applied (footer, layout, global CSS) so they fixed every page at once
Minimal code changes with maximum impact
All following WCAG AA guidelines

Key Takeaways

Run PageSpeed on every page — issues can vary page by page
Fix global components first — footer, header, and layout fixes apply everywhere
text-slate-500 is usually too light — bump to text-slate-700 for body text
Always add a <main> landmark in your root layout
Use <dt> and <dd> correctly inside <dl> elements
Don't rely on color alone to distinguish links — always add underline

If you found this helpful, check out the Accuguide repo and my GitHub profile.

Have questions or spotted something I missed? Drop a comment below!

DEV Community: orjinameh

How I Built a Real-Time Industrial PLC Monitoring Dashboard with Next.js and Modbus TCP(SCADA project)

How I Built a Real-Time Industrial PLC Monitoring Dashboard with Next.js and Modbus TCP

What I Built

Why This Project Matters

System Architecture

What is Modbus TCP?

Setting Up CODESYS

Node.js Server

Next.js Dashboard

JWT Authentication

Key Lessons

What's Next

Tech Stack Summary

Links

How I Added PWA Support to a Next.js App

What is a PWA?

What a PWA Needs

Step 1: Create public/manifest.json

Step 2: Create public/sw.js (Service Worker)

Step 3: Update src/app/layout.tsx

How to Test It

The Key Lesson

Summary

How I Added Screenshare Sound Notifications to an Open Source Chat App

The Problem

Exploring the Codebase

The Existing Screenshare Sounds

What I Changed

1. Added new SoundType entries (types.ts)

2. Added new sound functions (sounds/actions.ts)

3. Triggered the sound in voice actions (voice/actions.ts)

The Key Lesson

Summary

How I Fixed a Geolocation Permission Bug in a Next.js App

The Problem

Finding the Bug

Understanding the Fix

Part 1: Remove the auto-trigger from LocationProvider

Part 2: Request location only on the search page with a query

Why This Matters

Before the fix:

After the fix:

The Key Lesson

Real World Impact

Summary

How I Fixed PageSpeed Insights Accessibility Issues in a Next.js App

The Problems PageSpeed Found

1. Low Contrast Text

2. Links Relying on Color Alone

3. Invalid <dl> Element Structure

4. Missing <main> Landmark

5. Heading Elements Skipping Levels

Results

Key Takeaways

Step 1: Create `public/manifest.json`

Step 2: Create `public/sw.js` (Service Worker)

Step 3: Update `src/app/layout.tsx`

1. Added new SoundType entries (`types.ts`)

2. Added new sound functions (`sounds/actions.ts`)

3. Triggered the sound in voice actions (`voice/actions.ts`)

3. Invalid `<dl>` Element Structure

4. Missing `<main>` Landmark