Forem: Abdulwasiu Abdulmuize

🚀 Instant Pages with Speculation Rules: The Secret to Lightning-Fast Web Navigation

Abdulwasiu Abdulmuize — Fri, 05 Sep 2025 06:40:50 +0000

Imagine your website's pages popping up almost instantly—like landing on a teleportation pad instead of a slow-loading dock. That's the vibe the Speculation Rules API brings. The Speculation Rules API is an experimental yet powerful tool designed to prefetch or prerender likely navigations, boosting perceived performance. It's a modern replacement for outdated <link rel="prerender"> and enhances older prefetch methods with richer control and safety.

Let's set sail and explore how this powerful tool delivers smoother browsing with minimal effort.

What is the Speculation Rules API?

At its core, this API lets developers hint to the browser:

"Here are pages the user might visit next—go ahead and fetch them now."

Prefetching fetches just the response body of a future page (no subresources). It saves bandwidth and speeds up navigation—but offers a lighter performance boost.
Prerendering renders and loads everything—subresources, scripts, data—into an invisible cache. When the user navigates, activation is near-instant. But it consumes more memory, CPU, and bandwidth.

The API lets you define these behaviors using JSON rules, either embedded as:

<script type="speculationrules"> tags in HTML, or
External JSON files linked via the Speculation-Rules HTTP header.

👉 MDN emphasizes that these rules supersede older mechanisms and should be preferred where supported.

Key Benefits Over Older Techniques

Feature	Speculation Rules API	`<link rel="prefetch">` / Deprecated `<link rel="prerender">`
Control over resources fetched	✅ Yes (prefetch vs prerender, eagerness)	❌ No differentiated handling
Respects user power-saving modes	✅ Yes	❌ No
Cache isolation per page	✅ Yes (in-memory cache)	❌ No
Cross-site navigation support	✅ Prefetch-only when cookie-less or opt-in	❌ No
Not blocked by Cache-Control	✅ Speculation allowed even if HTTP cache is blocked	❌ Often blocked

Implementation Patterns

1. Embedding Rules in HTML

<script type="speculationrules">
{
  "prerender": [{
    "where": { "selector_matches": ".prerender" },
    "eagerness": "eager"
  }],
  "prefetch": [{
    "where": { "selector_matches": ".prefetch" },
    "eagerness": "moderate"
  }]
}
</script>

This enables dynamic behavior: apply .prefetch or .prerender CSS classes on links to control speculation.

2. Inject via JavaScript

You can conditionally inject rules based on user interactions (e.g., after adding to cart). Great for tag managers or A/B testing.

3. Via HTTP Header

Speculation-Rules: "/speculationrules.json"

Serve a JSON file with application/speculationrules+json type—handy for CDN deployment and easier rollout without modifying HTML.

Rolling It Out: A Guided Strategy

Start with Prefetch
A low-risk, broad-sweep way to gain speed. Great for typical navigations like homepage → article.
Move to Low‑Risk Pre‑render
Use moderate eagerness when the next destination is predictable. Minimize overhead but still improve performance.
Finally, Implement Eager Pre‑renders
With strong data (e.g., top funnels), use eager prerender for 1–2 highly likely navigations. Beware: Chrome caps at ~2–10 concurrent prerenders.

🌱 1. Start with Prefetch (Low-Risk, Low-Cost)

Use prefetching to speed up likely next-page loads, without executing scripts or rendering the DOM.

<!-- Add the "prefetch-next" class to links likely to be clicked soon -->
<a href="/about" class="prefetch-next">About Us</a>

<script type="speculationrules">
{
  "prefetch": [
    {
      "where": {
        "selector_matches": ".prefetch-next"
      },
      "eagerness": "moderate"
    }
  ]
}
</script>

What's happening:

This rule tells the browser: If you see any .prefetch-next link, prefetch the destination page.
eagerness: "moderate" avoids excessive resource use (vs. eager, which starts immediately).

🌿 2. Move to Low-Risk Prerender (Faster, Still Safe)

<!-- Add a "prerender-safe" class to pages that are highly likely and side-effect-free -->
<a href="/product/123" class="prerender-safe">View Product</a>

<script type="speculationrules">
{
  "prerender": [
    {
      "where": {
        "selector_matches": ".prerender-safe"
      },
      "eagerness": "moderate"
    }
  ]
}
</script>

Bonus: Add runtime behavior if prerendered

if (document.prerendering) {
  // Pause analytics or expensive tasks
  document.addEventListener("prerenderingchange", () => {
    startAnalytics(); // Run only after activation
  });
} else {
  startAnalytics(); // Normal page load
}

🌳 3. Implement Eager Prerenders (Predictive & Fastest)

<a href="/signup" class="eager-prerender">Start Free Trial</a>

<script type="speculationrules">
{
  "prerender": [
    {
      "where": {
        "selector_matches": ".eager-prerender"
      },
      "eagerness": "eager"
    }
  ]
}
</script>

Optional: Clear prerender cache on logout or major state change

Clear-Site-Data: "prefetchCache"

Summary Table

Phase	Code Pattern	Risk Level	Performance Boost
Prefetch only	`.prefetch-next` with `prefetch`	✅ Very Low	⚡ Small
Moderate prerender	`.prerender-safe` with `prerender`	⚠️ Medium	⚡⚡ Faster
Eager prerender	`.eager-prerender` with `eager` prerender	❗ Higher	⚡⚡⚡ Fastest

Safety First: Pitfalls to Avoid

Unintended Side‑effects
Avoid speculative fetching on actions like add-to-cart, logouts, OTP triggers. Use the Sec-Purpose header to detect and suppress side effects.
Stale or User‑specific State
Example: prerendered page shows "logged out" view after login. Fix by refreshing state post-activation via:
- Broadcast Channel API to sync across pages.
- WebSocket or fetch() to revalidate data.
Analytics & Ads

Guard analytics/event scripts using document.prerendering. Use prerenderingchange to trigger them only once visible.
Clear Speculative Cache on State Changes

After logout, avoid stale prefetched pages:

  Clear-Site-Data: "prefetchCache"

API Restrictions in Prerender Certain APIs are deferred or no-opped until activation (e.g., notifications, geolocation, full-screen, WebRTC).

Measurement: Did It Work?

Track improvements in LCP, CLS, and INP—but focus on specific paths, not site-wide metrics.

Detect speculation behavior:

console.log(document.prerendering);
console.log(performance.getEntriesByType("navigation")[0]?.activationStart > 0);

Log this to measure speculation efficiency with Real User Monitoring (RUM).

Summary and Final Tips

The Speculation Rules API is a powerful, modern approach to make page transitions nearly instant.

Roll out gradually: prefetch → moderate prerender → eager prerender.
Watch out for:
- Unwanted effects (side-effects on load).
- Stale or conflicting application state.
- Analytics and ad misfires.
- API constraints during prerender.

✅ Always measure, iterate, and adjust based on real user data.

Sample Implementation Snippet

<script type="speculationrules">
{
  "prefetch": [{
    "where": { "selector_matches": ".likely-next" },
    "eagerness": "moderate"
  }],
  "prerender": [{
    "where": { "urls": ["/checkout", "/product-detail"] },
    "eagerness": "eager"
  }]
}
</script>

if (document.prerendering) {
  console.log("Prerendering in background; deferring analytics.");
} else {
  runAnalytics();
}

The Speculation Rules API is one of the most promising ways to enhance perceived performance—and it's already supported in Chromium-based browsers. Now's the time to test, experiment, and share what works. 🚀

Breaking the Monolith: How I Successfully Separated an E-Learning Platform for Better Security and Performance

Abdulwasiu Abdulmuize — Wed, 30 Jul 2025 23:00:00 +0000

The Assignment: Modernizing a Growing Platform

When I joined this project, the challenge was clear: transform a unified Next.js e-learning platform into two specialized applications—one for students and one for administrators—without duplicating code or compromising performance.

The existing platform served both roles from a single codebase. While this “all-in-one” model had served the team well during the early stages, it began to show serious limitations as the platform scaled.

My mission: architect and implement a separation that would enhance security, boost performance, and make the codebase more maintainable for the long run.

The Challenge: When One Size No Longer Fits All

The original architecture followed a typical startup strategy:

“Build fast, ship faster.”

A single Next.js app powered everything—from course browsing to system administration. However, rapid growth exposed several architectural cracks:

📦 Bundle Bloat: The admin dashboard inflated the bundle size for student-facing pages.
🔐 Security Concerns: Admin features coexisted with public student routes—raising exposure risks.
🛠 Development Friction: Student features and admin tools tangled in the same codebase.
🐌 Performance Hits: Shared concerns affected load times and UX.

Clearly, the unified setup was becoming a bottleneck. It was time for a strategic evolution.

The Solution: Separation for Specialization

