Frames

epos.frames lets your project open and manage background frames.

These frames are ordinary iframes created by Epos and tracked per project. They are useful when you need a real page context running in the background, not just an HTTP request.

This guide explains when to use them, what Epos manages for you, and the basic lifecycle. For exact signatures, see the Frames API Reference.

Mental Model

Use epos.frames when you need to load a full page in a background iframe.

That is different from other Epos tools:

• Use normal fetch() for simple network requests.
• Use Fetch when page-level CORS blocks a request.
• Use Messaging when you need to talk between your own extension contexts.
• Use epos.frames when the remote page itself needs to exist and run.

So the value here is not data fetching. The value is having a live document, scripts, cookies, storage, and page behavior inside an iframe managed by Epos.

Basic Example

Create a frame, inspect the current list, then remove it:

const frameId = await epos.frames.create('https://example.com')

const frames = await epos.frames.list()
console.log(frames)

await epos.frames.remove(frameId)

create() returns the generated frame id. Use that id for later checks and cleanup.

When It Makes Sense

epos.frames is useful in cases like these:

• you need a real page environment, not just a response body
• you need the target site to run its own scripts inside a document
• you want Epos to manage the iframe lifecycle for your project

If you only need JSON or HTML from a server, a frame is usually the wrong tool. Use fetch() or epos.fetch() instead.

Tracking Frames

You can check whether a frame still exists:

const frameId = await epos.frames.create('https://example.com')

const exists = await epos.frames.has(frameId)
console.log(exists) // true

And you can list all frames opened by the current project:

const frames = await epos.frames.list()

for (const frame of frames) {
  console.log(frame.id, frame.name, frame.url)
}

The returned name is generated by Epos. It is based on your project slug and the target domain.

Passing Custom Attributes

create() accepts a second argument with extra iframe attributes:

const frameId = await epos.frames.create('https://example.com', {
  loading: 'eager',
})

Epos still applies its own default attributes such as src, name, project metadata, allow, and sandbox.

So this argument is best for small additions, not for taking full control over the iframe setup.

Cleanup

Remove frames you no longer need:

const frameId = await epos.frames.create('https://example.com')

// ...do work...

await epos.frames.remove(frameId)

Epos also removes project-owned frames when the project runtime is disposed. Still, it is better to remove them explicitly when your own flow is done.

What Epos Manages For You

When Epos creates a frame, it also handles a few details around it:

• it generates a unique frame id
• it assigns a generated iframe name
• it tags the iframe with project metadata
• it applies default allow and sandbox rules
• it adds a temporary network rule that removes X-Frame-Options for the target hostname

That last part is important because many sites block iframe embedding by default.

When you remove the frame, Epos also removes that temporary network rule.

Practical Rule

Reach for epos.frames only when you need a real background page context.

If the job can be done with fetch(), epos.fetch(), or your normal extension messaging, those options are usually simpler.