konamize

Konami-code easter egg for the web: type ↑ ↑ ↓ ↓ ← → ← → B A and a raptor charges across the page, roaring.

Zero runtime dependencies, written in TypeScript, image and sound bundled — nothing to host, no loader to configure.

Or, if your page has a strict Content-Security-Policy or a bundle budget: import @davalest/konamize/bare, bring your own assets, and nothing but ~2.5 kB of logic reaches your build. See Bring your own assets.

Install

yarn add @davalest/konamize     # or: npm i @davalest/konamize

The bare konamize name on npm belongs to an unrelated 2016 package, hence the scope.

Until then — or to try a local change from the repo that consumes it — any of these work:

| Source | Command (run in the consuming repo) | |---|---| | a sibling checkout | yarn add file:../konamize | | a tarball | npm pack in this repo, then yarn add ../konamize/davalest-konamize-1.1.0.tgz | | git | yarn add davalest/konamize#main | | live editing | yarn link here, then yarn link @davalest/konamize there |

Three things worth knowing about those:

• Yarn Classic copies a file: dependency instead of symlinking it, and copies the whole folder rather than honouring the files field. Re-run the yarn add after every change to the library, or use yarn link while you iterate. The tarball route installs dist/ and nothing else.
• dist/ is not committed. The prepare script builds it, which is what makes the git route work: npm and Yarn run prepare when installing a git dependency.
• Nothing to configure on the consumer side. The image and the sound are inlined as data URIs, so no asset loader, no publicPath, no files to copy. The trade is that your bundler emits that ~154 kB chunk whether or not anyone ever types the code — see Bring your own assets for the entry point that does not.

Wiring it into a React app

The résumé site this grew out of mounts it once, in the component that wraps the whole page:

// src/App.tsx
import {useKonamize} from '@davalest/konamize/react'

function App() {
    useKonamize()

    return (
        <>
            <Header />
            <Profile />
            <Footer />
        </>
    )
}

One instance for the whole app is enough — it listens on window, so it fires anywhere on the page.

That site actually uses @davalest/konamize/react/bare, because its Content-Security-Policy is default-src 'none' with no data: or 'unsafe-inline' exception. That version looks like this:

// src/ui/konamize/useEasterEgg.ts
import {useKonamize} from '@davalest/konamize/react/bare'
import '@davalest/konamize/styles.css'
import raptorImage from '@davalest/konamize/assets/raptor.webp?url'
import raptorM4a from '@davalest/konamize/assets/raptor-sound.m4a?url'
import raptorOgg from '@davalest/konamize/assets/raptor-sound.ogg?url'

export const useEasterEgg = (): void =>
    useKonamize({imageSrc: raptorImage, audioSrc: [raptorM4a, raptorOgg], volume: 0.4})

Quick start

import {konamize} from '@davalest/konamize'

konamize()

That is the whole setup: the key listener is attached, and the first time someone types the Konami code the raptor and its roar are fetched (from a lazy chunk, see Bundle size) and animated in.

The returned handle lets you drive it by hand:

const egg = konamize({autoListen: false})

await egg.go()   // fire it now; resolves when the animation is over
egg.listen()     // start watching the keyboard
egg.stop()       // stop watching, keep the nodes
egg.destroy()    // unhook the listener and remove everything from the DOM

Importing on a server is safe: with no document around, konamize() returns an inert handle instead of throwing.

React

import {useKonamize} from '@davalest/konamize/react'

function App() {
    const {go} = useKonamize()

    return (
        <main>
            <button type="button" onClick={() => void go()}>
                Release the raptor
            </button>
        </main>
    )
}

The hook mounts one instance, cleans it up on unmount, and takes the same options. They are read on mount, so the object needs no memoising; onTrigger is the exception — the latest one is always called. react is an optional peer dependency (17 or newer), only needed for this entry point.

Bring your own assets

