Plugin Lifecycle

onInitialize, onResize, onUnload, and ready() — the complete lifecycle of a plugin from load to teardown

The lifecycle API covers every stage from when a plugin first loads to when it is torn down. Register all lifecycle handlers at the top level of your entry file before any async work.

onInitialize

Registers a handler that fires once when the plugin iframe has loaded and the runtime is ready. The handler receives the plugin's initial attrs, element dimensions, and the current animation state.

handler (function; required). Called with an InitContext object.
Returns void

internote.onInitialize(({ attrs, width, height, animation }) => {
  // attrs      — fully resolved Chalk attribute values
  // width      — initial element width in pixels
  // height     — initial element height in pixels
  // animation  — AnimationState at load time, or null if the scene has no animation

  initRender(attrs, width, height)
  internote.ready()
})

internote.onInitialize(({ attrs, width, height, animation }) => {
  // attrs      — fully resolved Chalk attribute values
  // width      — initial element width in pixels
  // height     — initial element height in pixels
  // animation  — AnimationState at load time, or null if the scene has no animation

  initRender(attrs, width, height)
  internote.ready()
})

JavaScript

Read-only

InitContext

interface InitContext {
  attrs: Record<string, unknown>         // Resolved attribute values
  body: PluginChildElement[] | null      // Children from the {} block
  detail: PluginChildElement[] | null    // Children from the [] block
  width: number                          // Element width in pixels
  height: number                         // Element height in pixels
  elementHash: string                    // Content hash used for storage keying
  animation: AnimationState | null       // Animation state at load time
}

interface InitContext {
  attrs: Record<string, unknown>         // Resolved attribute values
  body: PluginChildElement[] | null      // Children from the {} block
  detail: PluginChildElement[] | null    // Children from the [] block
  width: number                          // Element width in pixels
  height: number                         // Element height in pixels
  elementHash: string                    // Content hash used for storage keying
  animation: AnimationState | null       // Animation state at load time
}

TypeScript

Read-only

The attrs object contains every attribute declared in the manifest, fully resolved. Parameter variables referenced in Chalk (e.g., particles: n) are resolved to their current numeric value before being delivered.

The onInitialize handler can be async. The SDK waits for the returned Promise to resolve before delivering subsequent messages. If the promise rejects, the plugin enters an error state.

ready()

Signals the host that your plugin has rendered its first frame and is ready to be revealed. The host shows a loading indicator until ready() is called.

Returns void

Call ready() inside onInitialize after your initial render is complete — not before painting, and not in a setTimeout. If ready() is not called within five seconds of initialisation, the host times out and shows an error state.

internote.onInitialize(({ attrs, width, height }) => {
  buildUI(attrs, width, height)
  internote.ready()   // Call last, after the frame is painted
})

internote.onInitialize(({ attrs, width, height }) => {
  buildUI(attrs, width, height)
  internote.ready()   // Call last, after the frame is painted
})

JavaScript

Read-only

If your initialisation is async (loading assets, reading from storage), await the work before calling ready():

internote.onInitialize(async ({ attrs, width, height }) => {
  const saved = await internote.storage.get('state')
  buildUI(attrs, width, height, saved)
  internote.ready()
})

internote.onInitialize(async ({ attrs, width, height }) => {
  const saved = await internote.storage.get('state')
  buildUI(attrs, width, height, saved)
  internote.ready()
})

JavaScript

Read-only

onResize

Registers a handler that fires whenever the internote layout causes the plugin element to change size.

handler (function; required). Called with a ResizeContext object.
Returns void

internote.onResize(({ width, height }) => {
  canvas.width = width
  canvas.height = height
  redraw()
})

internote.onResize(({ width, height }) => {
  canvas.width = width
  canvas.height = height
  redraw()
})

JavaScript

Read-only

ResizeContext

interface ResizeContext {
  width: number    // New element width in pixels
  height: number   // New element height in pixels
}

interface ResizeContext {
  width: number    // New element width in pixels
  height: number   // New element height in pixels
}

TypeScript

Read-only

onUnload

Registers a handler that fires when the plugin element is removed from the internote — the student navigated away, the internote was closed, or the educator deleted the element.

handler (function; required). Called with no arguments.
Returns void

Use onUnload to cancel requestAnimationFrame loops, clear timers, disconnect ResizeObserver instances, close WebSocket connections, and free any other resources.

let rafId = null

internote.onInitialize(({ attrs, width, height }) => {
  const loop = () => {
    tick()
    rafId = requestAnimationFrame(loop)
  }
  rafId = requestAnimationFrame(loop)
  internote.ready()
})

