DEV Community: Nguyen Xuan Hai

GSAP ScrollTrigger pin: true Nearly Broke My Portfolio — Here's What I Learned

Nguyen Xuan Hai — Sat, 04 Apr 2026 14:35:57 +0000

The Bug That Took 3 Days to Find

Last week, I shipped an update to my portfolio site. Everything looked perfect on my dev machine. Then a friend texted me a screenshot from their phone:

"Bro... why is PROJECTS showing while I'm still reading your work history?"

He was right. The PROJECTS section transition was appearing on top of the Experience section — before users had finished scrolling through my work history. On mobile, it was even worse: the text was fully visible over my last two job entries.

I'd been staring at this site for 6 hours and never noticed. Classic developer blindness.

The Architecture

My portfolio uses a scrollytelling layout:

Profile → About → Experience → SectionTransition("PROJECTS") → Portfolio

The SectionTransition component is a full-viewport kinetic text reveal using GSAP ScrollTrigger:

// KineticType.jsx — The problem code
const tl = gsap.timeline({
    scrollTrigger: {
        trigger: container,
        start: "top top",
        end: "+=100%",
        pin: true,     // ← This is the culprit
        scrub: 1,
    }
});

tl.fromTo(textEl,
    { scale: 0.8, opacity: 0, y: 50 },
    { scale: 1, opacity: 1, y: 0, duration: 1 },
);

Looks clean, right? It worked perfectly on my 1440px monitor. But pin: true has hidden costs that only surface on smaller viewports.

What `pin: true` Actually Does

When GSAP pins an element, it does three things most developers don't realize:

1. Creates a Pin-Spacer Wrapper

<!-- Your original element -->
<div class="kinetic-container">PROJECTS</div>

<!-- What GSAP creates -->
<div class="pin-spacer" style="height: 1400px; padding-bottom: 700px;">
    <div class="kinetic-container" 
         style="position: fixed; width: 400px; max-height: 700px;">
        PROJECTS
    </div>
</div>

The pin-spacer doubles your element's height in the document flow. On a 700px viewport, a 100vh element becomes 1400px of scroll space.

2. Forces `position: fixed`

During the pin phase, your element gets position: fixed. This removes it from document flow and places it in its own stacking context. Any content behind or after it can bleed through.

3. Recalculates Dimensions at Init Time

GSAP measures your element's dimensions once during initialization. If your layout changes after init (fonts loading, images rendering, dynamic content), the pin-spacer dimensions are wrong.

My Debug Journey

I initially tried the obvious fixes:

Attempt 1: z-index (Failed ❌)

.experience-section { z-index: 5; }
.kinetic-container { z-index: 2; }

Why it failed: z-index only works between elements in the same stacking context. GSAP's position: fixed creates a new stacking context. The z-index values were comparing apples to oranges.

Attempt 2: Increased padding (Failed ❌)

.experience-section {
    padding: 100px 20px 160px; /* Extra bottom padding */
}

Why it failed: More padding = taller section = worked on desktop. But on mobile (400px wide), text wraps more → section is even taller → the pin triggers at the wrong scroll position anyway.

Attempt 3: Hide content with opacity before pin (Partial ✅)

gsap.set([textEl, ...lines, ...circles], { opacity: 0 });

// Elements start hidden, GSAP reveals them
tl.fromTo(lines,
    { height: "0%", opacity: 0 },
    { height: "100%", opacity: 1, ... }
);

Result: The text was hidden, but the pin-spacer still existed — creating a 1400px empty gap. Users scrolled through work history, hit an empty black void, then saw PROJECTS, then another gap, then Portfolio. The layout was broken in a new way.

The Fix: Remove pin entirely

After 3 days of fighting GSAP's pin behavior, I realized the answer was to stop fighting it:

// ❌ Before — GSAP ScrollTrigger with pin
const tl = gsap.timeline({
    scrollTrigger: {
        trigger: container,
        start: "top top",
        end: "+=100%",
        pin: true,      // Creates pin-spacer, forces position: fixed
        scrub: 1,
    }
});

