This page exists for recruiters, collaborators, and other developers who want more than a project card gives — the actual stack, the structural decisions behind it, and the trade-offs that came with them.
1Project Overview
- Project
- Toufiq Alahe — Personal Developer Portfolio
- Purpose
- Showcase projects, skills, and experience to recruiters, clients, and collaborators
- Type
- Marketing / personal-brand website — no accounts, no backend data store
- Status
- Actively developed, deployed in production
- Framework
- Next.js 16 (App Router), React 19
- Hosting
- toufiq-portfolio.vercel.app on Vercel
2Technology Stack
Only what’s actually imported and used in src/ — not everything sitting in package.json.
Framework & Language
Animation & UX
Integrations
Tooling & Hosting
Note: next-themes, clsx, and tailwind-mergeare listed in package.json but aren’t currently imported anywhere in src/ — likely leftovers from scaffolding.
3Key Features
Animated Hero
Typewriter-style headline text with a mouse-driven parallax effect, built with Framer Motion.
Scroll-Spy Navigation
The navbar highlights the active section by comparing scroll position against section offsets cached on mount and resize — a magnetic desktop pill nav plus a slide-in mobile drawer.
Live GitHub Activity
A contribution calendar plus computed total-contributions, streak, and repo-count stats, fetched from GitHub’s public API and cached client-side for two hours.
Animated Stat Counters
Homepage stats count up on scroll into view using GSAP tied to the Lenis-smoothed scroll position.
Project Showcase
A homepage preview grid, a full listing page, and a statically generated detail page per project — with a real server-side 404 for unknown IDs.
Dynamic Social Previews
Open Graph images generated at request time with next/og, reusing the site’s actual brand colors instead of static export images.
Contact Form
Delivered through EmailJS (a notification email plus an automatic acknowledgement reply), guarded by a hidden honeypot field.
Light / Dark Theme
A custom context plus an inline blocking script that reads localStorage before hydration, so there’s no flash of the wrong theme.
Development Journey Timeline
An animated, alternating timeline narrating the author’s learning path, backed by a small local data module.
SEO & Legal Pages
Per-route metadata, Person/WebSite/CreativeWork JSON-LD, a generated sitemap and robots file, plus this page’s siblings — Privacy Policy and Terms of Service.
4Architecture
The app lives entirely under src/ (App Router), with a @/* import alias pointing at ./src/*.
- /Data layer. Content (about, skills, tech stack, projects, experience, nav links, social links) lives in plain JS modules under
src/data/*.jsand is imported directly into components — not fetched over HTTP. Matching/api/*route handlers still exist but aren’t called by anything insrc/— a leftover from an earlier client-fetch architecture. - /Rendering. The home page and each project page are plain Server Components. Below-the-fold home sections are still loaded through
next/dynamicfor code-splitting, but withssr: true, so they’re server-rendered like everything else — the dynamic import only trims client JS, it doesn’t defer the render. - /Static generation.
/projects/[id]usesgenerateStaticParamsto pre-render one page per project and callsnotFound()server-side for a real HTTP 404 on unknown IDs. - /Client/server boundary. Client Components are reserved for genuinely interactive or animated pieces (navigation, hero, contact form, the smooth-scroll/cursor/ambient-glow layer, project list/detail shells). This page, along with Privacy Policy and Terms of Service, is a plain Server Component with no client JS of its own.
- /External data. The only runtime call to an external API happens client-side, in the GitHub-stats hook, which hits GitHub’s REST API and a public contributions API and caches the result in
localStoragefor two hours.
5Technical Decisions
- /Static data imports over self-fetching API routes. Server Components can’t usefully fetch their own route handlers at build time, and doing so client-side added a visible loading flash → importing the data modules directly gives faster first paint and simpler code.
- /generateStaticParams + notFound() for project pages. Produces one static page per project at build time and a real HTTP 404 for missing IDs, instead of a client-detected “not found” state → better SEO and near-instant loads.
- /Inline blocking theme script. The theme class has to be set before first paint, which requires DOM access before React hydrates → no flash of the wrong theme despite defaulting to dark.
- /Lenis synced to a shared GSAP ticker. GSAP’s scroll-driven animations (stat counters, calendar glow) need to track a custom smooth-scroll library rather than native scroll → animations stay locked to the eased scroll position instead of drifting.
- /Dynamic OG images instead of static export assets. Social preview cards can be generated per-project at request time with
next/og, reusing the same brand colors defined inglobals.css→ consistent previews with nothing to keep in sync manually.
6Security Notes
This site has a small attack surface by design — there are no accounts, sessions, or a database:
- /No authentication, user accounts, or stored visitor records exist, so there's no session, token, or password handling to secure.
- /No database is used, so there's no query-injection surface.
- /The contact form is delivered entirely client-side via EmailJS; its service ID, template IDs, and public key are hardcoded in
Contact.jsxrather than read from environment variables. EmailJS’s public key is designed to be exposed client-side, so this isn’t a secret leak — but hardcoding makes the values harder to rotate or scope per environment. - /A honeypot field filters basic bots on the contact form, but there's no server-side handler for the form at all — delivery relies entirely on the third-party EmailJS SDK.
- /The /api/* route handlers are unauthenticated, but they only re-serve public content already shipped in the page's HTML/JS, so there's no sensitive-data exposure risk in practice.
- /No secrets or credentials exist in the repository — there are no .env files checked in, and none were found to leak.
Security Considerations
- /No security headers (CSP, X-Frame-Options, etc.) are currently configured in next.config.mjs.
- /EmailJS credentials could be moved from hardcoded values to environment variables for easier rotation.
7Performance Notes
- /Static Server Components and SSG for pages that don't need per-request logic — the home page, the projects listing, and each project detail page.
- /next/dynamic code-splitting for below-the-fold home sections, each with a dedicated skeleton fallback to avoid layout shift while still server-rendering the content.
- /next/image is configured with AVIF/WebP output, a 7-day server cache TTL, and a hand-tuned device/image size list, instead of relying on Next's defaults.
- /GitHub stats are cached in localStorage for two hours (falling back to stale cache on fetch failure) to avoid re-hitting GitHub's API on every visit.
- /The navbar's scroll-spy caches section offsets once on mount/resize instead of calling getBoundingClientRect() inside the scroll handler — a documented fix for layout thrashing.
- /Microsoft Clarity loads via next/script with strategy="lazyOnload" to stay off the critical rendering path.
- /Fonts are loaded through next/font/google with display: swap and are self-hosted at build time, so there's no runtime request to Google for them.
8Third-Party Integrations
- /Microsoft Clarity — behavioral analytics (heatmaps, session recordings).
- /EmailJS — contact-form delivery and the automatic acknowledgement reply.
- /GitHub’s public REST API and github-contributions-api.jogruber.de with react-github-calendar — the live contribution calendar and stats.
- /Google Fonts — Inter, Space Grotesk, and Great Vibes (self-hosted via
next/font), plus the Material Symbols icon font (loaded live). - /Vercel — the hosting and deployment platform this site runs on.
9Development Challenges
- /Layout thrashing during scroll. Frequent
getBoundingClientRect()calls inside the navbar’s scroll handler forced synchronous layout, causing stutter. Fixed by caching section offsets on mount/resize and only comparing numbers during scroll. - /Client fetch latency. Client-side
useEffectfetches to local API routes caused visible skeleton/placeholder flashes on load. Fixed by importing the data modules directly into Server Components at build time instead.
10Lessons Learned
- /Server-side rendering combined with generateStaticParams delivers near-instant pages for content that's known at build time.
- /Caching scroll-position/boundary calculations instead of recomputing them on every scroll event keeps animation-heavy pages smooth.
11Future Improvements
None of the following are implemented yet:
- /An automated test suite — there's currently no unit or end-to-end testing configured; Playwright is the project's own stated plan for e2e coverage.
- /Security headers (CSP, X-Frame-Options, etc.) in next.config.mjs.
- /Moving the EmailJS service/template IDs and public key from hardcoded values to environment variables.
- /Either wiring up the vestigial /api/* routes to a real consumer or removing them to reduce surface area.
- /A blog section backed by a headless CMS, full i18n support, and interactive 3D elements — all listed as future ideas in the project's own README.
12Project Status
Toufiq Alahe’s portfolio is an actively developed, single-owner personal site — not a product with paying customers, so “production ready” in the SaaS sense doesn’t apply here. It is, however, live and functioning in production: deployed on Vercel, receiving ongoing feature commits, and used as the author’s primary professional showcase.
13Technical Highlights
- /Modern Next.js 16 App Router architecture, entirely under src/, with a consistent @/* import alias.
- /A real static-generation story — SSG project pages backed by a genuine server-side 404 via notFound().
- /A scroll-synced animation system (Lenis + GSAP ScrollTrigger) instead of plain scroll-event listeners.
- /Dynamic, per-page Open Graph image generation with next/og instead of static social-preview assets.
- /Deliberate, documented performance fixes (scroll-spy caching, direct data imports) rather than default framework behavior.
- /A hand-built design system — CSS custom properties driving Tailwind v4's @theme inline — powering light/dark theming with no flash of the wrong theme.
Questions about how any of this was built? toufiqalahe.dev@gmail.com