CornflakeJS

Ephemeral script loader for the web

Load, execute, and auto-cleanup temporary scripts. Perfect for A/B tests, holiday features, hot-fixes, and any code that should expire.

Why CornflakeJS?

• Lightweight - No dependencies, <5KB
• Auto-expiring - Scripts clean themselves up
• Simple - Just JSON configuration
• Safe - Optional sandboxing
• Memory-efficient - Automatic garbage collection

Installation

npm install cornflakejs

Or use via CDN:

<script src="https://unpkg.com/cornflakejs@latest/cornflakejs.js"></script>

Quick Start

Basic Usage

import CornflakeJS from 'cornflakejs';

const cf = new CornflakeJS();

await cf.load({
  "holiday-banner": {
    "code": "console.log('Happy Holidays!')",
    "runTimes": 1,
    "ttl": 3600,
    "trigger": "immediate"
  }
});

Load from URL

await cf.load('https://example.com/config.cfk');

Load from .cfk file

Create a config.cfk file:

{
  "analytics-patch": {
    "code": "https://cdn.example.com/analytics-fix.js",
    "runTimes": 5,
    "ttl": 86400,
    "trigger": "onload",
    "cleanup": true
  },
  "promo-banner": {
    "code": "document.body.insertAdjacentHTML('afterbegin', '<div>Sale!</div>')",
    "runTimes": 1,
    "ttl": 7200,
    "trigger": "immediate"
  }
}

Load it:

await cf.load('./config.cfk');

Configuration Options

CornflakeJS Constructor

const cf = new CornflakeJS({
  autoCleanup: true,
  maxFlakes: 50,
  defaultTTL: 3600,
  verbose: false,
  sandbox: true
});

Flake Configuration

| Field | Type | Default | Description | |-------|------|---------|-------------| | code | string | required | Code to execute or URL to script | | runTimes | number | 1 | Number of times to execute | | ttl | number | 3600 | Time to live in seconds | | trigger | string | "immediate" | When to run: "immediate", "onload", "onevent" | | cleanup | boolean | true | Auto-remove after execution | | priority | number | 0 | Execution order (higher = first) | | sandbox | boolean | true | Run in sandboxed environment |

Use Cases

1. Holiday Features

{
  "christmas-theme": {
    "code": "https://cdn.example.com/christmas-theme.js",
    "ttl": 2592000,
    "trigger": "onload"
  }
}

2. A/B Testing

{
  "experiment-variant-a": {
    "code": "window.showVariantA()",
    "runTimes": 1,
    "ttl": 604800
  }
}

3. Hot Fixes

{
  "bugfix-form-validation": {
    "code": "https://github.com/user/repo/raw/main/fix.js",
    "ttl": 3600,
    "cleanup": true
  }
}

4. Analytics Sampling

{
  "analytics-sample": {
    "code": "trackEvent('page_view')",
    "runTimes": 10,
    "ttl": 86400
  }
}

API Reference

Methods

load(source)

Load flakes from object, JSON string, or URL

await cf.load({...});
await cf.load('{"flake": {...}}');
await cf.load('https://example.com/flakes.cfk');

addFlake(name, config)

Add a single flake

await cf.addFlake('my-flake', {
  code: 'console.log("hi")',
  runTimes: 1
});

executeFlake(name)

Manually execute a flake

await cf.executeFlake('my-flake');

removeFlake(name)

Remove a flake

cf.removeFlake('my-flake');

getFlake(name)

Get flake details

const flake = cf.getFlake('my-flake');
console.log(flake.execCount, flake.status);

getAllFlakes()

Get all active flakes

const allFlakes = cf.getAllFlakes();

clear()

Remove all flakes

cf.clear();

getLogs()

Get execution logs

const logs = cf.getLogs();

Browser Support

• Chrome/Edge 80+
• Firefox 75+
• Safari 13+
• Node.js 12+

Security

⚠️ Important: Only load code from trusted sources. CornflakeJS executes JavaScript code.

• Use sandbox: true for untrusted code
• Validate URLs before loading
• Review .cfk files from external sources
• Consider Content Security Policy

Examples

See the /examples directory for more:

• E-commerce seasonal features
• Progressive feature rollouts
• Temporary marketing campaigns
• Development hot-reloading

Contributing

Contributions welcome! Please read CONTRIBUTING.md

License

MIT License - see LICENSE file