// ✅ After — GSAP ScrollTrigger without pin
const tl = gsap.timeline({
    scrollTrigger: {
        trigger: container,
        start: "top 85%",   // Animate when 85% into viewport
        end: "top 10%",     // Complete by time it reaches top 10%
        scrub: 0.8,         // Smooth scroll-driven animation
        // NO pin — element scrolls naturally
    }
});

The key insight: you don't need pin for scroll-driven animations. scrub without pin gives you scroll-linked animation while keeping the element in normal document flow. No pin-spacer. No stacking context issues. No height miscalculations.

Premium Animation Without Pin

Removing the pin didn't mean sacrificing visual quality. I upgraded the animation with character-level splitting:

// Split text into individual characters
const characters = text.split('');

return (
    <div className="kinetic-chars-wrapper">
        {characters.map((char, i) => (
            <span key={i} className="kinetic-char">{char}</span>
        ))}
    </div>
);

// Scroll-driven character animation (no pin)
const tl = gsap.timeline({
    scrollTrigger: {
        trigger: container,
        start: "top 85%",
        end: "top 10%",
        scrub: 0.8,
    }
});

// Horizontal reveal line sweeps across
tl.to(hLine, { scaleX: 1, duration: 0.3 });

// Characters fly in one by one with 3D rotation
tl.to(chars, {
    y: 0, opacity: 1, rotateX: 0, scale: 1,
    duration: 0.5, stagger: 0.04, ease: "back.out(1.4)"
}, "<0.15");

// Geometric circles expand with rotation
tl.to(circles, {
    opacity: 0.6, scale: 1, rotation: 90,
    duration: 0.5
}, "<0.1");

The result is actually more impressive than the pinned version — each letter animates individually as you scroll, creating a premium kinetic typography effect.

CSS Architecture for Scroll Animations

The CSS is where the real magic happens. Key techniques:

/* Character split: 3D perspective entrance */
.kinetic-chars-wrapper {
    perspective: 800px;
}

.kinetic-char {
    display: inline-block;
    font-size: clamp(3rem, 14vw, 12rem);
    font-weight: 900;
    color: #ccff00;
    will-change: transform, opacity;
    transform-origin: center bottom;
    text-shadow:
        0 0 40px rgba(204, 255, 0, 0.15),
        0 0 80px rgba(204, 255, 0, 0.05);
}

/* Horizontal reveal line with gradient */
.kinetic-hline {
    width: 100%;
    height: 2px;
    background: linear-gradient(90deg,
        transparent, rgba(204, 255, 0, 0.8), transparent);
    transform: scaleX(0);
    transform-origin: center;
}

/* Responsive: smaller screens need shorter transitions */
@media (max-width: 768px) {
    .kinetic-container { height: 50vh; }
    .kinetic-char { font-size: clamp(2.5rem, 12vw, 5rem); }
}

Important: Every animated element starts with opacity: 0 in CSS as a safety net, with GSAP handling the reveal.

Performance Comparison

Metric	Pin Approach	Scroll-Driven (No Pin)
Pin-spacer DOM nodes	2 extra	0
Elements with `position: fixed`	1 (during pin)	0
Scroll height added	+100vh per pin	0
Mobile layout issues	⚠️ Common	✅ None
`ScrollTrigger.refresh()` needed	Yes, after async content	No
Compositing layers created	3-5	1-2
Cross-browser consistency	⚠️ Safari varies	✅ Consistent
Animation visual quality	Good	Better (character split)

When You SHOULD Use `pin: true`

To be fair, pin: true isn't always bad. Use it when:

Full-page takeover — Interactive storytelling where you literally need the viewport to "pause" on a section
Video sync — Scrubbing through a video that should fill the viewport
Step-by-step reveals — Wizards or onboarding flows where each step takes the full screen
Known viewport — Kiosk displays or embedded widgets with fixed dimensions

Don't use it for:

Section dividers/transitions
Text reveals between content sections
Any layout where the preceding section has dynamic height
Mobile-first designs (pin-spacer dimensions are unreliable)

5 Key Takeaways

pin: true creates invisible DOM elements (pin-spacer) that break your layout math
z-index doesn't fix stacking context issues caused by position: fixed
scrub without pin gives you scroll-driven animation without layout conflicts
Test on real mobile devices — DevTools responsive mode doesn't always trigger the same GSAP calculations
Character-level animation (splitting text into spans) looks MORE premium than a simple fade, and doesn't require pinning

