🌋🐓 LavaChicken

LavaChicken — is a JavaScript/TypeScript class for safe two-way communication between browser windows (e.g., parent and <iframe>), with support for events, messages, and an automatic connection handshake mechanism.

⚙️ Initialization

In the parent window

import { LavaChicken } from 'lava-chicken'

const lavaChicken = new LavaChicken('shared_sauce')

In the child window (e.g., inside an iframe)

import { LavaChicken } from 'lava-chicken'

const lavaChicken = new LavaChicken('shared_sauce', { isChicken: true })

🧪 API

new LavaChicken(sauce: string, options?: { isChicken?: boolean })

• sauce — unique string used to authenticate both sides.
• options.isChicken — indicates if this instance is a child (true for iframe). By default, it's auto-detected via window.parent !== window.

send(data: any): void

Sends a message to the other side.

lavaChicken.send({ text: 'Hello from parent!' })

trigger(eventName: string, data?: any): void

Sends a named event to the other side.

lavaChicken.trigger('form:submitted', { id: 123 })

onMessage(handler: (data: any) => void): void

Subscribe to incoming messages.

lavaChicken.onMessage((data) => {
  console.log('Received message:', data)
})

on(eventName: string, handler: (data: any) => void): void

Subscribe to specific events.

lavaChicken.on('form:submitted', (data) => {
  console.log('Form submitted with data:', data)
})

onLost(handler: () => void): void

Subscribe to lost connection event. Use only in Lava (parent window)

lavaChicken.onLost(() => {
  console.log('Connection with chicken is lost')
})

destroy(): void

Cleans up all intervals, subscriptions, and window references.

lavaChicken.destroy()

🔄 Connection mechanism

• The child window (iframe) automatically tries to connect to the parent by sending a connect system message every second (up to 10 times).
• The parent responds with connected, if the token matches.
• Once connected, you’ll see Connected! in the console.

📌 Full example

In the parent window:

const lavaChicken = new LavaChicken('tabasco123')

lavaChicken.on('custom:event', (payload) => {
  console.log('Child sent event:', payload)
})

lavaChicken.onMessage((msg) => {
  console.log('Message from child:', msg)
})

In the <iframe>:

const lavaChicken = new LavaChicken('tabasco123', { isChicken: true })

lavaChicken.send({ hello: 'parent' })

lavaChicken.trigger('custom:event', { foo: 'bar' })

❗ Notes

• The sauce value must be identical on both sides.
• Always call destroy() when the connection is no longer needed (e.g., when navigating between pages).

🧩 useLavachicken (Composable)

Global singleton composable for working with LavaChicken. Provides convenient access to a single instance across your app.

import { useLavaChicken } from 'lava-chicken'

const lavaChicken = useLavaChicken()

onMounted(() => {
  lavaChicken.init('secure-sauce', true)

  lavaChicken.send({ hello: 'iframe!' })

  lavaChicken.trigger('currency:selected', { code: 'USD' })

  lavaChicken.on('payment:success', (data) => {
    console.log('Success:', data)
  })

  lavaChicken.onMessage((msg) => {
    console.log('Message received:', msg)
  })
})

API

| Метод | Опис | | ----------------------- | ------------------------------------------------ | | init(sauce, isChicken)| Initializes the single LavaChicken instance | | send(message) | Sends a message | | trigger(event, data?) | Triggers an event with optional data | | on(event, handler) | Listens for an event | | onMessage(handler) | Listens for any message | | onLost(handler) | Listens for lost connection (for parent window) | | destroy() | Destroys the instance and clears all listeners |

🔬 Under the hood

This composable creates a single instance of LavaChicken shared across all components. If init() is not called, all other methods will do nothing.

⚠️ Don’t forget to call destroy() when needed (e.g., when navigating between routes inside an iframe).

🧩 useVueLavaChicken (Vue Composable)

Vue-style composable for using LavaChicken as a singleton. Features:

• auto-initialization on onMounted
• automatic cleanup on onUnmounted
• tracks active component count
• auto destroy, when last component unmounts

Usage

import { useVueLavaChicken } from 'lava-chicken'

const { send, trigger, on, onMessage } = useVueLavaChicken('secure-sauce', true)

onMounted(() => {
  trigger('view:ready')
})

onMessage((data) => {
  console.log('Got message:', data)
})

on('payment:success', (payload) => {
  console.log('Payment succeeded:', payload)
})

⚠️ useVueLavaChicken(sauce) must be called with the same token in all components where you want to use it. It connects/disconnects automatically — no need to manually call init() or destroy().

API

| Method | Description | | ----------------------- | --------------------------------------------- | | send(message) | Sends a plain message | | trigger(event, data?) | Triggers an event with data | | on(event, handler) | Subscribes to an event | | onMessage(handler) | Subscribes to any message | | onLost(handler) | Subscribes to lost connection (parent window) |

Example with v-if:

<template>
  <ChildComponent v-if="showChild" />
</template>

<script setup lang="ts">
const showChild = ref(true)
</script>

// ChildComponent.vue
const { trigger } = useVueLavaChicken('secure-sauce', true)

onMounted(() => {
  trigger('child:ready')
})

// When the component disappears, the internal counter is decreased automatically

🧠 This composable is a smart alternative to using a Pinia store or global singleton. It prevents duplicated instances and fully manages the lifecycle for you.