Passing imageSrc and audioSrc to the default entry point stops the bundled chunk from being requested. It does not stop it from being emitted: the fallback lives behind a dynamic import(), and a bundler decides what to emit by reading the module graph, not by evaluating the branch that guards it. So the ~154 kB sits in your dist/, gets uploaded, and gets cached — for nothing.

@davalest/konamize/bare is the same easter egg with that fallback removed. Its module graph never reaches the assets, so the chunk is not emitted at all. imageSrc and audioSrc become required, because there is nothing left to fall back to.

import {konamize} from '@davalest/konamize/bare'
import '@davalest/konamize/styles.css'

konamize({
    imageSrc: '/img/raptor.webp',
    audioSrc: ['/audio/roar.m4a', '/audio/roar.ogg'],
    injectStyles: false,
})

Want the raptor itself, just not as base64? It ships as files too:

import raptorImage from '@davalest/konamize/assets/raptor.webp'
import raptorM4a from '@davalest/konamize/assets/raptor-sound.m4a'
import raptorOgg from '@davalest/konamize/assets/raptor-sound.ogg'

Your bundler hashes them and serves them first-party, which is what img-src 'self' and media-src 'self' need.

Entry points

| Import | Assets | React | Notes | |---|---|---|---| | @davalest/konamize | bundled, lazy chunk | — | Zero configuration. Emits the ~154 kB chunk. | | @davalest/konamize/react | bundled, lazy chunk | ✓ | The useKonamize hook. | | @davalest/konamize/bare | yours, required | — | Emits no asset chunk. | | @davalest/konamize/react/bare | yours, required | ✓ | Emits no asset chunk. | | @davalest/konamize/styles.css | — | — | The stylesheet as a file, for injectStyles: false. | | @davalest/konamize/assets/* | — | — | raptor.webp, raptor-sound.m4a, raptor-sound.ogg. |

The split is checked at build time, not assumed: scripts/postbuild.mjs walks each entry point's emitted imports and fails the build if a bare one can reach the asset chunk.

Under a strict Content-Security-Policy

Two of the defaults are things a locked-down page refuses, and both have an opt-out:

| Default | Refused by | Instead | |---|---|---| | Assets as data: URIs | img-src 'self', media-src 'self' | /bare + @davalest/konamize/assets/* | | Stylesheet as an injected <style> | style-src 'self' | injectStyles: false + @davalest/konamize/styles.css |

With both applied, the egg runs under default-src 'none'; script-src 'self'; style-src 'self'; img-src 'self'; media-src 'self' with no exceptions added.

konamize.css is generated from buildStyles() during the build, so it cannot drift from the function. It bakes in the default KONAMI class name — a real stylesheet cannot be parameterised, which is the trade for not needing 'unsafe-inline'. For any other name, call buildStyles() and ship the result yourself.

Options

Everything is optional — except imageSrc and audioSrc on the bare entry points, where both are required.

| Option | Type | Default | What it does | |---|---|---|---| | code | readonly string[] | Konami code | Key sequence to watch, as KeyboardEvent.key values. Case-insensitive. | | imageSrc | string | bundled raptor | Image that charges across the screen. | | audioSrc | string \| readonly string[] | bundled roar (AAC + Ogg) | Sound to play. Several values become several <source> elements. | | className | string | 'KONAMI' | Base class for the injected nodes and keyframes. | | animationTime | number | 2500 | Animation length in ms. The roar starts a third of the way in. | | volume | number | 1 | Playback volume. Clamped to 0–1, since HTMLMediaElement.volume throws outside it. | | container | HTMLElement | document.body | Where the image and audio are appended. | | target | EventTarget | window | Where the keydown listener is attached. | | autoListen | boolean | true | Attach the listener on creation. | | injectStyles | boolean | true | Inject the stylesheet the animation needs. | | respectReducedMotion | boolean | true | Under prefers-reduced-motion, fade the raptor in and out instead of charging. Sound still plays. | | ignoreWhileTyping | boolean | true | Ignore keys typed into inputs, textareas, selects and contenteditable. | | onTrigger | () => void | — | Called on every trigger, before the animation starts. |

Every entry point exports KONAMI_CODE. The root and bare exports add createSequenceMatcher (the key-sequence matcher on its own) and buildStyles (the CSS as a string, for a class name other than the default).

Custom assets

konamize({
    imageSrc: '/img/my-boss.png',
    audioSrc: ['/audio/airhorn.m4a', '/audio/airhorn.ogg'],
    code: ['d', 'a', 'v', 'a', 'l'],
    animationTime: 1800,
})

When you pass both imageSrc and audioSrc, the bundled raptor chunk is never requested — the easter egg costs you nothing but the ~2 kB of logic.

Styling

The injected <style> defines four classes off className (KONAMI by default):

| Class | Applied to | |---|---| | KONAMI | the image, always — fixed to the bottom-right corner, hidden, pointer-events: none | | KONAMI-go | the image while it charges | | KONAMI-static | the image while it fades, under reduced motion | | KONAMI-source | the <audio> element |

The animation reads its duration from the --konamize-duration custom property, set inline from animationTime. Pass injectStyles: false to take over: either import @davalest/konamize/styles.css for the same rules as a real stylesheet, or write your own keyframes against the four class names above.

Bundle size

Measured from dist/ at 1.1.0, entry plus the chunks it pulls:

| What | Raw | Gzipped | |---|---|---| | @davalest/konamize | 5.9 kB | 2.7 kB | | @davalest/konamize/react | 6.5 kB | 3.0 kB | | @davalest/konamize/bare | 5.5 kB | 2.5 kB | | @davalest/konamize/react/bare | 6.1 kB | 2.8 kB | | @davalest/konamize/styles.css | 1.2 kB | 0.5 kB | | raptor + roar chunk | 154 kB | 113 kB |

The asset chunk is only requested when the egg is about to fire, and it is warmed halfway through the sequence so the roar is not late. Nobody who never types the Konami code downloads a dinosaur.

But requested and emitted are different things. The chunk is emitted into your build by the two default entry points regardless — a dynamic import() is a fact about the module graph, and passing imageSrc and audioSrc does not remove it. Earlier versions of this README claimed otherwise; it was wrong. If you do not want those bytes in your dist/, use the bare entry points.

Browser support

Any browser with ES2020, WebP and either AAC-in-MP4 or Ogg Vorbis — in practice, everything current. The package ships ES modules only, which every modern bundler (Vite, webpack 5, Rollup, Parcel, esbuild) consumes directly.

Development

Requires Node 20+ (see .nvmrc). Yarn Classic is the package manager, pinned via packageManager.

yarn install
yarn dev          # playground at http://localhost:5173
yarn test         # Vitest (jsdom)
yarn lint         # ESLint, fails on any warning
yarn build        # type-check, bundle to dist/, emit .d.ts

| Path | What lives there | |---|---| | src/core.ts | the instance: DOM, timers, animation, key handling. Takes its sources as a resolver | | src/konamize.ts | the default entry: resolves to the bundled assets, which is why the chunk exists | | src/bare.ts | the same, with the sources required and no path to src/assets.ts | | src/konami.ts | KONAMI_CODE and the KMP sequence matcher | | src/styles.ts | the CSS, as a function of the class name | | src/assets.ts | the raptor and roar as data URIs, imported lazily by src/konamize.ts only | | src/react-core.ts | the hook body both React entry points share | | src/react.ts / src/react-bare.ts | the two useKonamize exports | | src/types.ts | KonamizeOptions, BareOptions, CoreOptions, Sources | | scripts/postbuild.mjs | emits konamize.css, copies the assets, and verifies the chunk split | | demo/main.ts | the playground yarn dev serves |

yarn build fails if a bare entry point can reach the asset chunk. That check is the only thing standing between the split and a chunking heuristic quietly undoing it, so do not remove it.