After thoroughly analyzing the codebase and business needs, I proposed a split:

** Student Portal**: A lean, focused app for learning and discovery.
** Admin Dashboard**: A dedicated app for platform management.

But this wasn’t just about splitting code. It meant building a smart shared component architecture that prevented duplication while giving each app freedom to evolve independently.

The Architecture: Smart Separation with Shared Resources

The new structure followed a modular, maintainable pattern:

platform/
├── student/          # Student-focused Next.js app
├── admin/            # Admin-focused Next.js app  
└── shared/           # Common components & utilities
    ├── components/   # Reusable UI components
    ├── hooks/        # Custom React hooks
    ├── lib/          # API clients & utilities
    ├── providers/    # React context providers
    ├── store/        # Zustand state management
    └── types/        # TypeScript definitions

The shared/ directory became the single source of truth for components, state, and utilities.

Implementation Challenges and Solutions

🧩 Challenge 1: Component Dependencies

Problem: Existing components were mixed—some tightly coupled to student logic, others to admin workflows.

Solution: I introduced a component classification system:

shared/components/ → Universal UI components
student/src/components/ → Student-specific
admin/src/components/ → Admin-specific

🧠 Challenge 2: State Management

Problem: Zustand stores contained both student and admin logic.

Solution: I separated stores by domain:

auth-store.ts → Authentication (shared)
course-store.ts → Course data (shared)
progress-store.ts → Student tracking
certificate-store.ts → Certificate issuance

🔁 Challenge 3: Routing and Auth Logic

Problem: A single routing middleware managed both student and admin paths—hard to debug and scale.

Solution:

Student App: Public pages + protected dashboard
Admin App: Fully protected with role-based access control
Shared Layer: JWT logic + session management

The Results: Measurable Improvements

🔒 Enhanced Security

Reduced Attack Surface: No more admin code in the student app.
Complete Isolation: Admin tools live in their own sandbox.
Improved Access Control: Granular permissions per app.

⚡ Performance Gains

Bundle Size:
- Student: ↓ 33%
- Admin: ↓ 14%
Load Times: ↓ 34%
Build Time: ↓ 38%

💻 Developer Experience

Clearer codebase → Faster onboarding
Focused teams → Fewer conflicts
Isolated bugs → Easier debugging

🚀 Operational Benefits

Independent Deployments
Flexible Hosting
App-Specific Monitoring & Analytics

Impact Metrics: Before vs After

Metric	Before	After	Improvement
Student Bundle Size	2.1MB	1.4MB	33% smaller
Admin Bundle Size	2.1MB	1.8MB	14% smaller
First Load Time	3.2s	2.1s	34% faster
Dev Build Time	45s	28s	38% faster
Security Risk	Mixed	Isolated	Significantly safer

Key Lessons from the Migration

1. 🧱 Architect the Shared Layer First

Upfront investment in a shared library ensured reusability without tight coupling.

2. 📦 Keep Imports Consistent

Relative imports like ../../../shared/components/button enforced clarity and consistency.

3. 👥 Design for Team Autonomy

Each team focused on one domain, boosting domain expertise and velocity.

4. 🧪 Test Thoroughly During Migration

Comprehensive test suites protected against regressions.

Technology Stack That Enabled Success

Next.js 15 + App Router
TypeScript 5
Tailwind CSS + Radix UI
Zustand + TanStack Query
React Hook Form + Zod

Long-Term Benefits (6 Months Later)

🚀 Faster Feature Development
🔐 Stronger Security Posture
🧑‍💻 Higher Team Velocity
👋 Simplified Onboarding

When Should You Consider Platform Separation?

✅ You serve multiple user types
✅ You're seeing bundle bloat
✅ Your security surface is growing
✅ Teams are clashing over shared logic
✅ You need faster deployments and better monitoring

Conclusion: Thoughtful Separation, Strategic Evolution

This was more than a refactor—it was a strategic re-architecture that:

Strengthened platform security
Improved performance
Enhanced developer experience
Future-proofed the product

By separating concerns without sacrificing cohesion, we created a scalable foundation that supports long-term growth and team autonomy.

Sometimes, the smartest way forward is to break things apart intentionally.

Technical Implementation Note:
This was implemented using modern modular patterns in React and Next.js. The shared library ensures consistent UI and logic while enabling each app to evolve independently.

Project Outcome:
This architecture unlocked faster development, stronger security, and higher code quality across the board.

From Sluggish to Lightning Fast: A Database Performance Optimization Journey

Abdulwasiu Abdulmuize — Mon, 28 Jul 2025 05:05:20 +0000

When your application starts slowing down as your data grows, it's time to roll up your sleeves and dive into performance optimization. Today, I want to share a recent success story where I transformed a sluggish course management system into a lightning-fast experience through strategic database optimizations.

The Problem: N+1 Queries and Slow Load Times

Like many applications that grow organically, the course management system I was working on had developed some performance bottlenecks. The most glaring issue was the classic N+1 query problem in the course listing endpoint. For every course displayed, the system was making additional database calls to fetch related data like quizzes and user progress.

Imagine having 100 courses in your system. What should have been a single database query had ballooned into 101 separate queries. The result? Load times that made users tap their fingers impatiently while waiting for the page to render.

The Solution: Strategic Database Optimization

I tackled this performance challenge on three fronts: database indexing, query aggregation, and server initialization improvements.

1. Smart Database Indexing

First, I implemented strategic indexes for the most common query patterns:

Quiz Performance Index for faster course-quiz lookups
User Progress Index for quick progress tracking
Quiz Attempts Index for efficient attempt history retrieval

These indexes act like a book's table of contents, helping the database find exactly what it needs without scanning every record.

2. Aggregation Pipeline

The real game-changer was replacing multiple separate queries with single, optimized aggregation pipelines:

Course Listing (getCourses): I eliminated the N+1 query problem entirely by using MongoDB's aggregation framework to fetch all course data in a single database round trip. What used to require 101 queries now takes just 2.

Individual Course Data (getCourse): Instead of making separate calls for course details and quiz information, I now use a single aggregation query with $lookup operations to join related data efficiently.

Course Progress (getCourseWithProgress): The most complex optimization combined course data, quiz information, user progress, and quiz attempts into one comprehensive query, reducing 4 separate database calls to just 1.

3. Automatic Index Creation

I enhanced the server startup process to automatically create all necessary indexes when the application boots up. This ensures optimal performance from day one, with graceful error handling if index creation encounters any issues.

The Results: Dramatic Performance Improvements

The numbers speak for themselves:

Endpoint	Before	After	Performance Gain
Course Listing	1 + N queries	1 query	~90% faster
Single Course	2 queries	1 query	~50% faster
Course Progress	4 queries	1 query	~75% faster

For a system with 100 courses, we reduced load times from approximately 500ms to just 50ms – a 90% improvement that users immediately notice.

Bonus Features: Pagination and Scalability

As part of the optimization, I also added built-in pagination support to handle large course catalogs gracefully. The API now returns structured responses with page information, making it easy to implement infinite scroll or traditional pagination in the frontend.

The new aggregation-based approach also means performance actually improves as your dataset grows, thanks to better index utilization and reduced network overhead.

Key Takeaways

Profile Before You Optimize: Understanding where your bottlenecks actually are is crucial before making changes.
Database Indexes Are Your Friend: Strategic indexing can dramatically improve query performance with minimal code changes.
Embrace Aggregation Pipelines: Modern databases like MongoDB offer powerful aggregation frameworks that can replace multiple queries with single, optimized operations.
Maintain Backward Compatibility: All these optimizations were implemented without breaking existing functionality – users got better performance without any API changes.
Think About Scale: Optimizations should improve performance as your data grows, not just solve today's problems.

The Bottom Line

Performance optimization doesn't have to be a complete rewrite. With strategic database improvements, thoughtful query design, and modern database features, you can achieve dramatic performance gains while maintaining code simplicity and backward compatibility.

The best part? Your users will notice the difference immediately, and your application will be ready to handle growth for years to come. Sometimes the most impactful improvements happen behind the scenes, in the queries and indexes that power your application's data layer.

Have you tackled similar performance challenges in your applications? The principles of strategic indexing and query aggregation apply across most database systems and can yield impressive results with relatively modest implementation effort.

The Cleanest Way to Manage React Native Audio State: Zustand + TrackPlayer

Abdulwasiu Abdulmuize — Thu, 10 Jul 2025 23:31:33 +0000

Building a robust media player in React Native often involves managing playback state, track information, and user controls. While react-native-track-player handles the heavy lifting of audio playback, keeping your React Native UI in perfect sync with the player’s internal state can be a challenge. This is where state management libraries like Zustand come in.

In this technical blog post, we'll walk through building a powerful auto-sync system between react-native-track-player and Zustand. By the end, you'll have a useTrackPlayerSync() hook that keeps your app’s UI perfectly aligned with the audio player, making your development process smoother and your user experience seamless.

Why Auto-Sync?

Imagine your user:

Plays a track, then minimizes the app.
Opens the app later – the player UI should reflect the exact state of the background player.
Interacts with native controls (e.g., skip forward from the lock screen) – your UI needs to update instantly.

Without a robust sync mechanism, your UI can fall out of sync, leading to a confusing experience. Our auto-sync system solves this!

🧠 Our Goal: The `useTrackPlayerSync()` Hook

We'll build a reusable hook that:

Subscribes to react-native-track-player events
Updates Zustand store automatically
Handles errors gracefully
Is easy to plug into your app

✅ Step 1: Create Zustand Store

Create a file src/stores/usePlayerStore.ts:

// src/stores/usePlayerStore.ts
import { create } from 'zustand';
import { persist } from 'zustand/middleware';

export interface PlayerState {
  currentTrackId: string | null;
  playbackState: 'none' | 'ready' | 'playing' | 'paused' | 'stopped' | 'buffering';
  currentPosition: number;
  duration: number;
  volume: number;
  muted: boolean;
  shuffle: boolean;
  repeatMode: 'none' | 'single' | 'all';
  pointA: number | null;
  pointB: number | null;
  loopActive: boolean;
  subscriptionsInitialized: boolean;
  error: string | null;

  setCurrentTrack: (id: string | null) => void;
  setPlaybackState: (s: PlayerState['playbackState']) => void;
  setCurrentPosition: (p: number) => void;
  setDuration: (d: number) => void;
  setVolume: (v: number) => void;
  setMuted: (m: boolean) => void;
  setShuffle: (s: boolean) => void;
  setRepeatMode: (r: PlayerState['repeatMode']) => void;
  setPointA: (a: number | null) => void;
  setPointB: (b: number | null) => void;
  setLoopActive: (l: boolean) => void;
  setSubscriptionsInitialized: (v: boolean) => void;
  clearLoopPoints: () => void;
  setError: (error: string | null) => void;
}

export const usePlayerStore = create<PlayerState>()(
  persist(
    (set) => ({
      currentTrackId: null,
      playbackState: 'none',
      currentPosition: 0,
      duration: 0,
      volume: 1,
      muted: false,
      shuffle: false,
      repeatMode: 'none',
      pointA: null,
      pointB: null,
      loopActive: false,
      subscriptionsInitialized: false,
      error: null,

      setCurrentTrack: (id) => set({ currentTrackId: id }),
      setPlaybackState: (s) => set({ playbackState: s }),
      setCurrentPosition: (p) => set({ currentPosition: p }),
      setDuration: (d) => set({ duration: d }),
      setVolume: (v) => set({ volume: v }),
      setMuted: (m) => set({ muted: m }),
      setShuffle: (s) => set({ shuffle: s }),
      setRepeatMode: (r) => set({ repeatMode: r }),
      setPointA: (a) => set({ pointA: a }),
      setPointB: (b) => set({ pointB: b }),
      setLoopActive: (l) => set({ loopActive: l }),
      setSubscriptionsInitialized: (v) => set({ subscriptionsInitialized: v }),
      clearLoopPoints: () => set({ pointA: null, pointB: null, loopActive: false }),
      setError: (e) => set({ error: e }),
    }),
    {
      name: 'player-store',
    }
  )
);

🧩 Step 2: The `useTrackPlayerSync()` Hook

Create src/hooks/useTrackPlayerSync.ts:

import { useEffect } from 'react';
import TrackPlayer, {
  Event,
  State as TrackPlayerState,
  Track,
} from 'react-native-track-player';
import { usePlayerStore, PlayerState } from '../stores/usePlayerStore';

function trackStateToString(state: TrackPlayerState): PlayerState['playbackState'] {
  switch (state) {
    case TrackPlayerState.Playing: return 'playing';
    case TrackPlayerState.Paused: return 'paused';
    case TrackPlayerState.Buffering: return 'buffering';
    case TrackPlayerState.Stopped: return 'stopped';
    case TrackPlayerState.Ready: return 'ready';
    case TrackPlayerState.None: return 'none';
    default:
      console.warn(`Unknown state: ${state}`);
      return 'none';
  }
}

export function useTrackPlayerSync() {
  const {
    setCurrentTrack, setPlaybackState, setCurrentPosition,
    setDuration, setVolume, setSubscriptionsInitialized, setError,
  } = usePlayerStore();

  useEffect(() => {
    const setup = async () => {
      setError(null);
      try {
        const activeTrack: Track | null = await TrackPlayer.getActiveTrack();
        const progress = await TrackPlayer.getProgress();
        const volume = await TrackPlayer.getVolume();
        const playbackState = await TrackPlayer.getPlaybackState();

        setCurrentTrack(activeTrack?.id ?? null);
        setCurrentPosition(progress.position);
        setDuration(progress.duration);
        setVolume(volume);
        setPlaybackState(trackStateToString(playbackState.state));
        setSubscriptionsInitialized(true);
      } catch (error: any) {
        console.error("TrackPlayer setup error:", error);
        setError(`Init error: ${error.message || 'Unknown'}`);
        setSubscriptionsInitialized(false);
      }
    };

    setup();

    const subs = [
      TrackPlayer.addEventListener(Event.PlaybackActiveTrackChanged, (data) => {
        try {
          setCurrentTrack(data.track?.id ?? null);
          setError(null);
        } catch (e: any) {
          setError(`Track change error: ${e.message}`);
        }
      }),
      TrackPlayer.addEventListener(Event.PlaybackState, ({ state }) => {
        try {
          setPlaybackState(trackStateToString(state));
        } catch (e: any) {
          setError(`State error: ${e.message}`);
        }
      }),
      TrackPlayer.addEventListener(Event.PlaybackProgressUpdated, ({ position, duration }) => {
        setCurrentPosition(position);
        setDuration(duration);
      }),
      TrackPlayer.addEventListener(Event.PlaybackError, (err) => {
        setError(`Playback error: ${err.message || err.code}`);
        setPlaybackState('stopped');
      }),
    ];

    return () => {
      subs.forEach((sub) => sub.remove());
      setSubscriptionsInitialized(false);
      setError(null);
    };
  }, [
    setCurrentTrack, setPlaybackState, setCurrentPosition,
    setDuration, setVolume, setSubscriptionsInitialized, setError,
  ]);
}

🚀 Step 3: Use the Hook in App

// App.tsx
import React, { useEffect } from 'react';
import { View, Text, ActivityIndicator, StyleSheet } from 'react-native';
import TrackPlayer from 'react-native-track-player';
import { useTrackPlayerSync } from './src/hooks/useTrackPlayerSync';
import { usePlayerStore } from './src/stores/usePlayerStore';

async function setupTrackPlayer() {
  try {
    await TrackPlayer.setupPlayer();
    await TrackPlayer.updateOptions({
      capabilities: [
        TrackPlayer.Capability.Play,
        TrackPlayer.Capability.Pause,
        TrackPlayer.Capability.SkipToNext,
        TrackPlayer.Capability.SkipToPrevious,
        TrackPlayer.Capability.Stop,
      ],
    });
  } catch (error) {
    console.error('TrackPlayer setup failed:', error);
  }
}

export default function App() {
  useEffect(() => {
    setupTrackPlayer();
  }, []);

  useTrackPlayerSync();
  const { playbackState, currentTrackId, currentPosition, duration, error, subscriptionsInitialized } = usePlayerStore();

  return (
    <View style={styles.container}>
      {error && (
        <View style={styles.errorContainer}>
          <Text style={styles.errorText}>Error: {error}</Text>
        </View>
      )}
      {!subscriptionsInitialized ? (
        <ActivityIndicator size="large" />
      ) : (
        <View>
          <Text>Track: {currentTrackId || 'None'}</Text>
          <Text>State: {playbackState}</Text>
          <Text>Time: {currentPosition.toFixed(1)}s / {duration.toFixed(1)}s</Text>
        </View>
      )}
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, justifyContent: 'center', alignItems: 'center' },
  errorContainer: { backgroundColor: '#fee', padding: 10 },
  errorText: { color: '#900' },
});

🔁 Syncing Volume & Settings from UI

import React, { useEffect } from 'react';
import { Text, View } from 'react-native';
import { usePlayerStore } from '../stores/usePlayerStore';
import TrackPlayer from 'react-native-track-player';

export function PlayerControls() {
  const { volume, muted, repeatMode, setVolume, setMuted, setRepeatMode, setError } = usePlayerStore();

  useEffect(() => {
    const applyVolume = async () => {
      try {
        await TrackPlayer.setVolume(muted ? 0 : volume);
        setError(null);
      } catch (e: any) {
        setError(`Volume error: ${e.message}`);
      }
    };
    applyVolume();
  }, [volume, muted]);

  return (
    <View>
      <Text>Volume: {(volume * 100).toFixed(0)}% {muted ? '(Muted)' : ''}</Text>
      <Text>Repeat Mode: {repeatMode}</Text>
    </View>
  );
}

