@eeaas/core

Easter eggs as a service

A zero-dependency library to inject easter eggs into any app or website.

Built with modern JavaScript.

Demo

Installation

With npm:

npm i @eeaas/core

Without a bundler (available as window._eeaas):

<script src="https://unpkg.com/@eeaas/core@latest/dist/eeaas.min.js"></script>

Basic Usage

With bundler:

/* index.ts */
import { initializeEeaas } from '@eeaas/core'

// Initialise
const eeaas = initializeEeaas()

// Register eggs, only registered eggs can be activated
eeaas.register({
  name: 'MyEgg',
  onStart() {
    // Do some magic here!
    console.log('Easter egg time...')
  },
  onStop() {
    // Cleanup your harmless easter egg logic
    console.log('So sad...')
  },
})

// Trigger your egg, from anywhere in the app
const egg = eeaas.get('MyEgg')
egg.start()

Without bundler:

<!-- index.html -->
<script src="https://unpkg.com/@eeaas/core@latest/dist/eeaas.min.js"></script>
<script>
  // Initialise
  const eeaas = _eeaas.initializeEeaas();

  // Register eggs, only registered eggs can be activated
  eeaas.register({
    name: 'MyEgg',
    onStart() {
      // Do some magic here!
      console.log('Easter egg time...')
    },
    onStop() {
      // Cleanup your harmless easter egg logic
      console.log('So sad...')
    },
  })

  // Trigger your egg, from anywhere in the app
  const egg = eeaas.get('MyEgg')
  egg.start()
</script>

For more details see the React Example or the Vanilla JS Example.

Building your own egg

You can create quite complex easter eggs, the basic structure of an egg is as follows:

const MyEgg = {
  name: string
  enabled?: boolean
  trigger?: Trigger
  stopTrigger?: Trigger
  resources?: Resource[]
  onStart: (loadedResources: LoadedResource[]) => void | Promise<void>
  onStop: (loadedResources: LoadedResource[]) => void | Promise<void>
}

The Trigger allows you to run code when a user enters a sequence of characters instead of solely relying on the egg.start() method.

Here's the list of valid keystrokes.

Example usage:

trigger: {
  type: 'keys',
  keystrokes: ['n', 'y', 'a', 'n'],
  captureOnInputs: false,
}

This will cause the egg to run its logic when the user enters 'nyan' anywhere, except when the user is actively entering data into an input or textarea - this logic can be toggled with the captureOnInputs flag.

API Reference

Instance Methods

Method	Returns	Description
register(egg: UserEgg)	void	Register a new easter egg
get(name: string)	PublicEgg | undefined	Retrieve an egg instance by name
getInstance()	{ eggs: Record<string, PublicEgg> }	Get the global eeaas instance

Egg Methods

Method	Returns	Description
start()	Promise<void>	Manually activate the egg
stop()	Promise<void>	Manually deactivate the egg
enable()	void	Enable egg triggers
disable()	void	Disable egg triggers

Egg Properties

Property	Type	Required	Default	Description
name	string	Yes	-	Unique identifier for the egg
enabled	boolean	No	true	Whether the egg is initially enabled
trigger	Trigger	No	{ type: 'manual' }	How the egg is activated
stopTrigger	Trigger	No	{ type: 'manual' }	How the egg is deactivated
resources	Resource[]	No	[]	External CSS/JS resources to load
onStart	(resources: LoadedResource[]) => void | Promise<void>	Yes	-	Called when egg is activated
onStop	(resources: LoadedResource[]) => void | Promise<void>	Yes	-	Called when egg is deactivated

Trigger Types

type Trigger =
  | { type: 'manual' }     // Default, activate via start() method
  | { type: 'auto' }       // Activates immediately when enabled
  | {
    type: 'keys'           // Activated by keyboard sequence
      keystrokes: string[] // Array of keys to press
      captureOnInputs?: boolean // Listen on input fields, defaults to true)
    }

Resource Types

type Resource =
  | {
      type: 'css' | 'script'
      content?: string     // Inline CSS/JS
      url?: string         // Local path or external URL to CSS/JS file
    }

Resource Management

Resources are automatically injected and ejected from the DOM when an egg is started/stopped. Resources won't be loaded until start() method is called.