FAQ

Q: Does GSAP ScrollTrigger's pin: true work reliably on mobile browsers?

A: Not always. GSAP's pin: true creates a pin-spacer wrapper that doubles the element's height in the document flow. On mobile browsers (particularly Safari iOS and Chrome Android), this can cause scroll position miscalculations due to dynamic viewport height changes (URL bar hiding/showing), font loading shifts, and dynamic content that changes section heights after ScrollTrigger initialization. For mobile-first designs, use scrub without pin for more reliable behavior.

Q: What's the best alternative to GSAP pin for scroll animations in React?

A: Use GSAP ScrollTrigger with scrub (no pin) combined with IntersectionObserver. Set start: "top 85%" and end: "top 10%" to create a scroll-driven animation window. The element stays in normal document flow — no pin-spacer, no position: fixed, no stacking context conflicts. For even simpler cases, CSS @scroll-timeline (where supported) or the Web Animations API with ScrollTimeline are native alternatives.

Q: How do you create character-level animation without a library?

A: Split your text into individual <span> elements with JavaScript: text.split('').map(char => <span>{char}</span>). Apply CSS transform-origin: center bottom and perspective on the parent. Use GSAP's stagger property to animate each character sequentially. The back.out(1.4) easing creates a satisfying overshoot effect. Set will-change: transform, opacity on each span for GPU-accelerated compositing.

I'm Nguyễn Xuân Hải, a Fullstack Developer building production web apps with React, .NET Core & AI in Ho Chi Minh City. Check out my portfolio or connect on LinkedIn.

🔗 See the fix in action: hailamdev.space — scroll through Experience → PROJECTS → Portfolio
📦 Source code: github.com/xuanhai0913/My-Portfolio-NXH

My React Portfolio SEO Checklist: From 0 to Rich Results in 48 Hours

Nguyen Xuan Hai — Thu, 02 Apr 2026 01:35:13 +0000

The Problem with React & SEO

Here's the dirty secret: Google can render JavaScript. But most developers still treat React SPAs as SEO-unfriendly. The real issue isn't rendering — it's the missing fundamentals.

I audited my portfolio at hailamdev.space and went from zero structured data to passing Google's Rich Results Test in 48 hours. Here's my exact checklist.

The Complete Checklist

1. Meta Tags (index.html)

Every React SPA needs these in public/index.html:

<!-- Primary Meta Tags -->
<title>Your Name — Role | Tech Stack</title>
<meta name="description" 
  content="[155 chars max] Specific description with keywords and metrics" />
<meta name="robots" content="index, follow" />

<!-- Open Graph -->
<meta property="og:type" content="website" />
<meta property="og:url" content="https://yourdomain.com/" />
<meta property="og:title" content="Same as title tag" />
<meta property="og:description" content="Same as meta description" />
<meta property="og:image" content="https://yourdomain.com/og-image.jpg" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />

<!-- Twitter Card -->
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:title" content="Same as title tag" />
<meta name="twitter:description" content="Same as meta description" />
<meta name="twitter:image" content="https://yourdomain.com/og-image.jpg" />

<!-- Canonical URL (prevents duplicate content) -->
<link rel="canonical" href="https://yourdomain.com/" />

Pro tip: Keep your title under 60 characters and description under 155 characters. Google truncates anything longer in SERPs.

2. Structured Data (JSON-LD) — The #1 Thing Most Portfolios Miss

Structured data tells Google exactly what your page is about. Without it, Google is guessing:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Person",
  "name": "Your Name",
  "url": "https://yourdomain.com",
  "image": "https://yourdomain.com/images/profile.png",
  "jobTitle": "Fullstack Developer",
  "worksFor": {
    "@type": "Organization",
    "name": "Freelance"
  },
  "sameAs": [
    "https://github.com/yourusername",
    "https://www.linkedin.com/in/yourusername/",
    "https://dev.to/yourusername"
  ],
  "knowsAbout": ["React", ".NET Core", "Node.js", "AI Integration"],
  "address": {
    "@type": "PostalAddress",
    "addressLocality": "Your City",
    "addressCountry": "Your Country"
  }
}
</script>

For my portfolio at hailamdev.space, I added 6 schemas total:

Schema	Purpose
`Person`	My identity — name, role, skills, social profiles
`WebSite`	Site info + sitelinks search box eligibility
`BreadcrumbList`	Navigation paths for Google
`ProfilePage`	Signals this is a personal profile page
`ItemList`	Project listings structured as an ordered list
`FAQPage`	Common questions about my work (AI search gold mine)

3. FAQPage Schema — The AI Search Secret Weapon

This is the most underrated SEO technique for 2025. AI search engines (ChatGPT, Perplexity, Google AI Overviews) extract FAQ content at 3x the rate of regular paragraphs.

Why? Because FAQ format is already structured as question→answer pairs — exactly what AI models need.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "What technologies does [Your Name] specialize in?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "I specialize in React, .NET Core, Node.js, and AI integration with Google Gemini and Deepseek LLM. I have shipped 9+ production projects including 3 commercial platforms in Vietnam."
      }
    },
    {
      "@type": "Question",
      "name": "How to add an AI chatbot to a React portfolio website?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "I integrated a Google Gemini-powered AI assistant into my React portfolio at hailamdev.space. The implementation uses the Gemini 2.0 API with a custom system prompt containing portfolio context, enabling visitors to ask about skills, projects, and availability in real-time."
      }
    },
    {
      "@type": "Question",
      "name": "What makes a good developer portfolio in 2025?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "A standout developer portfolio in 2025 should include: real commercial projects with measurable impact, AI-powered interactive features, structured data for SEO, responsive design with smooth animations, and clear calls-to-action."
      }
    }
  ]
}
</script>

The key insight: Write each answer as a self-contained, 40-60 word block. This is the optimal length for AI citation according to the Princeton GEO Study (KDD 2024).

4. robots.txt — Don't Forget AI Bots

Most robots.txt files only handle Googlebot. In 2025, you need to explicitly allow AI search bots — otherwise they literally cannot cite your work:

User-agent: *
Allow: /

# Block sensitive paths
Disallow: /src/
Disallow: /node_modules/
Disallow: /.git/
Disallow: /.env

# ============================================
# AI Search Bots — Allow for citation
# ============================================

User-agent: GPTBot
Allow: /

User-agent: ChatGPT-User
Allow: /

User-agent: Google-Extended
Allow: /

User-agent: PerplexityBot
Allow: /

User-agent: ClaudeBot
Allow: /

User-agent: anthropic-ai
Allow: /

User-agent: Bingbot
Allow: /

# Sitemap
Sitemap: https://yourdomain.com/sitemap.xml

Many developers don't realize: if your robots.txt blocks GPTBot (some default configs do), then ChatGPT will never cite your portfolio — no matter how great your content is.

5. XML Sitemap

For a React SPA with few routes, keep it simple:

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:image="http://www.google.com/schemas/sitemap-image/1.1">

  <url>
    <loc>https://yourdomain.com/</loc>
    <lastmod>2025-04-01</lastmod>
    <changefreq>weekly</changefreq>
    <priority>1.0</priority>
    <image:image>
      <image:loc>https://yourdomain.com/images/og-image.jpg</image:loc>
      <image:title>Your Portfolio Preview</image:title>
      <image:caption>Portfolio showcasing React, .NET and AI projects</image:caption>
    </image:image>
  </url>

  <!-- Add each real route -->
  <url>
    <loc>https://yourdomain.com/assistant</loc>
    <lastmod>2025-04-01</lastmod>
    <changefreq>monthly</changefreq>
    <priority>0.8</priority>
  </url>

</urlset>

Submit this through Google Search Console for fastest indexing.

6. Noscript Fallback — Your SEO Safety Net

Google can render JavaScript… usually. But it uses a two-phase indexing process: crawl → render queue → index. The render queue can take days.

A <noscript> fallback gives crawlers your full content immediately:

<noscript>
  <header>
    <h1>Your Name — Fullstack Developer</h1>
    <nav>
      <a href="#about">About</a> |
      <a href="#portfolio">Portfolio</a> |
      <a href="#contact">Contact</a>
    </nav>
  </header>

  <main>
    <section id="about">
      <h2>About Me</h2>
      <p>Your Name is a Full-Stack Developer based in Your City,
         specializing in React, .NET Core, and AI integration.
         9+ projects shipped to production.</p>
    </section>

    <section id="portfolio">
      <h2>Projects</h2>
      <article>
        <h3>Project Name</h3>
        <p>Description. Technologies: React, .NET Core, SQL Server.</p>
        <a href="https://project-url.com">Visit Site</a>
      </article>
      <!-- Repeat for ALL projects -->
    </section>

    <section id="contact">
      <h2>Contact</h2>
      <ul>
        <li>Email: <a href="mailto:you@email.com">you@email.com</a></li>
        <li>LinkedIn: <a href="https://linkedin.com/in/you">linkedin.com/in/you</a></li>
        <li>GitHub: <a href="https://github.com/you">github.com/you</a></li>
      </ul>
    </section>
  </main>
</noscript>

Important: This must contain your complete portfolio content — not just "Enable JavaScript to view this site." Every section, every project, every link.

7. Image Alt Texts — Small Change, Big Impact

Every <img> tag needs a descriptive alt text. Not just the filename or project name:

// Bad — meaningless to search engines
<img src="screenshot.png" alt="screenshot" />
<img src="project-img.png" alt="Project Title" />

// Good — descriptive, includes technology keywords
<img 
  src="project-img.png" 
  alt="Great Link Mai House — ASP.NET Core, SQL Server, C# project screenshot" 
/>

In React/JSX, you can dynamically generate descriptive alt text:

// Dynamic alt text with project name + technologies
const altText = `${project.title} — ${project.technologies.join(', ')} project screenshot`;
// Output: "Great Link Mai House — ASP.NET Core, SQL Server, C# project screenshot"

This small change has two benefits:

Google Image Search can now index your project screenshots
Visually impaired users using screen readers get useful descriptions

8. Performance: Preload & Preconnect

Slow sites rank lower. These <link> tags in <head> make critical resources load faster:

<!-- Preconnect to CDNs you depend on -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="preconnect" href="https://res.cloudinary.com">

<!-- Preload your hero/LCP image -->
<link rel="preload" as="image" href="/images/hero.webp">

<!-- Defer non-critical CSS (like icon fonts) -->
<link rel="stylesheet" 
      href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/all.min.css" 
      media="print" 
      onload="this.media='all'" />

The media="print" onload="this.media='all'" trick defers CSS loading without blocking the initial render. This technique alone improved my LCP by 0.8 seconds.

9. Bilingual hreflang Tags

If your portfolio targets multiple language audiences (like mine — Vietnamese + English):

<link rel="alternate" hreflang="en" href="https://yourdomain.com/" />
<link rel="alternate" hreflang="vi" href="https://yourdomain.com/" />
<link rel="alternate" hreflang="x-default" href="https://yourdomain.com/" />

This tells Google: "This page serves both English and Vietnamese speakers." Without it, Google might only index your page for one language.

10. AI-Extractable Content Blocks

This is my personal addition based on the Princeton GEO study. Write key content blocks in third person and self-contained:

Bad — First person, AI can't extract without context:
"I build production web apps with React and .NET Core."

Good — Third person, self-contained, AI can cite this standalone:
"Nguyễn Xuân Hải is a Full-Stack Developer based in Ho Chi Minh City, 
Vietnam, specializing in React, .NET Core, and AI integration. 
He has shipped 9+ production projects, including 3 commercial platforms."

Why third person? When ChatGPT or Perplexity extracts your content, they need text that makes sense without your page context. "I build apps" means nothing out of context. "Nguyễn Xuân Hải builds apps" is instantly citable.

My Results After 48 Hours

Test	Before	After
Google Rich Results Test	Fail	6 schemas valid
Lighthouse SEO Score	82	100
Structured Data Schemas	0	6 (Person, WebSite, FAQ, etc.)
AI Bot Access (robots.txt)	0 bots	7 bots explicitly allowed
Noscript Fallback	None	Full content (8 projects, bio, contact)
Image Alt Coverage	~60%	100%
OG/Twitter Preview	Broken	Rich preview on all platforms
hreflang Tags	None	3 (en, vi, x-default)

The Order Matters

If you're starting from scratch, do these in order:

1. Meta tags + OG tags        → 30 minutes
2. JSON-LD Person schema      → 30 minutes  
3. FAQPage schema             → 20 minutes
4. robots.txt (with AI bots)  → 10 minutes
5. XML sitemap                → 15 minutes
6. Noscript fallback          → 45 minutes (longest, most tedious)
7. Image alt texts            → 20 minutes
8. Preload/preconnect         → 10 minutes
9. hreflang                   → 5 minutes
10. AI-extractable blocks     → 30 minutes
═══════════════════════════════════════
Total:                        ~3.5 hours

You can do this in a single afternoon. No excuses.

Tools to Validate

After implementing, test with these free tools:

Tool	What It Tests	URL
Google Rich Results Test	Structured data validity	search.google.com/test/rich-results
PageSpeed Insights	Core Web Vitals	pagespeed.web.dev
Google Search Console	Indexing status	search.google.com/search-console
Meta Tags Debugger	OG/Twitter preview	metatags.io
Schema Markup Validator	JSON-LD syntax	validator.schema.org

FAQ

Q: Does Google actually index React single-page applications?

A: Yes, Googlebot can render JavaScript since 2019. However, it uses a two-phase indexing process — crawl first, then queue for rendering, then index. This render queue can delay indexing by hours or days. Adding a noscript fallback with full content gives crawlers your content immediately without waiting, resulting in faster indexing and more reliable coverage.

Q: How many JSON-LD schemas should a developer portfolio have?

A: For a developer portfolio, I recommend 5-6 schemas: Person (your identity), WebSite (site metadata), ProfilePage (page type signal), ItemList (your projects as a structured list), FAQPage (common questions for AI search extraction), and optionally BreadcrumbList for navigation. Each schema helps both Google and AI search engines understand different aspects of your portfolio content.

Q: Do AI search engines like ChatGPT actually use robots.txt?

A: Yes. OpenAI's GPTBot, Perplexity's PerplexityBot, and Anthropic's ClaudeBot all respect robots.txt directives. If your robots.txt blocks these bots (which some default configurations do), AI search engines cannot crawl your content and will never cite your work in their generated answers. Explicitly allowing AI bots is one of the highest-impact, lowest-effort SEO changes you can make in 2025.

Q: Is the noscript fallback really necessary if Google can render JavaScript?

