SDK overview

@freegamestore/games is one npm package. Add it to your game’s web/package.json:

{
  "dependencies": {
    "@freegamestore/games": "^0.13.0",
    "react": "^19",
    "react-dom": "^19"
  }
}

That’s the only required dep beyond React + the storefront brand fonts (loaded via Google Fonts in index.html).

Exports at a glance

Components

Component	When to use
<GameShell>	Required wrapper. Provides layout lock + the SoundProvider that audio hooks read.
<GameTopbar>	The brand-matched topbar. Mount inside GameShell’s topbar prop.
<GameButton>	The brand-matched button. Use for in-game UI to match the topbar style.
<GameAuth>	Sign-in / sign-out button. Drop into the topbar’s actions prop.
<Leaderboard>	Pre-built top/recent scores list.

Hooks

Hook	Returns
useAuth()	{ user, signIn, signOut, loading }
useLeaderboard(gameId)	{ topScores, recentScores, submitScore, loading, refresh }
useSound()	{ muted, toggle } — the platform mute state
useGameSounds()	8 synthesized SFX functions, mute-aware

Types

LeaderboardEntry, User, GameShellProps, GameTopbarProps, GameTopbarStat, GameButtonProps, GameButtonVariant, GameButtonSize, LeaderboardProps.

The one rule

useSound() and useGameSounds() only work when called from a component rendered inside <GameShell>. GameShell mounts the SoundProvider internally. Hooks called above it get a disconnected default that’s permanently muted — and you’ll spend an evening wondering why your audio spy never fires.

The full pattern is documented in Custom audio that respects mute.

Versioning

The SDK is a single semver-pinned package. Breaking changes bump the minor (we’re still pre-1.0). Each scaffolded game pins ^0.13.0 so a minor bump upgrades cleanly. Major bumps surface in the changelog.