Lunidex

A focused Pokémon workspace for players, trainers, and TCG collectors.

Live app · Repository · Issues

Overview · Features · Quick start · Configuration · Architecture · Deployment

English · Français · Español · Deutsch · Italiano · 日本語 · 한국어 · 中文 · Português

Overview

Lunidex is an independent, open-source npm-workspaces monorepo centered on Pokémon TCG collection tracking, with a Pokédex, team-building utilities, and an account-backed personal workspace.

Lunidex is open-source software distributed under the MIT License. See LICENSE for the complete license text.

The web app covers 1,025 Pokémon across nine generations and supports eight interface locales: English, French, Spanish, German, Italian, Japanese, Korean, and Simplified Chinese. Portuguese is available as a translated repository README, but is not a web UI locale.

Public reference pages work without an account. The personal workspace—favorites, caught Pokémon, teams, quiz progress, TCG collections, wishlists, saved searches, notes, decks, and related features—uses Neon Auth and Neon PostgreSQL when configured and synchronized. Web display preferences use IndexedDB; the Expo app uses AsyncStorage.

Note

Pokémon, Pokémon character names, trademarks, artwork, imagery, and related intellectual property belong to their respective rights holders. Lunidex is an independent fan project and is not affiliated with, endorsed by, sponsored by, or otherwise officially connected with Nintendo, Creatures Inc., GAME FREAK inc., or The Pokémon Company.

Features

Area	What you can do
Pokédex and reference	Browse and filter all 1,025 Pokémon; inspect stats, types, abilities, moves, evolutions, forms, encounters, sprites, and localized species data. Search moves, abilities, and items.
Team and battle lab	Build teams of up to six, analyze type and move coverage, review synergy and roles, compare up to three Pokémon, use the 18-type chart, plan EVs and IVs, calculate breeding outcomes, and run a Gen 9 battle simulator.
Progress and play	Track favorites, caught Pokémon, Living Dex progress, activity, badges, and quiz statistics. Play three quiz challenges across three game modes, including daily runs, and track a Nuzlocke run.
Sharing and social tools	Import and export Showdown teams, share read-only team links, create public profiles, manage friends, view quiz leaderboards, and use account-backed battle rooms.
Pokémon TCG workspace	Browse cards and sets, filter the catalog, compare cards, track owned and wanted cards, review set progress, save searches and notes, build decks, and display upstream price fields when TCGdex provides them.
PWA and persistence	Install the web app as a PWA. The service worker caches the app shell and selected upstream resources for resilient repeat visits, while account data remains behind the server API.
Mobile companion	Use the Expo app on iOS, Android, or the web with shared API clients, types, Zustand state, persistence contracts, translations, and Neon helpers from @primedex/core.

Explore the app

Replace en with any supported locale: en, fr, es, de, it, ja, ko, or zh.

Surface	Route
Home	/en
Pokédex	/en/pokedex
Pokémon detail	/en/pokemon/pikachu
Team builder	/en/team
Type chart	/en/types
Quiz	/en/quiz
Battle simulator	/en/battle
TCG catalog	/en/tcg
TCG collection	/en/tcg/collection
Dashboard	/en/dashboard

Collection, dashboard, social, and other personal surfaces may require an authenticated sync session.

Quick start

Prerequisites

• Node.js 22
• npm and the committed package-lock.json
• Git

Clone the repository, install the workspaces, and start the web app:

git clone https://github.com/teefloo/Lunidex.git
cd Lunidex
npm ci
npm run dev

Open http://localhost:3000. The locale proxy redirects an unprefixed URL to a supported locale such as /en, using the primedex-lang cookie or the browser language when available.

Important

Development and production builds intentionally use webpack: npm run dev runs next dev --webpack, and npm run build runs next build --webpack. Keep the flag even though the Next.js configuration also declares a Turbopack root.

Mobile app

The Expo companion lives in apps/mobile. It currently includes the Pokédex list, search, detail views, favorites, team, account, theme, and language settings. It is not yet at full web feature parity; the remaining web tools stay available in the Next.js app.

Start it from the repository root:

npm run start --workspace=@primedex/mobile

Use the Expo prompt to open iOS, Android, or a web preview. The package also exposes android, ios, and web scripts:

npm run android --workspace=@primedex/mobile
npm run ios --workspace=@primedex/mobile
npm run web --workspace=@primedex/mobile

For mobile-specific environment variables and architecture notes, see the mobile README.

Configuration

No environment variables are required for public reference browsing. Copy the template when enabling optional account, server, contact, push, or development integrations:

cp .env.example .env.local

For the Expo app, use apps/mobile/.env.example as the template:

cp apps/mobile/.env.example apps/mobile/.env

Variable(s)	Scope	Purpose
NEXT_PUBLIC_APP_URL	Web / public	Canonical site and API base URL. Defaults to https://lunidex.app.
NEXT_PUBLIC_NEON_AUTH_URL	Web / public	Neon Auth endpoint used by the browser client.
NEON_AUTH_BASE_URL, NEON_AUTH_JWKS_URL	Server-only	Neon Auth proxy and JWT verification endpoints.
NEON_AUTH_COOKIE_SECRET, NEON_AUTH_JWT_ISSUER, NEON_AUTH_JWT_AUDIENCE	Server-only	Auth cookie protection and JWT validation constraints.
NEON_DATABASE_URL / DATABASE_URL	Server-only	Neon PostgreSQL connection. Vercel's Neon integration supplies DATABASE_URL; local tooling can use NEON_DATABASE_URL.
EXPO_PUBLIC_NEON_AUTH_URL, EXPO_PUBLIC_APP_URL	Mobile / public	Neon Auth and deployed application endpoints used by Expo.
NEXT_PUBLIC_GOOGLE_VERIFICATION	Web / public	Optional Google Search Console verification value.
NEXT_PUBLIC_ENABLE_AGENTATION	Development	Enables the Agentation UI-review overlay when set to true.
NEXT_PUBLIC_VAPID_PUBLIC_KEY	Web / public	Optional browser push subscription key.
VAPID_PRIVATE_KEY, VAPID_SUBJECT	Server-only	Optional server-side push delivery configuration.
RESEND_API_KEY, CONTACT_TO_EMAIL, CONTACT_FROM_EMAIL	Server-only	Optional contact-form email delivery through Resend.
SUPABASE_DB_URL	Migration-only	Source connection used by the retained Supabase-to-Neon export scripts; never a web or mobile runtime variable.

Warning

Never expose connection strings, JWKS settings, cookie secrets, VAPID private material, Resend keys, or migration URLs through NEXT_PUBLIC_*, EXPO_PUBLIC_*, source files, logs, or commits.

Enable Agentation during development

Add this value to .env.local and restart the dev server:

NEXT_PUBLIC_ENABLE_AGENTATION=true

The development helper uses http://localhost:4747; its development origin and CSP support are already configured.

Scripts

Run root commands from the repository root:

Command	Description
npm run dev	Start the Next.js development server.
npm run build	Create a production build.
npm run start	Serve the production build.
npm run lint	Lint web, core, and mobile sources.
npm run typecheck	Type-check the web workspace.
npx tsc --project packages/core/tsconfig.json --noEmit	Type-check @primedex/core.
npm run typecheck --workspace=@primedex/mobile	Type-check the Expo app.
npm run lint --workspace=@primedex/mobile	Lint the Expo app.
npm run db:neon:export	Export the retained source data for migration.
npm run db:neon:import	Apply the Neon schema and import a prepared export.
npm run db:neon:verify	Compare the source and Neon migration result.

Warning

The Neon import and verification commands access external databases. Read neon/AGENTS.md and scripts/neon/AGENTS.md first, and use an approved disposable or staging target.

The CI workflow in .github/workflows/ci.yml runs dependency installation, linting, web and core type-checks, the production build, and the mobile type-check.

Architecture

.
├── src/                 Next.js 16 / React 19 web application
├── packages/core/       @primedex/core shared API clients, types, store, i18n, and helpers
├── apps/mobile/         @primedex/mobile Expo Router companion
├── neon/migrations/     Active Neon PostgreSQL application schema
├── supabase/            Archived Edge Function and historical security material
├── scripts/neon/        Controlled export, import, and verification scripts
├── public/              PWA icons, screenshots, card assets, and static files
└── docs/                Product, design, migration, audit, and implementation notes

Web (Next.js App Router)
  ├── Server and client route components
  ├── TanStack Query ──▶ shared API clients ──▶ PokéAPI + TCGdex
  ├── Zustand ──▶ IndexedDB display preferences
  └── Route Handlers ──▶ Neon Auth + Neon PostgreSQL user workspace

Mobile (Expo Router)
  └── @primedex/core ──▶ AsyncStorage + Neon Auth/API when configured

Key boundaries:

• Web: Next.js 16 App Router, React 19, TypeScript, Tailwind CSS 4, Base UI, Framer Motion, TanStack Query, and the PWA layer.
• Shared core: platform-agnostic domain types, API clients, Zustand store, i18n bundles, Neon helpers, and pure utilities are shared by web and mobile.
• Data access: remote requests go through the centralized API façade in src/lib/api and packages/core/src/api; presentational components do not add ad hoc API clients.
• Persistence: web display preferences use IndexedDB with a browser fallback; native persistence uses AsyncStorage. Authenticated workspace data is synchronized through the Neon API and stored in user_state.
• Platform seam: matching *.ts and *.native.ts adapters keep browser and React Native storage/configuration separate without copying domain logic.
• Localization: locale-prefixed routes and translation bundles support en, fr, es, de, it, ja, ko, and zh.

Important

Lunidex is the visible product name, but primedex, @primedex/core, @primedex/mobile, usePrimeDexStore, storage keys, route slugs, Expo schemes, and bundle identifiers are compatibility-sensitive historical identifiers. Keep them unchanged unless a deliberate migration is part of the task.

Data sources and attribution

Source	Used for
PokéAPI REST and GraphQL	Pokémon, species text, stats, types, moves, abilities, evolutions, encounters, and localized names.
PokéAPI sprites	Pokémon and item sprites and related artwork assets.
TCGdex	Pokémon TCG cards, sets, rarities, images, catalog fields, and price fields when supplied upstream.
Neon	Optional authentication, PostgreSQL user state, profiles, friends, leaderboards, battle rooms, and server-backed workspace features.

Upstream availability, localized coverage, images, and price fields can change. Lunidex is not a card marketplace and does not guarantee market valuations or price-history coverage.

The original Lunidex code is distributed under the MIT License in LICENSE. The MIT License does not cover Pokémon intellectual property, artwork, imagery, game data, or other third-party materials; those remain subject to their respective owners and source terms.

Deployment

Lunidex is configured for Vercel and can also run on a host that supports the Next.js server runtime and image optimization.

npm run build
npm run start

For Vercel:

1. Import teefloo/Lunidex into a Vercel project.
2. Configure the Neon Auth values and server-only database connection in Preview and Production.
3. Use the standard Next.js build settings. The committed vercel.json intentionally stays minimal.

The active web runtime uses Neon. Supabase SQL migrations are no longer kept in the repository; this directory now contains only an archived Edge Function and historical security material. The controlled migration scripts are historical tooling and are not part of the web application's authentication or database runtime.

See the Neon migration runbook for the schema, environment boundaries, and validation procedure.

Related docs

• Mobile setup and parity notes
• Product context
• Design system
• Neon migration runbook
• Technical guides (TCGdex, PokéAPI, Next.js, and localization)
• GitHub issues