🔑 Borderlands SHiFT Vault

A sleek, Borderlands-themed SHiFT code aggregator for Vault Hunters

🎮 Live Demo • Report Bug • Request Feature

📖 Overview

SHiFT Vault is a modern web application that aggregates and displays SHiFT codes for all Borderlands games. Built with React and TypeScript, it features a custom Borderlands-inspired dark theme with vault gold accents, making it easy for Vault Hunters to find and redeem codes for Golden Keys and other rewards.

📸 Screenshots

✨ Features

🎮 Multi-Game Support - Codes for BL1, BL2, Pre-Sequel, BL3, BL4, and Tiny Tina's Wonderlands
🔍 Smart Filtering - Filter by game and code status (active, expired, unknown)
📋 One-Click Copy - Instantly copy codes to clipboard
🚀 Quick Redeem - Redeem button auto-fills your code on the SHiFT website (no manual paste needed)
🖱️ Middle-Click Redeem - Middle mouse button opens Redeem in a new tab with code pre-filled
🆕 New Today Section - Highlighted section for freshly added codes
⚡ Weekly Auto-Refresh - Automatic data refresh with 7-day cache
🐦 Twitter Integration - Pull codes from @Borderlands, @ShiftCodesTK, and more (manual runs only — see below)
🤖 Reddit Integration - Daily auto-fetch from r/Borderlands4, r/Borderlands, r/borderlands3, r/Borderlandsshiftcodes
🎨 Borderlands Theme - Custom dark theme with vault gold and orange accents
♿ Accessible - ARIA labels and keyboard navigation support
📱 Responsive - Works great on desktop and mobile

🎮 Supported Games

Game	Short Code	Theme Color
Borderlands (GOTY Enhanced)	BL1	Blue
Borderlands 2	BL2	Gold
Borderlands: The Pre-Sequel	TPS	Purple
Borderlands 3	BL3	Orange
Borderlands 4	BL4	Green
Tiny Tina's Wonderlands	TTW	Pink

📡 Data Sources

Codes are aggregated from multiple trusted sources:

MentalMars.com - Comprehensive SHiFT code database (manual import)
Game8.co - Borderlands 4 codes with expiration info (manual runs only; Cloudflare blocks GitHub Actions IPs)
r/Borderlandsshiftcodes - Community-sourced codes from Reddit
r/Borderlands4 - Borderlands 4 community
r/Borderlands - Main Borderlands subreddit
r/borderlands3 - Borderlands 3 community
Twitter - @Borderlands, @ShiftCodesTK, @DuvalMagic (manual runs only; the X API is no longer available)

Only the Reddit scraper runs on a schedule. Reddit is the sole source that currently updates the site automatically. Codes are discovered, never redemption-tested, so no entry claims to be "verified" — always confirm on the official SHiFT site.

🚀 Getting Started

Prerequisites

Node.js (v18 or higher)
npm, yarn, or bun

Installation

# Clone the repository
git clone https://github.com/Manaiakalani/borderlands-loot-hub.git
cd borderlands-loot-hub

# Install dependencies
npm install
# or
bun install

# Start development server
npm run dev
# or
bun dev

The app will be available at http://localhost:5173

Available Scripts

Command	Description
`npm run dev`	Start development server with hot reload
`npm run build`	Build for production
`npm run build:dev`	Build for development
`npm run preview`	Preview production build locally
`npm run lint`	Run ESLint
`npm run test`	Run tests once
`npm run test:watch`	Run tests in watch mode
`npm run test:e2e`	Playwright end-to-end suite
`npm run audit:ci`	Fail on any untriaged production `npm audit` advisory

🏗️ Project Structure

src/
├── components/          # React components
│   ├── ui/             # shadcn/ui components
│   ├── CodeCard.tsx    # Individual code display card
│   ├── CodeList.tsx    # Grid of code cards
│   ├── FilterBar.tsx   # Game and status filters
│   ├── Header.tsx      # App header with stats
│   ├── Footer.tsx      # App footer with links
│   └── NewTodaySection.tsx  # Highlighted new codes
├── config/
│   └── dataConfig.ts   # Data fetching & caching config
├── data/
│   └── shiftCodes.ts   # Type definitions and code data
├── hooks/
│   └── useShiftCodes.ts # Main data hook with caching
├── lib/
│   └── utils.ts        # Utility functions
├── pages/
│   ├── Index.tsx       # Main page
│   └── NotFound.tsx    # 404 page
├── test/               # Test files
├── App.tsx             # App entry with routing
├── main.tsx            # React DOM entry
└── index.css           # Global styles & theme
.github/
└── workflows/
    ├── ci.yml                   # Typecheck, lint, tests, build, E2E (on PRs)
    ├── deploy-pages.yml         # GitHub Pages deployment
    ├── fetch-reddit-codes.yml   # Daily Reddit fetch (the only scheduled scraper)
    ├── fetch-twitter-codes.yml  # Twitter fetch — manual dispatch only
    └── fetch-game8-codes.yml    # Game8 fetch — manual dispatch only