internote.onUnload(() => {
  if (rafId !== null) cancelAnimationFrame(rafId)
})

let rafId = null

internote.onInitialize(({ attrs, width, height }) => {
  const loop = () => {
    tick()
    rafId = requestAnimationFrame(loop)
  }
  rafId = requestAnimationFrame(loop)
  internote.ready()
})

internote.onUnload(() => {
  if (rafId !== null) cancelAnimationFrame(rafId)
})

JavaScript

Read-only

onUnload is not guaranteed to fire in all termination scenarios — a browser tab that is killed abruptly will not deliver the message. Do not rely on onUnload as the sole point of data persistence. Use internote.storage during normal operation and treat onUnload as a best-effort cleanup hook.

Full Lifecycle Example

import { internote } from '@internote/plugin-sdk'

let canvas, ctx, rafId, currentAttrs

internote.onInitialize(({ attrs, width, height }) => {
  currentAttrs = attrs

  canvas = document.createElement('canvas')
  canvas.width = width
  canvas.height = height
  document.body.style.margin = '0'
  document.body.appendChild(canvas)
  ctx = canvas.getContext('2d')

  const loop = () => {
    draw(ctx, currentAttrs, canvas.width, canvas.height)
    rafId = requestAnimationFrame(loop)
  }
  rafId = requestAnimationFrame(loop)

  internote.ready()
})

internote.onAttrsUpdate((attrs) => {
  currentAttrs = attrs
})

internote.onResize(({ width, height }) => {
  canvas.width = width
  canvas.height = height
})

internote.onUnload(() => {
  cancelAnimationFrame(rafId)
})

import { internote } from '@internote/plugin-sdk'

let canvas, ctx, rafId, currentAttrs

internote.onInitialize(({ attrs, width, height }) => {
  currentAttrs = attrs

  canvas = document.createElement('canvas')
  canvas.width = width
  canvas.height = height
  document.body.style.margin = '0'
  document.body.appendChild(canvas)
  ctx = canvas.getContext('2d')

  const loop = () => {
    draw(ctx, currentAttrs, canvas.width, canvas.height)
    rafId = requestAnimationFrame(loop)
  }
  rafId = requestAnimationFrame(loop)

  internote.ready()
})

internote.onAttrsUpdate((attrs) => {
  currentAttrs = attrs
})

internote.onResize(({ width, height }) => {
  canvas.width = width
  canvas.height = height
})

internote.onUnload(() => {
  cancelAnimationFrame(rafId)
})

JavaScript

Read-only

On this page

onInitialize ready()onResize onUnload Full Lifecycle Example

Plugin Lifecycle

onInitialize, onResize, onUnload, and ready() — the complete lifecycle of a plugin from load to teardown

The lifecycle API covers every stage from when a plugin first loads to when it is torn down. Register all lifecycle handlers at the top level of your entry file before any async work.

onInitialize

Registers a handler that fires once when the plugin iframe has loaded and the runtime is ready. The handler receives the plugin's initial attrs, element dimensions, and the current animation state.

handler (function; required). Called with an InitContext object.
Returns void

internote.onInitialize(({ attrs, width, height, animation }) => {
  // attrs      — fully resolved Chalk attribute values
  // width      — initial element width in pixels
  // height     — initial element height in pixels
  // animation  — AnimationState at load time, or null if the scene has no animation

  initRender(attrs, width, height)
  internote.ready()
})

internote.onInitialize(({ attrs, width, height, animation }) => {
  // attrs      — fully resolved Chalk attribute values
  // width      — initial element width in pixels
  // height     — initial element height in pixels
  // animation  — AnimationState at load time, or null if the scene has no animation

  initRender(attrs, width, height)
  internote.ready()
})

JavaScript

Read-only

InitContext

interface InitContext {
  attrs: Record<string, unknown>         // Resolved attribute values
  body: PluginChildElement[] | null      // Children from the {} block
  detail: PluginChildElement[] | null    // Children from the [] block
  width: number                          // Element width in pixels
  height: number                         // Element height in pixels
  elementHash: string                    // Content hash used for storage keying
  animation: AnimationState | null       // Animation state at load time
}

interface InitContext {
  attrs: Record<string, unknown>         // Resolved attribute values
  body: PluginChildElement[] | null      // Children from the {} block
  detail: PluginChildElement[] | null    // Children from the [] block
  width: number                          // Element width in pixels
  height: number                         // Element height in pixels
  elementHash: string                    // Content hash used for storage keying
  animation: AnimationState | null       // Animation state at load time
}

TypeScript

Read-only