A: The noscript fallback serves three purposes: faster initial indexing (no render queue delay), a safety net for rendering failures (Googlebot's renderer occasionally fails on complex JavaScript), and content for non-Google crawlers that may not render JavaScript at all (including some AI bots). It takes 45 minutes to implement and eliminates an entire category of indexing risk.

I'm Nguyễn Xuân Hải, a Fullstack Developer building production web apps with React, .NET Core & AI in Ho Chi Minh City.

Check out my portfolio or connect on LinkedIn.

See this checklist in action: hailamdev.space

My other articles:

How I Built an AI-Powered Portfolio Assistant with Google Gemini

Nguyen Xuan Hai — Wed, 01 Apr 2026 13:36:05 +0000

How I Built an AI-Powered Portfolio Assistant with Google Gemini

TL;DR: I built an AI assistant into my portfolio at hailamdev.space that can answer questions about my skills, projects, and experience — powered by Google Gemini 2.0. Here's exactly how I did it.

The Problem

As a Fullstack Developer based in Ho Chi Minh City, Vietnam, I wanted my portfolio to stand out. Traditional portfolios are passive — visitors scroll, look at screenshots, and leave. I wanted something interactive.

What if recruiters and potential clients could ask questions about my experience and get instant, intelligent answers?

The Architecture

User Question → Intent Detection (local) → Gemini API → Structured Response → Rich UI Card

Key Components

Intent Detection Layer — Detects common patterns locally before hitting the API
System Prompt Engineering — Provides Gemini with full context about my profile, projects, and skills
Structured Output — Gemini returns JSON with answer, highlights, quickFacts, skillsMatrix
Rich Response Cards — React components render structured data beautifully

Tech Stack

Component	Technology
Frontend	React + CSS (Brutalist theme)
AI Model	Google Gemini 2.0 Flash
Hosting	Vercel
Animations	GSAP + Three.js
Analytics	Google Analytics 4

Intent Detection — Saving API Calls

Before calling Gemini, I detect common intents locally:

// chatIntents.js - Local intent detection
export const detectIntent = (message) => {
  const lower = message.toLowerCase();

  if (/cv|resume|download/.test(lower)) return 'cv';
  if (/contact|email|hire/.test(lower)) return 'contact';
  if (/project|portfolio|work/.test(lower)) return 'projects';
  if (/skill|technology|stack/.test(lower)) return 'skills';

  return null; // Falls through to Gemini
};

This handles ~40% of questions without API calls, reducing latency and costs.

Structured Prompt Engineering

The secret sauce is the system prompt. Instead of letting Gemini generate free-form text, I instruct it to return structured JSON:

const systemPrompt = `
You are an AI assistant for Nguyễn Xuân Hải's portfolio.
Always respond in JSON format:
{
  "answer": "Natural language answer",
  "highlights": ["Key point 1", "Key point 2"],
  "quickFacts": [{"label": "Experience", "value": "2+ years"}],
  "skillsMatrix": [{"skill": "React", "level": "advanced", "evidence": "5+ projects"}]
}
`;

This gives me full control over the UI while letting Gemini handle the intelligence.

Features I'm Proud Of

1. Multi-Language Support

The assistant handles both Vietnamese and English seamlessly, detecting language from user input.

2. Job Description Analysis

HR recruiters can upload a JD and the assistant analyzes fit against my profile — showing matching skills, gaps, and recommendations.

3. Slash Commands

Power users can use commands like /cv, /pdf, /clear for quick actions.

4. Response Styles

Users can switch between brief, detailed, and fit modes for different use cases.

Results

Since deployment:

Average session duration increased significantly
Recruiters spend more time interacting vs. just scrolling
The assistant handles questions I'd normally answer via email

Try It Yourself

Chat with my AI Assistant — ask it anything about my skills, projects, or availability.

Full Portfolio — explore my projects, experience, and 3D animations.

About the Author

Nguyễn Xuân Hải is a Fullstack Developer based in Ho Chi Minh City, Vietnam, specializing in React, .NET Core, Node.js, and AI integration. His commercial projects include Great Link Mai House (B2B real estate platform), English Community Hub (educational platform), and VN Media Hub (CMS platform).

📫 Contact: xuanhai0913750452@gmail.com | GitHub | Portfolio

DEV Community: Nguyen Xuan Hai

GSAP ScrollTrigger pin: true Nearly Broke My Portfolio — Here's What I Learned

The Bug That Took 3 Days to Find

The Architecture

What pin: true Actually Does

1. Creates a Pin-Spacer Wrapper

2. Forces position: fixed

3. Recalculates Dimensions at Init Time

My Debug Journey

Attempt 1: z-index (Failed ❌)

Attempt 2: Increased padding (Failed ❌)

Attempt 3: Hide content with opacity before pin (Partial ✅)

The Fix: Remove pin entirely

Premium Animation Without Pin

CSS Architecture for Scroll Animations

Performance Comparison

When You SHOULD Use pin: true

5 Key Takeaways

FAQ

My React Portfolio SEO Checklist: From 0 to Rich Results in 48 Hours

The Problem with React & SEO

The Complete Checklist

1. Meta Tags (index.html)

2. Structured Data (JSON-LD) — The #1 Thing Most Portfolios Miss

3. FAQPage Schema — The AI Search Secret Weapon

4. robots.txt — Don't Forget AI Bots

5. XML Sitemap

6. Noscript Fallback — Your SEO Safety Net

7. Image Alt Texts — Small Change, Big Impact

8. Performance: Preload & Preconnect

9. Bilingual hreflang Tags

10. AI-Extractable Content Blocks

My Results After 48 Hours

The Order Matters

Tools to Validate

FAQ

How I Built an AI-Powered Portfolio Assistant with Google Gemini

How I Built an AI-Powered Portfolio Assistant with Google Gemini

The Problem

The Architecture

Key Components

Tech Stack

Intent Detection — Saving API Calls

Structured Prompt Engineering

Features I'm Proud Of

1. Multi-Language Support

2. Job Description Analysis

3. Slash Commands

4. Response Styles

Results

Try It Yourself

About the Author

What `pin: true` Actually Does

2. Forces `position: fixed`

When You SHOULD Use `pin: true`