✅ Benefits Recap

Single source of truth with Zustand
Automatic sync using TrackPlayer events
Modern API support
Error handling baked in
Reusability across apps
Clean and scalable architecture

🎉 Conclusion

By building a useTrackPlayerSync() hook and managing your state with Zustand, your React Native audio player becomes more reliable, resilient, and ready for production.

Happy syncing – and even happier users. 🎧

Building a Robust SQLite Query Builder in TypeScript: Lessons from an Arabic Dictionary App

Abdulwasiu Abdulmuize — Fri, 06 Jun 2025 13:56:34 +0000

As developers, we often find ourselves writing repetitive SQL queries, especially when dealing with client-side databases like SQLite in mobile or desktop applications. While raw SQL offers ultimate control, it can quickly become cumbersome, error-prone, and hard to maintain as your application grows. This is where a well-designed query builder shines.

During the development of my Arabic Roots Dictionary application, I faced this exact challenge. The app required numerous dynamic queries for searching roots, derivatives, and managing dictionary data. Instead of scattering raw SQL strings throughout the codebase, I decided to build a custom SQLite query builder in TypeScript. This journey was incredibly insightful, and I'd love to share the key learnings and the architectural patterns that emerged.

Why a Custom Query Builder?

You might ask, "Why not use an existing ORM or query builder library?" While excellent options exist, a custom solution offered several advantages for my specific needs:

Tailored for SQLite: I could optimize for SQLite's nuances and features without the overhead of a general-purpose SQL library.
Lightweight: Avoided pulling in large dependencies that might impact bundle size or performance, especially crucial for a mobile app.
Type Safety: TypeScript's static analysis provided invaluable type safety for column names, operators, and return types, catching errors early.
Control and Flexibility: Complete control over the generated SQL, which was important for debugging and understanding performance.
Learning Experience: A fantastic opportunity to deepen my understanding of database interactions and software design patterns.

The Core Architecture: Chainable and Type-Safe

The goal was to create a fluent, chainable API that felt natural to write, similar to popular ORMs, while strictly enforcing types. The solution involved a BaseQueryBuilder class and specialized subclasses for SELECT, INSERT, UPDATE, and DELETE operations.

1. Defining the Building Blocks (Types)

First, I defined the essential interfaces for WHERE conditions, JOIN conditions, and ORDER BY clauses. This is where TypeScript truly shines:

// types.ts
export interface WhereCondition {
  column: string;
  operator: '=' | '!=' | '>' | '<' | '>=' | '<=' | 'LIKE' | 'IN' | 'NOT IN' | 'IS NULL' | 'IS NOT NULL';
  value?: any;
}

export interface JoinCondition {
  type: 'INNER' | 'LEFT' | 'RIGHT' | 'FULL OUTER';
  table: string;
  on: string;
}

export interface OrderByCondition {
  column: string;
  direction: 'ASC' | 'DESC';
}

2. The BaseQueryBuilder: Common Functionality

The BaseQueryBuilder acts as the foundation, encapsulating common query components like WHERE, JOIN, ORDER BY, LIMIT, and OFFSET.

export abstract class BaseQueryBuilder {
  protected _table: string = '';
  protected _whereConditions: WhereCondition[] = [];
  protected _joins: JoinCondition[] = [];
  protected _orderBy: OrderByCondition[] = [];
  protected _limit?: number;
  protected _offset?: number;

  // Chainable methods would go here...

  protected buildWhereClause(): { clause: string; params: any[] } { /* ... */ }
  protected buildJoinClause(): string { /* ... */ }
  protected buildOrderByClause(): string { /* ... */ }
  protected buildLimitClause(): string { /* ... */ }

  abstract toSQL(): { query: string; params: any[] };
}

Key Learnings:

Chainable API: return this; in each method enables fluent usage.
Parameterized Queries: Protects against SQL injection and handles SQLite types correctly.
Abstract toSQL(): Enforces concrete builders to define their own SQL generation logic.

3. Specialized Builders

Each concrete query builder extends BaseQueryBuilder and adds its own specific methods and toSQL() logic.

SelectQueryBuilder

export class SelectQueryBuilder extends BaseQueryBuilder {
  private _columns: string[] = ['*'];
  private _distinct: boolean = false;
  private _groupBy: string[] = [];
  private _having: WhereCondition[] = [];

  select(columns: string | string[] = '*'): this { /* ... */ }
  distinct(): this { /* ... */ }
  groupBy(columns: string | string[]): this { /* ... */ }
  having(column: string, operator: WhereCondition['operator'], value?: any): this { /* ... */ }

  toSQL(): { query: string; params: any[] } {
    // Build SELECT query from all clauses
  }
}

UpdateQueryBuilder (with Safety Check)

export class UpdateQueryBuilder extends BaseQueryBuilder {
  private _data: Record<string, any> = {};

  set(columnOrData: string | Record<string, any>, value?: any): this { /* ... */ }

  toSQL(): { query: string; params: any[] } {
    const { clause: whereClause, params: whereParams } = this.buildWhereClause();
    if (!whereClause) {
      throw new Error('WHERE clause is required for UPDATE queries');
    }
    // Build UPDATE statement...
  }
}

4. The QueryBuilder Factory

A static factory class simplifies usage:

export class QueryBuilder {
  static select(columns?: string | string[]): SelectQueryBuilder {
    return new SelectQueryBuilder().select(columns);
  }

  static from(table: string): SelectQueryBuilder {
    return new SelectQueryBuilder().select().from(table);
  }

  // insert(), update(), delete() methods
}

5. Database Executor: Bridging to SQLite

The DatabaseExecutor bridges your query builder to the SQLite engine:

export interface DatabaseInterface {
  execAsync(query: string, params?: any[]): Promise<any>;
  getAllAsync(query: string, params?: any[]): Promise<any[]>;
  getFirstAsync(query: string, params?: any[]): Promise<any>;
  runAsync(query: string, params?: any[]): Promise<{ lastInsertRowId: number; changes: number }>;
}

export class DatabaseExecutor {
  constructor(private db: DatabaseInterface) {}

  async select(builder: SelectQueryBuilder): Promise<any[]> {
    const { query, params } = builder.toSQL();
    return await this.db.getAllAsync(query, params);
  }

  // insert(), update(), delete() methods
}

Integration with the Arabic Dictionary App

Before (Raw SQL)

async searchRootsRaw(query: string): Promise<Root[]> {
  const sql = `SELECT * FROM roots WHERE root_normalized LIKE ? LIMIT 50`;
  return await this.db.getAllAsync(sql, [`%${query.trim()}%`]);
}

After (Using Query Builder)

async searchRootsWithQueryBuilder(query: string, dictionaryFilter?: string | null, limit = 50): Promise<Root[]> {
  this.ensureInitialized();
  if (!query.trim()) return [];

  const normalizedQuery = query.trim();

  let queryBuilder = QueryBuilder
    .select([
      'r.id', 'r.root_display', 'r.root_normalized', 'r.root_no_diacritics',
      'r.total_derivatives_count', 'r.main_derivatives_count', 'r.extracted_derivatives_count',
      'r.dictionary_source', 'r.root_length', 'r.full_text'
    ])
    .from('roots r')
    .where('r.root_normalized', 'LIKE', `%${normalizedQuery}%`)
    .orderBy('r.root_length')
    .orderBy('r.root_display')
    .limit(limit);

  if (dictionaryFilter) {
    queryBuilder = queryBuilder.where('r.dictionary_source', '=', dictionaryFilter);
  }

  return await this.executor!.select(queryBuilder);
}

Benefits

More Readable: Clear intent.
Less Error-Prone: Type-safe and parameterized.
Easier to Modify: Just chain more methods.
Safer: Enforced WHERE clause in destructive queries.

Challenges and Further Considerations

Complex Union Queries: Raw SQL may still be preferable in highly complex scenarios.
Schema Awareness: Integrating a schema definition would increase type safety.
Error Handling: Must be robust in the executor layer.
Extensibility: Consider future support for advanced SQL features.

Conclusion

Building a custom SQLite query builder was a significant learning experience and a valuable addition to my Arabic Roots Dictionary application. It taught me the power of the Builder design pattern, the importance of type safety in database interactions, and how to create a more maintainable and robust data access layer.

While external libraries are often a great choice, sometimes a custom, lightweight solution tailored to your specific needs can offer unparalleled control and a deeper understanding of the underlying mechanisms.