The onInitialize handler can be async. The SDK waits for the returned Promise to resolve before delivering subsequent messages. If the promise rejects, the plugin enters an error state.

ready()

Signals the host that your plugin has rendered its first frame and is ready to be revealed. The host shows a loading indicator until ready() is called.

Returns void

internote.onInitialize(({ attrs, width, height }) => {
  buildUI(attrs, width, height)
  internote.ready()   // Call last, after the frame is painted
})

internote.onInitialize(({ attrs, width, height }) => {
  buildUI(attrs, width, height)
  internote.ready()   // Call last, after the frame is painted
})

JavaScript

Read-only

If your initialisation is async (loading assets, reading from storage), await the work before calling ready():

internote.onInitialize(async ({ attrs, width, height }) => {
  const saved = await internote.storage.get('state')
  buildUI(attrs, width, height, saved)
  internote.ready()
})

internote.onInitialize(async ({ attrs, width, height }) => {
  const saved = await internote.storage.get('state')
  buildUI(attrs, width, height, saved)
  internote.ready()
})

JavaScript

Read-only

onResize

Registers a handler that fires whenever the internote layout causes the plugin element to change size.

handler (function; required). Called with a ResizeContext object.
Returns void

internote.onResize(({ width, height }) => {
  canvas.width = width
  canvas.height = height
  redraw()
})

internote.onResize(({ width, height }) => {
  canvas.width = width
  canvas.height = height
  redraw()
})

JavaScript

Read-only

ResizeContext

interface ResizeContext {
  width: number    // New element width in pixels
  height: number   // New element height in pixels
}

interface ResizeContext {
  width: number    // New element width in pixels
  height: number   // New element height in pixels
}

TypeScript

Read-only

onUnload

Registers a handler that fires when the plugin element is removed from the internote — the student navigated away, the internote was closed, or the educator deleted the element.

handler (function; required). Called with no arguments.
Returns void

Use onUnload to cancel requestAnimationFrame loops, clear timers, disconnect ResizeObserver instances, close WebSocket connections, and free any other resources.

let rafId = null

internote.onInitialize(({ attrs, width, height }) => {
  const loop = () => {
    tick()
    rafId = requestAnimationFrame(loop)
  }
  rafId = requestAnimationFrame(loop)
  internote.ready()
})

internote.onUnload(() => {
  if (rafId !== null) cancelAnimationFrame(rafId)
})

let rafId = null

internote.onInitialize(({ attrs, width, height }) => {
  const loop = () => {
    tick()
    rafId = requestAnimationFrame(loop)
  }
  rafId = requestAnimationFrame(loop)
  internote.ready()
})

internote.onUnload(() => {
  if (rafId !== null) cancelAnimationFrame(rafId)
})

JavaScript

Read-only

Full Lifecycle Example

import { internote } from '@internote/plugin-sdk'

let canvas, ctx, rafId, currentAttrs

internote.onInitialize(({ attrs, width, height }) => {
  currentAttrs = attrs

  canvas = document.createElement('canvas')
  canvas.width = width
  canvas.height = height
  document.body.style.margin = '0'
  document.body.appendChild(canvas)
  ctx = canvas.getContext('2d')

  const loop = () => {
    draw(ctx, currentAttrs, canvas.width, canvas.height)
    rafId = requestAnimationFrame(loop)
  }
  rafId = requestAnimationFrame(loop)

  internote.ready()
})

internote.onAttrsUpdate((attrs) => {
  currentAttrs = attrs
})

internote.onResize(({ width, height }) => {
  canvas.width = width
  canvas.height = height
})

internote.onUnload(() => {
  cancelAnimationFrame(rafId)
})

import { internote } from '@internote/plugin-sdk'

let canvas, ctx, rafId, currentAttrs

internote.onInitialize(({ attrs, width, height }) => {
  currentAttrs = attrs

  canvas = document.createElement('canvas')
  canvas.width = width
  canvas.height = height
  document.body.style.margin = '0'
  document.body.appendChild(canvas)
  ctx = canvas.getContext('2d')

  const loop = () => {
    draw(ctx, currentAttrs, canvas.width, canvas.height)
    rafId = requestAnimationFrame(loop)
  }
  rafId = requestAnimationFrame(loop)

  internote.ready()
})

internote.onAttrsUpdate((attrs) => {
  currentAttrs = attrs
})

internote.onResize(({ width, height }) => {
  canvas.width = width
  canvas.height = height
})

internote.onUnload(() => {
  cancelAnimationFrame(rafId)
})

JavaScript

Read-only

On this page

onInitialize ready()onResize onUnload Full Lifecycle Example