AetherPixel

AetherPixel is a Next.js App Router application that looks up Minecraft players and guilds, then displays Hypixel network and game statistics.

It consumes Mojang and Hypixel APIs on the server, validates responses with Zod, and applies cache profiles to reduce upstream load and repeated calls.

Request/Data Flow

Player stats page (/player/[ign])

1. Resolve IGN to UUID through Mojang API (getUuid)
2. Fetch Hypixel player profile (getPlayer)
3. Fetch current online status (getSession)
4. Fetch guild data (getGuild)
5. Render server components with validated data

Relevant files:

• src/app/(stats)/player/[ign]/page.tsx
• src/lib/hypixel/api/mojang.ts
• src/lib/hypixel/api/player.ts
• src/lib/hypixel/api/online.ts
• src/lib/hypixel/api/guild.ts

Guild member enrichment route (/api/guildmembers)

1. Validate uuid query param
2. Fetch minimal player payload through getPlayerForGuild
3. Return normalized JSON response

Relevant file:

• src/app/(stats)/api/guildmembers/route.ts

External API Usage

Mojang

• Endpoint: GET https://api.mojang.com/users/profiles/minecraft/{ign}
• Purpose: convert player IGN to Mojang UUID
• Implementation: src/lib/hypixel/api/mojang.ts

Hypixel

All Hypixel calls include server-side header:

API-Key: <HYPIXEL_API_KEY>

• GET https://api.hypixel.net/v2/player?uuid={uuid}
  • Used by getPlayer and getPlayerForGuild
• GET https://api.hypixel.net/v2/status?uuid={uuid}
  • Used by getSession
• GET https://api.hypixel.net/v2/guild?player={uuid} (or id/name)
  • Used by getGuild

Implementation files:

• src/lib/hypixel/api/player.ts
• src/lib/hypixel/api/online.ts
• src/lib/hypixel/api/guild.ts

Caching Strategy

This project uses Next.js "use cache" + named cacheLife(...) profiles.

Global profiles are configured in next.config.ts:

Profile	stale	revalidate	expire	Intended use
hypixelApi	60s	30s	5m	Player, status, guild reads
mojangApi	60s	30s	5m	IGN -> UUID lookups
playerWithGuild	24h	24h	7d	Guild member helper lookups

Where profiles are applied:

• getPlayer, getSession, getGuild: apply hypixelApi in production
• getUuid: applies mojangApi in production
• getPlayerForGuild: applies playerWithGuild for guild helper route

Key files:

• next.config.ts
• src/lib/hypixel/api/player.ts
• src/lib/hypixel/api/mojang.ts
• src/lib/hypixel/api/online.ts
• src/lib/hypixel/api/guild.ts

Reliability and Safety Controls

• Server-only secret usage through validated env access (@t3-oss/env-nextjs)
• Zod parsing for API payloads before rendering
• Null-safe return paths for upstream failures and invalid payloads
• Maintenance mode gate (MAINTENANCE_MODE) for temporary disablement

Relevant files:

• src/lib/env/server.ts
• src/lib/schema/player.ts
• src/lib/schema/guild.ts
• src/lib/schema/status.ts

Environment Variables

Required server env values:

• HYPIXEL_API_KEY (required, non-empty)
• MAINTENANCE_MODE (optional, defaults to false)

Defined in:

• src/lib/env/server.ts

Run Locally

bun install
bun run dev

Optional checks:

bun run typecheck
bun run lint
bun run fmt