If you're working with client-side databases and finding yourself repeating SQL or struggling with query complexity, I highly recommend considering building your own query builder. It's a rewarding challenge that pays dividends in code quality and developer experience.

Building a Markdown Blog in Next.js with Decap CMS: A Comprehensive Guide

Abdulwasiu Abdulmuize — Sun, 23 Feb 2025 06:20:33 +0000

Introduction

In today’s fast-paced web development environment, having a reliable content management system (CMS) is essential for managing your content efficiently. Decap CMS, formerly known as Netlify CMS, is a powerful open-source headless CMS that allows developers to manage content in a user-friendly interface while leveraging the power of static site generation with frameworks like Next.js. In this tutorial, we’ll walk you through the steps to set up and use Decap CMS in a Next.js application.

Prerequisites

Before we get started, ensure that you have the following:

A basic understanding of Next.js
Node.js and npm installed
Familiarity with Git and version control

1. Setting Up a Next.js Project

1.1 Create a New Next.js Application

First, let's create a new Next.js application. Open your terminal and run the following command:

npx create-next-app my-nextjs-cms
cd my-nextjs-cms

This command creates a new Next.js project in a folder named my-nextjs-cms and navigates into that directory.

1.2 Install Necessary Packages

Next, we need to install Decap CMS. You can do this by running:

npm install decap-cms-app

This command installs Decap CMS in your Next.js project, making it available for use.

2. Configure Decap CMS

2.1 Create a Configuration File

Now, we’ll create a configuration file for Decap CMS. This file will define the settings and collections that Decap CMS will use.

Create a directory named admin inside the public folder:

# Create and navigate into public/admin folder
mkdir -p public/admin
cd public/admin

# Create index.html and config.yml file
touch index.html
touch config.yml

Then, create a file named config.yml in the public/admin directory:

# public/admin/config.yml
backend:
  name: git-gateway
  branch: main  # The branch to update
  repo: github_username/repo_name

local_backend: true # set to true to allow decap cms to save file locally during development

media_folder: "public/uploads"  # Folder to store media
public_folder: "/uploads"  # Public URL for media

collections:
  - name: "posts"  # Name of the collection
    label: "Posts"  # Label for the admin UI
    folder: "/public/content/posts"  # Folder where posts are stored
    create: true  # Allow new posts to be created
    slug: "{{year}}-{{month}}-{{day}}-{{slug}}"  # Post slug format
    fields: # The fields for each document, usually in front matter
      - { name: "layout", label: "Layout",  widget: "hidden", default: "posts" }
      - { name: "title", label: "Title", widget: "string" }
      - { name: "date", label: "Date", widget: "dateformat", date_format: "YYYY-MM-DD", time_format: false },
      - { name: "thumbnail", label: "Featured Image",  widget: "image" }
      - { name: "body", label: "Body", widget: "markdown" }

This configuration sets up a backend with Git Gateway, specifies where to store media, and defines a collection for blog posts with fields for title, date, and body.

Here's a breakdown of the provided code in a table format:

Key	Description
`collections`	An array defining different content collections for the CMS.
`- name`	`"posts"`: The name of the collection, used internally by the CMS.
`label`	`"Posts"`: The label that will be displayed in the admin UI for users.
`folder`	`"content/posts"`: The directory where the posts will be stored in the file system.
`create`	`true`: Indicates that new posts can be created in this collection.
`slug`	`"{{year}}-{{month}}-{{day}}-{{slug}}"`: The format for generating post URLs, using the year, month, day, and custom slug.
`fields`	An array defining the fields that each post will have, usually found in the front matter at the beginning of the document, (except for `body`, which follows the front matter). Each field contains the following properties: `label`, `widget`, `name`.
`- { name: "layout"`	Defines a field for the post's layout.
`label: "Layout"`	The label for the layout field, shown in the admin UI.
`widget: "hidden"`	The type of widget for this field, which is hidden in the UI.
`default: "posts"`	The default value for this field, set to "posts".
`- { name: "title"`	Defines a field for the post's title.
`label: "Title"`	The label for the title field in the admin UI.
`widget: "string"`	The type of widget for this field, which allows string input.
`- { name: "date"`	Defines a field for the post's date.
`label: "Date"`	The label for the date field in the admin UI.
`widget: "dateformat"`	The type of widget for date input, providing a date picker.
`date_format: "YYYY-MM-DD"`	Specifies the format for displaying the date.
`time_format: false`	Indicates that time should not be included in this field.
`- { name: "thumbnail"`	Defines a field for the post's featured image.
`label: "Featured Image"`	The label for the thumbnail field in the admin UI.
`widget: "image"`	The type of widget for this field, allowing image uploads.
`- { name: "body"`	Defines a field for the main content of the post.
`label: "Body"`	The label for the body field in the admin UI.
`widget: "markdown"`	The type of widget for this field, allowing for Markdown input for the post content.

This table breaks down each part of the configuration, providing a clear understanding of the structure and purpose of each key in the CMS collection setup.

Paste HTML for Decap CMS into your public/admin/index.html file

<!doctype html>
<html>
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Content Manager</title>
  <script src="https://identity.netlify.com/v1/netlify-identity-widget.js"></script>
</head>
<body>
  <!-- Include the script that builds the page and powers Decap CMS -->
  <script src="https://unpkg.com/decap-cms@^3.0.0/dist/decap-cms.js"></script>
</body>
</html>

2.2 Set Up Authentication

To enable authentication, you can use Git Gateway. This allows users to authenticate via Git providers (e.g., GitHub, GitLab) or services like Netlify. Make sure your hosting platform supports this configuration.

If you are using Netlify, enable Identity and Git Gateway in your Netlify dashboard.
1. Go to Integrations > Identity > Netlify Identity - Enable, click Enable Identity, and then go to Configuration and usage.
2. Under Registration, choose Open or Invite only. Usually, you want only invited users to access your CMS, but if you're just testing, you can leave it open.
3. To allow one-click login with services like Google and GitHub, check the boxes next to the services you want to use under External providers.
4. Scroll down to Services > Git Gateway, and click Enable Git Gateway. This will authenticate with your Git host and generate an API access token. We're leaving the Roles field blank, which means any logged-in user can access the CMS. For more details on changing this, check the Netlify Identity documentation.
Configure your repos settings to allow access via the configured identity provider.

3. Create Admin Interface

3.1 Create the Admin Page

We need to create a page that will serve as the admin interface for Decap CMS. Create a new file named index.tsx in the pages/admin directory:

// pages/admin/index.tsx

import { useEffect } from "react";
import Head from "next/head";

interface NetlifyIdentity {
  on: (event: string, callback: (user: any) => void) => void; // Update here
  // Add other properties and methods as needed
}

declare global {
  interface Window {
    netlifyIdentity: NetlifyIdentity;
  }
}

const CMSPage: React.FC = () => {
  useEffect(() => {
    // Initialize Netlify Identity
    if (window.netlifyIdentity) {
      window.netlifyIdentity.on("init", (user) => {
        if (!user) {
          window.netlifyIdentity.on("login", () => {
            document.location.href = "/admin/";
          });
        }
      });
    }

      // Dynamically add the decap-cms script in the body
      // const script = document.createElement("script");
      // script.src = "https://unpkg.com/decap-cms@^3.0.0/dist/decap-cms.js";
      // script.async = true;
      // document.body.appendChild(script);

      // return () => {
      //   document.body.removeChild(script);
      // };
  }, []);

  return (
    <>
      <Head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <meta name="robots" content="noindex" />
        <title>Content Manager</title>
        <script
          src="https://unpkg.com/decap-cms@^3.0.0/dist/decap-cms.js"
          async
        ></script>
        <script
          src="https://identity.netlify.com/v1/netlify-identity-widget.js"
          async
        ></script>
        <link href="/admin/config.yml" type="text/yaml" rel="cms-config-url" />
      </Head>
      <main id="cms" />
    </>
  );
};

export default CMSPage;

Alternatively, we can also use the Next.js Script tag like this:

 import Script from "next/script";


  return (
    <>
      <Head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <meta name="robots" content="noindex" />
        <title>Content Manager</title>
        <link href="/admin/config.yml" type="text/yaml" rel="cms-config-url" />
      </Head>
      <Script
        src="https://identity.netlify.com/v1/netlify-identity-widget.js"
        async
      />
      <Script src="https://unpkg.com/decap-cms@^3.0.0/dist/decap-cms.js" async></Script>
      <main id="cms" />
    </>
  );

Let's break down the code.

Importing Required Modules

import { useEffect } from "react";
import Head from "next/head";

The code begins by importing necessary modules. useEffect from React is a hook that allows us to perform side effects in functional components, such as initializing authentication when the component mounts. Head from Next.js is used to manage the document head, allowing us to set meta tags, titles, and scripts essential for our application.

Defining the Netlify Identity Interface

