How xeland314/advent-calendar works
Project type and purpose
• This is a static, front-end–only web application built with Next.js (React) and exported as a static site (GitHub Pages).
• Purpose: an interactive Advent calendar that reveals daily virtual gifts, uses date logic to enable content, includes animations and a countdown timer.
File structure
Top-level:
• .github/workflows/nextjs.yml – CI/CD workflow for build and deployment
• public/ – static assets (manifest.webmanifest, service worker sw.js, pixel-art images)
• src/app/ – Next.js App Router: pages, layout, components, hooks, utilities
• config files – next.config.ts, tailwind.config.ts, jest.config.ts, eslint.config.mjs, tsconfig.json
Under src/app:
• page.tsx, layout.tsx, not-found.tsx – routing and global layout
• components/ – UI building blocks (Header, Footer, Gift, AnimatedBall, Calendar, CountdownTimer, SnowFlake, etc.)
• hooks/ – custom React hooks (useCountdownTimer)
• utils/ – helper functions (getFormattedDate, getFormattedTimeLeft) and tests
• app/coal-gift/page.tsx – a dynamic “gift” page
README for additional insights
• Confirms static export, UI-focused features (animations, date gating), technologies (Next.js, React, Tailwind)
• No backend or API; all logic runs client-side
Main components
A. Build & Deployment Pipeline
• Source code repository (GitHub) → GitHub Actions (“nextjs.yml”) runs npm run build and npm run export → static artifacts
• Deployment to GitHub Pages or CDN
B. Static Hosting Layer
• CDN/Hosting (GitHub Pages) serves index.html, JS bundles, CSS, manifest, service worker, image assets
C. Client (Browser) Runtime
1. Browser requests static assets
2. Service Worker (public/sw.js) registers & caches files for offline support
3. Next.js–generated JavaScript bundles hydrate React on the client
D. React Application Structure
• Layout component – Header, Footer, global CSS
• Page components – Calendar grid (24 Gift components), CoalGift page
• Shared components – AnimatedBall, SnowFlake (decorative), CountdownTimer, Calendar, Gift
• Hooks & Utils – useCountdownTimer (countdown logic), getFormattedDate/TimeLeft (date formatting)
E. Data Flow & User Interaction
• On page load, hook reads system date → calculates available gift indexes
• CountdownTimer component updates every second via hook
Architectural patterns and design principles
• Static Site Generation (SSG) – Next.js export for performance and simplicity
• Component-driven design – small, reusable React components
• Custom hooks for encapsulating stateful logic
• Utility modules for pure functions and date logic
• Client-only logic (no server)