Image Handler

Moving image rendering into another handler.

Internally, Frog serves an image handler for every Frame at the frame path + /image endpoint. Although it comes with ease, this approach has several limitations:

Making refreshing frames would not be possible as initial frame response is cached indefinitely and image URL would change if the image changes.
If your Frame is heavily composed of different UI elements, browsers might cut a part of image URL that contains the compressed image in the query parameter, making it fail to render.

In order to mitigate that, Frog has .image handler that can be used to serve an image at a static URL.

import { Frog } from 'frog'
 
export const app = new Frog({ title: 'Frog Frame' })
 
app.frame('/', (c) => {
  return c.res({
    image: '/img'
    /* ... */
  })
})
 
app.image('/img', (c) => {
  /* Access frame's state via `c.previousState` */
  return c.res({/* ... */})
})

Since the image URL is static now, you're open to add Cache-Control: max-age=0 header to image response to achieve refreshing initial frame.

import { Frog } from 'frog'
 
export const app = new Frog({ title: 'Frog Frame' })
 
app.frame('/', (c) => {
  return c.res({
    image: '/img'
    /* ... */
  })
})
 
app.image('/img', (c) => {
  /* Access frame's state via `c.previousState` */
  return c.res({
    headers: {
        'Cache-Control': 'max-age=0'
    },
    /* ... */
  })
})

Bonus: Learn the API

You can learn more about the image APIs here: