How I Built an Offline-First Party Game with Next.js and Capacitor (and Shipped It to Google Play)

A developer shipped Imposter Word, a free pass-the-phone social deduction game for Android, built with Next.js, TypeScript and Capacitor. The game uses a three-tier word provider that tries a Gemini 2.5 Flash Lite call through a server route, falls back to a cached IndexedDB store, then to a bundled word list, keeping the API key server-side and validating that hints never reveal the word. A service worker precaches every route at install time, and the build fails if the route list drifts from the client copy.

I recently shipped Imposter Word , a pass-the-phone social deduction game, to Google Play. Most players get a secret word. One or more imposters get only a vague hint. Everyone gives clues, argues, votes, and tries to catch the imposter before the imposter works out the word. It's a free game, built with Next.js, TypeScript and Capacitor. The interesting part wasn't the game rules. It was making a web stack behave like a native app that works on a train with no signal, then getting it through Google's release process. This post covers the architecture decisions that mattered, the bugs that cost me the most time, and what I'd do differently. Try it: Imposter Word on Google Play https://play.google.com/store/apps/details?id=com.hafizsyedahmedali.imposterword · Source on GitHub https://github.com/HafizSyedAhmedAli/Imposter-Word-Game A party game gets played in cars, cafés, hostels and living rooms with bad Wi-Fi. That gave me three rules: gemini-2.5-flash-lite for word and hint generation, called only from a server route The game engine never talks to the AI or to IndexedDB directly. It only knows a small interface: export interface WordProvider { generateRoundContent category: Category, difficulty: Difficulty, options?: { signal?: AbortSignal; excludeWords?: string ; language?: GameLanguage; }, : Promise<GeneratedRoundContent ; } There are three implementations, tried in order: Here is the shape of the selection function, simplified: async function getRoundContent category, difficulty, language, signal { if navigator.onLine { try { const content = await aiProvider.generateRoundContent category, difficulty, { signal, excludeWords: getRecentWordText , language, } ; void cacheAiWord content ; // best-effort, never blocks the round return content; } catch { if signal?.aborted throw new Error "Round preparation cancelled." ; } } try { return await cacheProvider.generateRoundContent category, difficulty, { language } ; } catch { // fall through to the bundled list } return fallbackProvider.generateRoundContent category, difficulty, { language } ; } Two details made this feel solid: The bundled fallback list deliberately uses generic terms a "sequel" instead of a real movie title so nothing depends on someone else's IP. The Gemini key lives only in a Next.js route handler /api/round/generate and is never prefixed with NEXT PUBLIC , so it can't end up in the client bundle. The client sends only the category, the difficulty and a list of recent words to avoid. The server returns a validated { word, hint } pair, never the raw model output. A few things I'd repeat: responseMimeType: "application/json" , so there's no markdown to strip. if hint.toLowerCase .includes word.toLowerCase { return { valid: false, reason: "Hint reveals the word." }; } This was the hardest part, and the most educational. This layer is for the web/PWA version. The native Android app skips the service worker entirely, because Capacitor already bundles the assets inside the app. A service worker that only caches pages you've already visited isn't offline-first. If a player installs the app and then goes offline, screens they haven't opened yet would be missing. So the service worker precaches the full HTML for every route at install time: js const APP ROUTES = "/", "/setup", "/players", "/round", "/pass", "/game", "/voting", "/results", "/final-results", "/how-to-play", "/privacy", "/settings", "/statistics", ; The service worker can't import TypeScript, so the client has its own copy of that list in lib/app-routes.ts . Two hand-maintained lists will drift, and they did once. So the build script that generates sw.js compares the two and fails the build if they differ. Adding a new screen and forgetting one of the lists is now impossible to ship. The next bug was subtle. In the App Router, moving between screens with <Link or router.push fetches an RSC payload in the background. Offline, that fetch fails, and the transition can hang or end on the browser's "site can't be reached" page. It doesn't reliably fall back to a normal page load. The fix: when the device is offline and the target is a known app route, skip the router and force a real document navigation, which the service worker can answer from its precache: export function navigateInternal target: string, replace = false : boolean { if isOffline || isKnownAppRoute target return false; hardNavigateListeners.forEach listener = listener ; if replace window.location.replace target ; else window.location.assign target ; return true; } Online, this never runs, so normal client-side navigation is untouched. A side effect: a hard navigation tears down the page, including the ambient menu music. The hardNavigateListeners hook lets the music controller note that the music was playing, so the reloaded page resumes it quickly as a continuation instead of replaying the fade-in from silence. navigator.onLine lies inside an Android WebView On the web, navigator.onLine is good enough for a status badge. Inside a Capacitor Android WebView, I saw it stay "online" after Wi-Fi and mobile data were both off. The fix was to use Capacitor's Network plugin on native, which asks Android's ConnectivityManager directly, and keep the browser events only for the web build: // simplified if Capacitor.isNativePlatform { const { Network } = await import "@capacitor/network" ; Network.getStatus .then s = setOnline s.connected ; Network.addListener "networkStatusChange", s = setOnline s.connected ; } The same code ships as a web app and as an Android app, and they have different needs: /api/round/generate works. output: "export" inside the app. A static export can't contain a server route handler. So the mobile build script temporarily renames app/api out of the way, runs next build with NEXT PUBLIC BUILD TARGET=capacitor , and restores the folder in a finally block, whether or not the build succeeded. A failed build that leaves app/api renamed would silently break the next normal build, which is worse than the mobile build failing. The native app has no server of its own, so it calls the deployed web instance through NEXT PUBLIC API BASE URL . That makes the route cross-origin from https://localhost , so it sets CORS headers. If the call fails for any reason, the app falls back to local words like everywhere else. Everything personal stays in IndexedDB through Dexie: settings, statistics, achievements, and a cache of AI words. Two choices paid off: contentSource on a round can then tell the two apart. usageCount and lastUsedAt , and selection prefers words that have never been used, then the least recently used. A long-lived install doesn't keep seeing the same few words. Schema changes go through numbered Dexie migrations. When I added the Roman Urdu language option, existing rows were backfilled to "english" , and the read code also treats a missing language as English in case a migration is only partly applied. For a game with lots of state roles, votes, eliminations, ties, multiple imposters , the pure game logic was worth testing heavily. The rules live in plain TypeScript modules, with hundreds of Vitest unit tests covering role assignment, voting, elimination and results. Playwright covers the flows that need a browser, including an offline-fallback spec that aborts the AI request at the network layer and checks that a round still reaches the pass-the-phone screen from the bundled word list. Building the app was the easy half. These cost me the most time: 1. An optional signing config silently produces an unsigned bundle. My Gradle config only signs the release build if keystore.properties exists. Without it, the build still succeeds, and Play Console then rejects the upload with "All uploaded bundles must be signed". If you gitignore your keystore config, check for it before you build. def hasKeystore = rootProject.file "keystore.properties" .exists // ... release { if hasKeystore { signingConfig signingConfigs.release } } 2. storeFile is relative to the app module. I wrote app/my-key.jks and Gradle looked in app/app/ . The bare filename was right. 3. Java 25 breaks the Gradle version Android uses. Android Studio's bundled JDK was 25, and the build died with "Unsupported class file major version 69". Pointing Gradle at JDK 21 fixed it. Keep that path in a local, uncommitted setting, not in a file other people will clone. 4. I committed my keystore. Early on, a git add . pushed the release keystore and its password file to a public repo, because my .gitignore fix had never been saved on my real machine. I scrubbed the history with git-filter-repo , force-pushed, deleted the tag, and generated a brand-new key. This was only survivable because the app wasn't published yet. After release, a Play signing key is effectively permanent. Add the ignore rules first, and run git status before you commit. 5. New personal accounts must run a closed test. Google requires a number of testers 12 at the time to stay opted in for 14 days before you can request production access. Start recruiting testers before your build is finished. 6. The privacy policy must be real and reachable. Play needs a public URL, and the Data safety form has to match what the app actually does. I made the policy a page inside the app /privacy so it ships with the product. My analytics sends only a handful of explicitly named, coarse events, with autocapture and session recording turned off, and never sends names, words or hints. The policy and the form disclose it anyway. The game is free, with no account, and works offline: Imposter Word on Google Play https://play.google.com/store/apps/details?id=com.hafizsyedahmedali.imposterword . The code is on GitHub https://github.com/HafizSyedAhmedAli/Imposter-Word-Game . If you've shipped a Capacitor app, I'd like to hear what bit you. And if you want a playable word game for your next road trip, grab three friends and give it a go. I'm Syed Ahmed Ali, a full-stack developer building web apps and AI-powered products. You can find me on LinkedIn https://www.linkedin.com/in/syed-ahmed-ali-625523307 and my portfolio http://syedahmedali.com/ .