scripts/
├── fetch-twitter-codes.mjs      # Twitter fetch script
├── fetch-reddit-codes.mjs       # Reddit fetch script (4 subreddits)
├── fetch-game8-codes.mjs        # Game8.co fetch script
└── lib/shift-codes-file.mjs     # Shared validation + safe write helper

🎨 Tech Stack

Framework: React 19 with TypeScript
Build Tool: Vite 7 with esbuild minification
Styling: Tailwind CSS with custom Borderlands theme
UI Components: shadcn/ui (Radix primitives)
Icons: Lucide React
State Management: React hooks with a 7-day local cache
Routing: React Router DOM (with lazy-loaded routes)
Testing: Vitest + Testing Library

⚡ Performance

Code splitting — Routes lazy-loaded with React.lazy() + Suspense
Vendor chunking — React and Radix UI split into cacheable chunks
Memoized components — CodeCard, CodeList, FilterBar, NewTodaySection wrapped in React.memo
CSS-driven hover effects — Uses group-hover instead of React state for zero re-renders
Capped animation stagger — Animation delays capped to prevent long delays on large lists
Modern build target — esnext for smaller, more efficient bundles

🔧 Configuration

Twitter Fetch (manual only)

Disabled on a schedule. X/Twitter API access is no longer available for this workflow, so it runs only when dispatched manually from the Actions tab, and only if a TWITTER_BEARER_TOKEN secret is present.

Setup (only needed if you have API access):

Go to your GitHub repo -> Settings -> Secrets and variables -> Actions
Click New repository secret
Name: TWITTER_BEARER_TOKEN
Value: Your Twitter API bearer token (get one here)

Monitored Twitter Accounts:

@Borderlands - Official Gearbox account
@ShiftCodesTK - SHiFT code tracker
@borderlands4HQ - BL4 news & codes
@DuvalMagic - Randy Pitchford (Gearbox CEO)

How it works:

Triggered manually from the Actions tab
Fetches tweets from monitored accounts
Extracts any SHiFT codes found
Validates, then commits new codes to src/data/shiftCodes.ts

Game8 Fetch (manual only)

Disabled on a schedule since 2026-07. Cloudflare began challenging GitHub Actions IPs around 2026-06-17, so game8.co returns a challenge page instead of the article and every scheduled run failed. There is no API to authenticate with. Dispatch it manually to retry; the script exits non-zero if it is still being challenged.

Reddit Auto-Fetch (GitHub Actions)

SHiFT codes are also scraped daily from four Borderlands subreddits. No API keys required — Reddit blocks the unauthenticated .json endpoint from datacenter IPs, so it fetches via Reddit RSS feeds (primary) with PullPush.io as a fallback.

Monitored Subreddits:

r/Borderlands4 - BL4 community codes
r/Borderlands - Main Borderlands subreddit
r/borderlands3 - BL3 community codes
r/Borderlandsshiftcodes - Dedicated SHiFT code subreddit

How it works:

GitHub Actions runs daily at 9 AM UTC
Fetches hot and new posts from all four subreddits
Extracts SHiFT codes using regex pattern matching
Detects game type, reward, and expiration automatically
Deduplicates against existing codes and commits new ones to src/data/shiftCodes.ts
Caps how many codes one unattended run may add, and fails the run if the feeds respond but nothing can be parsed or extracted (so a silent format change is visible rather than looking like a quiet day)
Gates every commit behind tsc, eslint, the full test suite, and a build
You can also trigger it manually from Actions tab

Data Refresh Settings

Configure in src/config/dataConfig.ts:

Setting	Default	Description
`CACHE_DURATION_MS`	7 days	How long to cache data in browser
`STALE_THRESHOLD_MS`	14 days	When to show "data may be outdated" warning
`BACKGROUND_CHECK_INTERVAL_MS`	24 hours	How often to check for updates while app is open

Customizing the Theme

The Borderlands theme is defined in src/index.css. Key CSS variables:

:root {
  --primary: 45 95% 55%;      /* Vault Gold */
  --accent: 25 95% 55%;       /* Orange */
  --success: 142 70% 45%;     /* Active codes */
  --destructive: 0 72% 51%;   /* Expired codes */
  --warning: 45 95% 55%;      /* Unknown status */
}

📋 v1.4.0 Updates (August 2026)

Forced nanoid to 3.3.18, closing Dependabot alert #41 (GHSA-2v37-7h3g-55p8) in production.
Landed the open Dependabot backlog (sonner, typescript-eslint, globals, postcss, puppeteer, jest-dom, eslint-plugin-react-refresh, @types/node).
Added Open Graph image, sitemap lastmod, screenshots, and grouped future npm Dependabot PRs.
Removed a dead React Query vendor chunk that no longer exists in the app.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

📝 License

This project is open source and available under the MIT License.

⚠️ Disclaimer

This project is not affiliated with, endorsed by, or connected to Gearbox Software or 2K Games. Borderlands and SHiFT are trademarks of Gearbox Software. All codes are aggregated from publicly available sources.

🔗 Useful Links

Official SHiFT Website - Redeem your codes here
@Borderlands on Twitter - Official announcements
r/Borderlands - Community discussions

Happy Vault Hunting! 🎯

Made with 💛 for the Borderlands community

FilesExpand file tree

README.md

Latest commit

History