interface NetlifyIdentity {
  on: (event: string, callback: (user: any) => void) => void; // Update here
  // Add other properties and methods as needed
}

Here, we define an interface called NetlifyIdentity. This interface specifies the structure of the Netlify Identity object we expect to find on the window object. The on method allows us to listen for specific events (like "init" or "login") and provide a callback function that receives a user object.

Declaring Global Variables

declare global {
  interface Window {
    netlifyIdentity: NetlifyIdentity;
  }
}

In this section, we extend the global Window interface to include our NetlifyIdentity interface. This ensures TypeScript understands that window.netlifyIdentity exists and conforms to our defined structure, eliminating type errors during development.

The CMSPage Component

const CMSPage: React.FC = () => {

We define a functional component named CMSPage. This component serves as the main interface for our content management system.

Setting Up useEffect

useEffect(() => {
  // Initialize Netlify Identity
  if (window.netlifyIdentity) {
    window.netlifyIdentity.on("init", (user) => {
      if (!user) {
        window.netlifyIdentity.on("login", () => {
          document.location.href = "/admin/";
        });
      }
    });
  }
}, []);

Inside the component, we utilize the useEffect hook. This hook runs after the component mounts, and here’s what happens:

Check for Netlify Identity: We first check if window.netlifyIdentity is available, ensuring that the Netlify Identity script has loaded properly.
Listening for Events:

* **"init" Event**: When the Netlify Identity initializes, it returns a `user` object if the user is already logged in. If `user` is `null`, it indicates that no user is logged in.

* **"login" Event**: If the user logs in, we redirect them to the `/admin/` route, where they can manage content.

This flow ensures that users who are not logged in are automatically redirected to the login interface.

Configuring the Document Head

return (
  <>
    <Head>
      <meta charSet="utf-8" />
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <meta name="robots" content="noindex" />
      <title>Content Manager</title>
      <script
        src="https://unpkg.com/decap-cms@^3.0.0/dist/decap-cms.js"
        async
      ></script>
      <script
        src="https://identity.netlify.com/v1/netlify-identity-widget.js"
        async
      ></script>
      <link href="/admin/config.yml" type="text/yaml" rel="cms-config-url" />
    </Head>
    <main id="cms" />
  </>
);

In this part of the code, we define the structure of the HTML document:

Meta Tags: We set the character set, viewport settings for responsiveness, and specify that this page should not be indexed by search engines.
Title: The title of the page is set to "Content Manager", which will be displayed in the browser tab.
Scripts:
- We include the Decap CMS script from a CDN, which is necessary for the CMS functionalities.
- We also include the Netlify Identity widget script, enabling user authentication functionalities.
Configuration Link: The link to our CMS configuration file (public/admin/config.yml) is included, which the Decap CMS will use to understand how to manage our content.

Main Render Function

<main id="cms" />

Finally, we define a <main> element with an ID of cms. This is where Decap CMS will mount and manage content.

Exporting the Component

export default CMSPage;

We export the CMSPage component, making it available for use in other parts of our Next.js application.

3.2 Start Your local server

Working with a Local Git Repository

Decap CMS can be connected to a local Git repository, allowing you to manage content without relying on a live repository. Here’s how to set it up:

Navigate to Your Local Git Repository

Ensure you're in the root directory of your local Git repository configured with Decap CMS.
Update Your Configuration

In your config.yml file, add the following top-level property to enable local backend functionality:
```
local_backend: true
backend:
  name: git-gateway
```
Start the Decap Server

Run the following command from the root directory of your repository to start the Decap server:
```
npx decap-server
```
If the default port (8081) is already in use, the proxy server won't start, and you will see an error message. In this case, you should resolve the port conflict before proceeding.
Start Your Next.js Development Server

In a separate terminal window, start your Next.js application. For example:
```
npm run dev
```
Access the Admin Interface

Open your web browser and navigate to:
```
http://localhost:<your-nextjs-port>/admin
```
Replace <your-nextjs-port> with the port number your Next.js server is running on (the default is usually 3000). This allows you to verify that you can administer your content locally.

Important Note

It’s crucial to keep the Decap server running alongside your Next.js development server. The Decap server serves as a backend for content management, enabling the CMS to save files locally during development. If the Decap server is not running, you won't be able to access the admin interface or manage your content effectively.

Additionally, please be aware that the Decap server operates an unauthenticated Express server. Since any client can send requests to this server, it should only be used for local development purposes. Also, note that the editorial_workflow feature is not supported in this environment.

3.3 Add Links to Admin Page

Next, you may want to provide a navigation link to the admin page from your application. You can do this by modifying the index.tsx file:

// pages/index.tsx
import Link from 'next/link';

const HomePage = () => {
  return (
    <div>
      <h1>Welcome to My Blog</h1>
      <Link href="/admin">Go to Admin</Link>
    </div>
  );
};

export default HomePage;

4. Build Your Content Structure

4.1 Creating Markdown Files

To structure your content, create a content/posts directory for your blog posts in the public directory. This will be where Decap CMS saves the markdown files created from the admin interface, as configured in the config.yml file:

mkdir -p content/posts

Within this content/posts directory, you can manually create Markdown files for your blog posts or use a content management system like Decap CMS to manage your posts directly from an admin interface.

4.2 Previewing Content

Decap CMS allows you to preview content directly within the admin interface. You can test this feature by creating a new post and using the preview option available in the editor.

5. Writing Utility Functions for Markdown Posts

To effectively manage and fetch your blog posts, it’s a good practice to create a utility file containing functions that handle operations related to your Markdown files. This can help keep your code clean and organized.

First, install the gray-matter package to parse markdown frontmatter:

npm install gray-matter

5.1 Creating a Utils File

Create a new file named utils.ts (or any preferred name) in your project directory, and add the following functions to manage your Markdown files:

import fs from "fs";
import matter from "gray-matter";
import path from "path";
import { PostData } from "./types"; // Import your type

// example if using typescript: this is based on the post schema we created in the config.yml

export interface PostData {
  slug: string;
  title: string;
  description: string;
  date: string; // Use Date type if you want to work with Date objects
  thumbnail?: string; // Optional
  author: string;
  body: string; // The actual content of the post
}

const postsDirectory = path.join(process.cwd(), "content/posts");

export function getSortedPostsData(): PostData[] {
  const fileNames = fs.readdirSync(postsDirectory);
  const allPostsData: PostData[] = fileNames.map((fileName) => {
    const slug = fileName.replace(/\.md$/, "");
    const fullPath = path.join(postsDirectory, fileName);
    const fileContents = fs.readFileSync(fullPath, "utf8");
    const { data } = matter(fileContents);

    return {
      slug,
      ...data,
      date: data.date instanceof Date ? data.date.toISOString() : data.date,
    } as PostData;
  });

  return allPostsData.sort((a, b) => (a.date < b.date ? 1 : -1));
}

export function getAllPostIds() {
  const fileNames = fs.readdirSync(postsDirectory);
  return fileNames.map((fileName) => ({
    params: {
      slug: fileName.replace(/\.md$/, ""), // Removing .md extension
    },
  }));
}

export function getPostData(slug: string): PostData {
  const fullPath = path.join(postsDirectory, `${slug}.md`);
  const fileContents = fs.readFileSync(fullPath, "utf8");
  const matterResult = matter(fileContents);

  return {
    slug,
    ...matterResult.data,
    date: matterResult.data.date instanceof Date ? new Date(matterResult.data.date).toISOString() : matterResult.data.date,
    body: matterResult.content,
  } as PostData;
}

5.2 Explanation of Utility Functions

Function Name	Description
`getSortedPostsData`	Reads all Markdown files, extracts their metadata, sorts the posts by date, and returns an array of post data.
`getAllPostIds`	Retrieves all post file names and maps them to an array of objects containing the `slug` parameter for dynamic routing in Next.js.
`getPostData`	Fetches the content and metadata of a single post based on its slug, returning it in a structured format.
`const { data } = matter(fileContents);`	In this code, we read the Markdown files from the `content/posts` directory, extract their metadata using gray-matter, and pass the posts as props.

6. Fetching and Displaying Content in Next.js

Now that we have our utility functions, we can integrate them into our Next.js pages.

6.1 Use `getStaticProps` to Fetch Posts

Next.js allows you to fetch data at build time using getStaticProps.

To fetch data at build time using getStaticProps, update your index.tsx file in the pages directory:

// pages/index.tsx
import { getSortedPostsData } from "@/utils"; // Import the utility function
import Link from "next/link";

export const getStaticProps = async () => {
  const allPostsData = getSortedPostsData();

  return {
    props: {
      posts: allPostsData,
    },
  };
};

const HomePage = ({ posts }) => {
  return (
    <div>
      <h1>Welcome to My Blog</h1>
      {posts.map(post => (
        <div key={post.slug}>
          <h2>{post.title}</h2>
          <p>{post.date}</p>
          <Link href={`/posts/${post.slug}`}>
            <a>Read More</a>
          </Link>
        </div>
      ))}
    </div>
  );
};

export default HomePage;

In this code, we read the Markdown files from the content/posts directory, extract their metadata using our utility function, and pass the posts as props to the HomePage component.

6.2 Rendering Posts on the Page

You can render each post’s title and date in a list format. The Read More link will take users to a detailed page for each post.

Create a dynamic route to display individual posts. Create a new folder called posts under pages, then create a [slug].tsx file:

This code allows you to fetch and render the content of individual markdown posts.

Tom properly handle markdown we can use a markdown parser and sanitizer such as the react-markdown or next-mdx-remote .

start by innstallling your prefered package, here i will be using the react-markdown for simplicity:

npm i react-markdown

You can now use as follows:

// pages/posts/[slug].tsx
import { getPostData, getAllPostIds } from "@/utils"; // Import the utility functions
import { GetStaticPaths, GetStaticProps } from "next";

export const getStaticPaths: GetStaticPaths = async () => {
  const paths = getAllPostIds();
  return {
    paths,
    fallback: false, // This will show a 404 for paths not returned by getStaticPaths
  };
};

export const getStaticProps: GetStaticProps = async ({ params }) => {
  const postData = getPostData(params.slug as string);

  return {
    props: {
      post: postData,
    },
  };
};

const PostPage = ({ post }) => {
  return (
    <div>
      <h1>{post.title}</h1>
      <p>{post.date}</p>
     {/* // a simple way to doit without using a package(NOT RECOMMENDED) */}
          {/*  <div dangerouslySetInnerHTML={{ __html: post.body }} /> */} 
     {/* RECOMMNEDED */}
      <Markdown remarkPlugins={[remarkGfm]}>{post.body}</Markdown>
    </div>
  );
};

export default PostPage;

6. Deployment

6.1 Deploying to Netlify or Vercel

After you’ve completed your application, you can deploy it to platforms like Netlify or Vercel.

Netlify: You can connect your GitHub repository to Netlify and enable Identity and Git Gateway

to manage authentication for Decap CMS.

Vercel: Simply push your code to a GitHub repository, and you can deploy it directly from Vercel’s dashboard.

6.2 Environment Variables

If you are using any environment variables (e.g., for GitHub or GitLab authentication), make sure to set them up in your platform's settings.

7. Conclusion

Congratulations! You have successfully set up and integrated Decap CMS with your Next.js application. You can now manage your blog content easily through the Decap CMS interface.

In this guide, we've explored how to set up a Markdown blog in Next.js, including creating a content structure, writing utility functions to manage posts, and using these functions to display content in the application.

By organizing your code and leveraging utility functions, you can keep your blog manageable and extendable, allowing for easy content updates and a smooth user experience. Now, you can create and manage your blog posts efficiently, whether manually or through a content management system like Decap CMS. Happy blogging!

If you have any questions or feedback, feel free to leave a comment below!

Additional Resources

Responsive Design in React Native: Building Apps for Multiple Screen Sizes

Abdulwasiu Abdulmuize — Sun, 23 Feb 2025 06:12:45 +0000

As mobile devices come in various shapes and sizes, building responsive designs in React Native is crucial to delivering seamless user experiences. In this post, we'll explore strategies and tools for ensuring your React Native app looks great and functions well on screens of all sizes, from small phones to larger tablets.

Why Responsive Design Matters

Responsive design ensures that your app adapts to different screen dimensions and resolutions without breaking the layout or sacrificing usability. A well-designed responsive app will:

Enhance user experience: Users expect apps that are easy to navigate, regardless of the device they're using. Responsive design keeps your users engaged and satisfied.
Increase userbility, allowing users on different screen sizes to access the same features.
Reduce development costs, as it minimizes the need for separate codebases for different devices.
Wider User Reach: Catering to multiple screen sizes means your app can reach a broader audience, from small smartphones to large tablets and beyond.
Improved Accessibility: Accessibility is vital. Responsive design ensures that your app is usable by people with disabilities, no matter their device's characteristics.

Techniques for Responsive Design in React Native

Now, let's explore some techniques to achieve responsive design in React Native:

1. Flexbox: The Backbone of Responsive Layouts

React Native uses Flexbox as its primary layout model, which makes it easier to design responsive UIs. Flexbox allows you to define flexible and adaptive layouts that adjust to various screen sizes.

Example: Simple Flexbox Layout

import React from 'react';
import { View, Text, StyleSheet } from 'react-native';

const ResponsiveScreen = () => {
  return (
    <View style={styles.container}>
      <View style={styles.header}>
        <Text style={styles.text}>Header</Text>
      </View>
      <View style={styles.content}>
        <Text style={styles.text}>Content</Text>
      </View>
      <View style={styles.footer}>
        <Text style={styles.text}>Footer</Text>
      </View>
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
  header: {
    flex: 1,
    backgroundColor: '#FFD700',
    justifyContent: 'center',
    alignItems: 'center',
  },
  content: {
    flex: 3,
    backgroundColor: '#00BFFF',
    justifyContent: 'center',
    alignItems: 'center',
  },
  footer: {
    flex: 1,
    backgroundColor: '#32CD32',
    justifyContent: 'center',
    alignItems: 'center',
  },
  text: {
    fontSize: 18,
  },
});

export default ResponsiveScreen;

In this example, we define three sections—Header, Content, and Footer—using Flexbox. The layout will automatically adapt to different screen sizes by adjusting the proportions (1:3:1) without needing any additional work.

2. Using Dimensions API for Dynamic Layouts

The Dimensions API in React Native allows you to retrieve the device's width and height at runtime. This is useful when you want to adjust your UI dynamically based on the screen's size.

Example: Adjusting Layout Dynamically

import React from 'react';
import { View, Text, StyleSheet, Dimensions } from 'react-native';

const { width, height } = Dimensions.get('window');

const DynamicScreen = () => {
  return (
    <View style={styles.container}>
      <Text style={styles.text}>Screen Width: {width}</Text>
      <Text style={styles.text}>Screen Height: {height}</Text>
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
  text: {
    fontSize: width > 400 ? 24 : 16, // Adjust font size based on screen width
  },
});

export default DynamicScreen;

In this example, we use the Dimensions API to adjust the font size dynamically. If the screen width is greater than 400 pixels, the font size will increase to 24; otherwise, it will remain 16.

3. Percentage-based Dimensions

Using percentage-based values for width and height ensures that UI elements scale proportionally across different screen sizes.

Example: Percentage-based Sizing

const styles = StyleSheet.create({
  box: {
    width: '80%', // 80% of the screen width
    height: '50%', // 50% of the screen height
    backgroundColor: '#FF4500',
  },
});

This approach allows you to define elements that scale in proportion to the screen dimensions, making your layout more flexible and adaptable to various devices.

4. Platform-specific Styles

React Native provides Platform module that lets you conditionally render styles or components based on the platform (iOS or Android).

Example: Platform-specific Styling

import { Platform, StyleSheet } from 'react-native';

const styles = StyleSheet.create({
  button: {
    padding: 10,
    ...Platform.select({
      ios: {
        backgroundColor: '#007AFF',
      },
      android: {
        backgroundColor: '#3DDC84',
      },
    }),
  },
});

With Platform.select, we apply different background colors for buttons on iOS and Android devices.

5. React Native Responsive Libraries

To streamline responsive design in React Native, you can use several libraries that help scale UI components and handle various screen sizes.

5.1 `react-native-responsive-screen`

react-native-responsive-screen allows you to define elements in terms of screen percentage, ensuring consistent sizes across different devices.

npm install react-native-responsive-screen

Example: Using `react-native-responsive-screen`

import { widthPercentageToDP as wp, heightPercentageToDP as hp } from 'react-native-responsive-screen';

const styles = StyleSheet.create({
  container: {
    width: wp('90%'), // 90% of screen width
    height: hp('50%'), // 50% of screen height
  },
});

5.2 `react-native-size-matters`

This library provides simple utility functions for scaling styles based on screen size, making it easier to maintain consistency.

npm install react-native-size-matters

Example: Using `react-native-size-matters`

import { ScaledSheet } from 'react-native-size-matters';

const styles = ScaledSheet.create({
  container: {
    width: '100@s', // Scales based on the screen size
    height: '200@ms', // Scales moderately based on screen size
  },
});

6. Media Queries in React Native

Although React Native doesn't have native support for CSS media queries, you can achieve similar behavior using the useWindowDimensions hook or third-party libraries like react-native-media-query.

Example: Using `useWindowDimensions`

import { useWindowDimensions } from 'react-native';

const ResponsiveComponent = () => {
  const { width } = useWindowDimensions();

  return (
    <View style={[styles.container, width > 400 && styles.largeScreen]}>
      <Text>Responsive Layout</Text>
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    backgroundColor: 'lightgray',
  },
  largeScreen: {
    padding: 20,
    backgroundColor: 'darkgray',
  },
});

