@eeaas/core v2.3.1

Easter eggs as a service

A production ready and framework agnostic library to help bring back the magic of easter eggs into every app and website. Built with modern JavaScript.

Features

• 🎯 Framework agnostic
• 🔑 Keyboard sequence triggers
• 🎨 Dynamic CSS injection
• 📜 Dynamic JavaScript injection
• ⚡ Async loading
• 🎮 Manual and automatic triggers

Installation

npm i @eeaas/core

Once installed you can import the utility and start creating your own easter eggs.

Basic Usage

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()

Or without a bundler:

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

For more details see the React Example or the Vanilla JavaScript 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

Egg Methods

Egg Properties

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.