Troubleshooting Guide
Relevant source files
The following files were used as context for generating this wiki page:
This guide provides technical insights into diagnosing and resolving issues within the Moe Kyaw Aung Portfolio V2. It focuses on the integration of high-performance animation libraries, 3D rendering components, and smooth scrolling mechanics.
The portfolio architecture relies on a Vite-based React environment utilizing framer-motion, gsap, lenis, and @splinetool/react-spline. Understanding the interplay between these dependencies is critical for maintaining the intended user experience.
Environment and Dependencies
Issues often arise from version mismatches or incorrect environment configurations. The project uses Vite for its build pipeline and dev server.
| Dependency | Purpose | Version |
|---|---|---|
react | UI Framework | ^18.2.0 |
vite | Build Tool / Dev Server | ^4.4.5 |
lenis | Smooth Scrolling | ^1.0.4 |
@splinetool/react-spline | 3D Scene Rendering | ^3.0.20 |
framer-motion | Declarative Animations | ^10.16.4 |
Sources: package.json:12-20, package.json:23-24
Development Server Issues
The development server is configured to run on a specific port. If the port is occupied, the server will fail to start.
- Default Port: 3000
- Configuration File:
vite.config.js
Sources: vite.config.js:4-8
Smooth Scroll (Lenis) Integration
The project implements Lenis for inertial scrolling. If scrolling feels jittery or stops working, the Request Animation Frame (RAF) loop or CSS conflicts are the primary suspects.
Scroll Logic Flow
The scroll engine must be initialized once and updated on every animation frame.
The diagram above illustrates the continuous loop required for Lenis to calculate scroll positions.
Sources: src/App.jsx:7-20
CSS Conflict Resolution
Specific global styles are required to ensure Lenis interacts correctly with the browser's scroll container.
| Selector | Property | Required Value | Reason |
|---|---|---|---|
html.lenis | height | auto | Allows Lenis to control height |
.lenis-smooth | scroll-behavior | auto | Prevents browser interference |
iframe | pointer-events | none | Prevents scroll hijacking during movement |
Sources: src/styles/globals.css:21-36
3D and Animation Troubleshooting
Spline Scene Failures
The Hero3D component loads an external Spline scene. If the 3D element does not appear:
- Check the network for the scene URL:
https://prod.spline.design/f9mXvGfQ6oZ0k8rN/scene.splinecode. - Ensure the container has defined dimensions; the project uses
absolute inset-0 w-full h-full.
Sources: src/components/3D-Hero/Hero3D.jsx:10-13
Animation Performance
framer-motion is used for entry animations. If animations are sluggish:
- Verify that
initialandanimatestates are not conflicting with heavy 3D rendering. - The project utilizes
easeOuttransitions with a1sduration to balance visual impact and performance.
<motion.div
initial={{ opacity: 0, y: 50 }}
animate={{ opacity: 1, y: 0 }}
transition={{ duration: 1, ease: "easeOut" }}
>
Sources: src/components/3D-Hero/Hero3D.jsx:20-24
Component-Specific Issues
Magnetic Button Interactions
The MagneticButton uses react-magnetic with a specific strength. If the button "sticks" or behaves erratically:
- Strength Setting:
0.3 - Implementation: Ensure the
{...bind()}spread is applied to the interactive element.
Sources: MagneticButtom.jsx:4-13
Layout Overflows
Global styles enforce overflow-x: hidden on html and body to prevent horizontal shifts caused by animations or wide 3D scenes. If horizontal scrollbars appear, check for elements exceeding the viewport width in nested components.
Sources: src/styles/globals.css:11-14
Summary
Troubleshooting this portfolio primarily involves verifying the Lenis RAF loop in src/App.jsx, ensuring external assets load correctly in Hero3D.jsx, and maintaining the CSS overrides in globals.css that prevent native browser scroll interference. Most issues are related to the synchronization of the smooth scroll engine and the high-fidelity 3D/animation layers.