In this example, we conditionally apply styles based on the screen width.

Other Methods

1. Dynamic Font and Text Scaling

Text should scale dynamically according to the user's device settings for accessibility. React Native provides the Text component, which automatically adjusts based on user preferences. However, you can also use the PixelRatio and Dimensions APIs to control text scaling dynamically.

import { Text, StyleSheet, PixelRatio, Dimensions } from 'react-native';

const { width } = Dimensions.get('window');
const scale = width / 320; // Base width to scale fonts

export function normalize(size) {
  const newSize = size * scale;
  return Math.round(PixelRatio.roundToNearestPixel(newSize));
}

// Usage
const styles = StyleSheet.create({
  text: {
    fontSize: normalize(14), // Dynamically scaled font size
  },
});

In this code:

normalize(size) dynamically scales the font size based on the screen width.
This approach ensures that text size adapts across devices while respecting the user's font settings.

2. Scalable Images

In React Native, you can use scalable vector graphics (SVG) or different image assets for various screen densities to maintain image quality.

For scalable images:
- Use .svg files for vector-based images. You can leverage libraries like react-native-svg to render them. This ensures images scale perfectly on any screen size without losing quality.
- For raster images, provide multiple resolutions (e.g., @1x, @2x, @3x) for different screen densities.
Example usage of an image:

import { Image, StyleSheet } from 'react-native';

const ScalableImage = () => {
  return <Image style={styles.image} source={require('./image.png')} />;
};

const styles = StyleSheet.create({
  image: {
    width: 100,
    height: 100,
    resizeMode: 'contain', // Ensure the image scales proportionally
  },
});

export default ScalableImage;

By providing image assets in different resolutions, React Native automatically selects the appropriate image based on the device’s screen density.

3. DPI and Pixel Ratios

Device Pixel Density (DPI) plays a crucial role in ensuring that visuals remain sharp across various screen resolutions. React Native’s PixelRatio API helps you manage pixel densities effectively.

import { PixelRatio } from 'react-native';

const devicePixelRatio = PixelRatio.get(); // Returns the current device's pixel ratio

if (devicePixelRatio >= 2) {
  // High-density screen logic here
}

PixelRatio.get() returns the current pixel ratio of the device.
You can use this information to adjust layouts, images, or icons to ensure they look sharp and appropriate on high-density displays.

4. Testing on Real Devices

Emulators and simulators provide a basic idea of how your app behaves on different screen sizes and orientations, but real-device testing is essential for truly understanding user experience.

Tips for Testing:

Test on devices with different screen sizes: iPhones, iPads, and Android devices with varying resolutions.
Use landscape and portrait modes: Ensure your layout adapts correctly to both orientations.
Check scaling behavior: Make sure fonts, images, and UI elements scale correctly on small and large screens.
Test different pixel densities: Verify that images and text remain sharp across devices with varying DPIs.

You can also use Expo Go or USB debugging to quickly test on real devices without having to install the app each time.

Conclusion

Responsive design in React Native is essential for creating apps that look and function well across various devices. By leveraging Flexbox, percentage-based dimensions, the Dimensions API, and responsive libraries, you can ensure your app scales smoothly on all screen sizes. Combining these techniques with platform-specific styling and media queries further enhances the adaptability and user experience of your app.

Start building responsive React Native apps today and make sure every user, regardless of their device, gets the best experience!

My Goals and Plans for the 8 weeks of the HNGi8 Internship. LET'S GO

Abdulwasiu Abdulmuize — Sun, 15 Aug 2021 13:42:44 +0000

Why I Enrolled For the Internship

I applied for HNG internship because I heard about how intense it was. I'm really just looking to learn a lot.

I've always yearned for a hands-on learning opportunity, and I believe this will provide me with "experience." It may be argued that it is a necessary method of learning rather than being informed overtly.

Enough with the blah blah blah blah blah paragraph Let's discuss the HNG internship.

What is HNG internship

The HNG internship is a program that aims to alter Africa's educational system. Its goal is to bridge the gap between coding and world-class performance. The HNG internship's main goal is to assist those who desire to start a career in technology but are limited by distance. The HNG internship is designed in such a way that it can accommodate you regardless of your background.

My Goals for HNGi8 internship include the following:

I am so looking forward to engaging in the weekly tasks that are more focused on real-world experiences.
Learn and grow my skillsets in Web programming.
Build awesome relationships with team mates and mentors.

On the bright side, I'll provide some courses that will be useful along this adventure. You might require those as well :)

JavaScript
Modern JavaScript Tutorial

Figma
The Figma 2021 Crash Course by Example

Git and Github
Git Tutorial for Beginners - Git & GitHub Fundamentals In Depth

You can visit the Zuri Website to learn more about their internships.

And that brings us to the end of this article. I hope everything goes well and till next time.

P.S: This blog post is part of the entry project to advance into level 1 of the HNG Internship program.

Forem: Abdulwasiu Abdulmuize

🚀 Instant Pages with Speculation Rules: The Secret to Lightning-Fast Web Navigation

What is the Speculation Rules API?

Key Benefits Over Older Techniques

Implementation Patterns

1. Embedding Rules in HTML

2. Inject via JavaScript

3. Via HTTP Header

Rolling It Out: A Guided Strategy

🌱 1. Start with Prefetch (Low-Risk, Low-Cost)

🌿 2. Move to Low-Risk Prerender (Faster, Still Safe)

🌳 3. Implement Eager Prerenders (Predictive & Fastest)

Summary Table

Safety First: Pitfalls to Avoid

Measurement: Did It Work?

Summary and Final Tips

Sample Implementation Snippet

Breaking the Monolith: How I Successfully Separated an E-Learning Platform for Better Security and Performance

The Challenge: When One Size No Longer Fits All

The Solution: Separation for Specialization

The Architecture: Smart Separation with Shared Resources

Implementation Challenges and Solutions

🧩 Challenge 1: Component Dependencies

🧠 Challenge 2: State Management

🔁 Challenge 3: Routing and Auth Logic

The Results: Measurable Improvements

🔒 Enhanced Security

⚡ Performance Gains

💻 Developer Experience

🚀 Operational Benefits

Impact Metrics: Before vs After

Key Lessons from the Migration

1. 🧱 Architect the Shared Layer First

2. 📦 Keep Imports Consistent

3. 👥 Design for Team Autonomy

4. 🧪 Test Thoroughly During Migration

Technology Stack That Enabled Success

Long-Term Benefits (6 Months Later)

When Should You Consider Platform Separation?

Conclusion: Thoughtful Separation, Strategic Evolution

From Sluggish to Lightning Fast: A Database Performance Optimization Journey

The Problem: N+1 Queries and Slow Load Times

The Solution: Strategic Database Optimization

1. Smart Database Indexing

2. Aggregation Pipeline

3. Automatic Index Creation

The Results: Dramatic Performance Improvements

Bonus Features: Pagination and Scalability

Key Takeaways

The Bottom Line

The Cleanest Way to Manage React Native Audio State: Zustand + TrackPlayer

Why Auto-Sync?

🧠 Our Goal: The useTrackPlayerSync() Hook

✅ Step 1: Create Zustand Store

🧩 Step 2: The useTrackPlayerSync() Hook

🚀 Step 3: Use the Hook in App

🔁 Syncing Volume & Settings from UI

✅ Benefits Recap

🎉 Conclusion

Building a Robust SQLite Query Builder in TypeScript: Lessons from an Arabic Dictionary App

Why a Custom Query Builder?

The Core Architecture: Chainable and Type-Safe

1. Defining the Building Blocks (Types)

2. The BaseQueryBuilder: Common Functionality

3. Specialized Builders

SelectQueryBuilder

UpdateQueryBuilder (with Safety Check)

4. The QueryBuilder Factory

5. Database Executor: Bridging to SQLite

Integration with the Arabic Dictionary App

Before (Raw SQL)

After (Using Query Builder)

Benefits

Challenges and Further Considerations

Conclusion

Building a Markdown Blog in Next.js with Decap CMS: A Comprehensive Guide

Introduction

Prerequisites

1. Setting Up a Next.js Project

1.1 Create a New Next.js Application

🧠 Our Goal: The `useTrackPlayerSync()` Hook

🧩 Step 2: The `useTrackPlayerSync()` Hook

6.1 Use `getStaticProps` to Fetch Posts

5.1 `react-native-responsive-screen`

Example: Using `react-native-responsive-screen`

5.2 `react-native-size-matters`

Example: Using `react-native-size-matters`

Example: Using `useWindowDimensions`