[RFC] Support for Offscreen Documents #527

jkkrow · 2023-03-31T15:18:01Z

How do you envision this feature/change to look/work like?

The Offscreen API has been added since Chrome 109 version. This solves a problem with the service worker which can't access the DOM or the window interface. It would be great if this feature is natively supported in Plasmo.

As quoted in this link, Manifest V3 extensions are service worker-based, but service workers don't provide support for the same APIs and mechanisms that full document-based pages (which include background and event pages) do. Additionally, using content scripts to access DOM APIs on web pages leaves the extension at the mercy of different content security policies on a page-to-page basis.

Offscreen Documents supports DOM-related features and APIs by allowing Manifest V3 extensions to open minimal, scoped, and relatively un-permissioned offscreen documents at runtime through a dedicated API.

What is the purpose of this change/feature? Why?

The Offscreen API requires a dedicated html page just like other extension pages, so currently it seems impossible to implement this within the Plasmo environment using React and Typescript which automatically bundles the tsx files into html and js.

(OPTIONAL) Example implementations

Like other extension pages or background sw, automatically building an offscreen environment by creating a file named offscreen.ts in a root directory or src folder looks like an ideal implementation.

(OPTIONAL) Contact Details

No response

Verify canary release

I verified that the issue exists in plasmo canary release

Code of Conduct

I agree to follow this project's Code of Conduct
I checked the current issues for duplicate problems.

The text was updated successfully, but these errors were encountered:

dimadolgopolovn · 2023-05-12T10:19:01Z

Is there a workaround to implement this in Plasmo now?

louisgv · 2023-05-12T16:23:17Z

@dimadolgopolovn yeah you can just use it as-is. All low-level chrome API are available at your disposal.

dimadolgopolovn · 2023-05-13T10:33:08Z

Adding the solution here so that people don't waste time on it.

Add offscreen.html and offscreen.js to project root as per Chrome documentation.

offscreen.html:

<!DOCTYPE html>
  <script src="offscreen.js"></script>

background.js:

import OFFSCREEN_DOCUMENT_PATH from 'url:~offscreen.html'

async function createOffscreenDocument() {
  if (!(await hasDocument())) {

    await chrome.offscreen.createDocument({
      url: OFFSCREEN_DOCUMENT_PATH,
      reasons: [chrome.offscreen.Reason.WEB_RTC],
      justification: 'P2P data transfer'
    }).then(e => {
      // Now that we have an offscreen document, we can dispatch the
      // message.
    })
  }
}
createOffscreenDocument()

async function hasDocument() {
  // Check all windows controlled by the service worker if one of them is the offscreen document
  // @ts-ignore clients
  const matchedClients = await clients.matchAll()
  for (const client of matchedClients) {
    if (client.url.endsWith(OFFSCREEN_DOCUMENT_PATH)) {
      return true
    }
  }
  return false
}

jkkrow · 2023-05-14T08:28:18Z

@dimadolgopolovn Thank you for the solution! I struggled to connect the html file to the document and that url import did the trick!

import OFFSCREEN_DOCUMENT_PATH from 'url:~offscreen.html';

It seems I can also use typescript file as a script.

<script src="offscreen.ts" type="module"></script>

anooppoommen · 2023-06-12T08:30:59Z

@jkkrow @dimadolgopolovn Plasmo doesn't seem to pick up the files when compiling how did you add this to the project.

dimadolgopolovn · 2023-06-12T15:20:00Z

@anooppoommen, same as with adding a background.ts. You put it in root and you just need to add “export {}” as the first line.
Plasmo picks up any ts file like this. (that’s what the “~” is there for) There’s official documentation on this.

anooppoommen · 2023-06-12T17:07:47Z

@dimadolgopolovn I tried creating an offscreen.ts file in the root directory and an offscreen.html both these weren't included in the build should I modify something in the package.json too?

jkkrow · 2023-06-12T17:19:55Z

@anooppoommen

You should include "offscreen" to permissions in the package.json.

{
  "permissions": [
    "offscreen",
  ]
}

anooppoommen · 2023-06-12T17:24:27Z

@jkkrow added the permission too but the file doesn't appear in the final build did you add it to the tsconfig or anywhere to let Plasmo pick it up

jkkrow · 2023-06-12T17:38:57Z

@anooppoommen

I didn't set any configuration regarding this. I only put offscreen.ts and offscreen.html in the src directory.

This is my tsconfig.json:

{
  "extends": "plasmo/templates/tsconfig.base",
  "exclude": [
    "node_modules"
  ],
  "include": [
    ".plasmo/index.d.ts",
    "./**/*.ts",
    "./**/*.tsx",
  ],
  "compilerOptions": {
    "paths": {
      "~*": [
        "./src/*"
      ]
    },
    "baseUrl": ".",
    "strictNullChecks": true,
    "ignoreDeprecations": "5.0"
  },
}

This is where I use offscreen in message handler:

import type { PlasmoMessaging } from '@plasmohq/messaging';

import OFFSCREEN_DOCUMENT_PATH from 'url:~src/offscreen.html';

const handler: PlasmoMessaging.MessageHandler = async (req, res) => {
  if (!(await chrome.offscreen.hasDocument())) {
    await chrome.offscreen.createDocument({
      url: OFFSCREEN_DOCUMENT_PATH,
      reasons: [chrome.offscreen.Reason.BLOBS],
      justification: 'Testing',
    });
  }

  res.send('');
};

export default handler;

anooppoommen · 2023-06-12T17:41:08Z

@jkkrow thanks for the example it's really helpful. the issue for me seems to be the tsconfig in my project.

anooppoommen · 2023-06-12T17:44:25Z

adding the sample offscreen.html here for others looking for adding this to their project

<!DOCTYPE html>
<html>
  <head>
    <title>Offscreen</title>
  </head>
  <body>
    <script src="offscreen.ts" type="module"></script>
  </body>
</html>

louisgv · 2023-06-29T11:03:25Z

What should we abstract out for this API? Would love for folks who've played around with this API to chime in. Should we design it like this:

// offscreen.ts

export const config: OffscreenConfig = {} // typed config that get passed down to `chrome.offscreen.createDocument`

// do your offscreen bidding

The above then get compiled into a chrome.offscreen.createDocument call in the default bgsw? The problem is that for folks who want to do dynamic offscreen spawning like #527 (comment), this abstraction is pretty useless :d....

To abstract out the html, you can use the tab-page feature: https://docs.plasmo.com/framework/tab-pages

Make a file in tabs/offscreen.ts -> this generates a tabs/offscreen.html. Then mount it like this:

    await chrome.offscreen.createDocument({
      url: chrome.runtime.getURL("tabs/offscreen.html"),
      reasons: [chrome.offscreen.Reason.BLOBS],
      justification: 'Testing',
    });

jkkrow · 2023-06-30T10:10:54Z

I think creating the offscreen document manually is better for more versatile usage. Let's say if someone needs offscreen documents for different reasons. If the config is bound to offscreen.ts file and run it as a default, we would only have to use offscreen with single reasons option.

In most cases it won't matter, but this option decides different lifespan of offscreen. According to this,

AUDIO_PLAYBACK: Closed after 30 seconds without audio playing.
All other reasons: the lifetime is unbounded (the page can remain open forever).

So I think it would be better to let developers create the offscreen manually, but with abstracted function (Such as checking the existing document before create one).

For example,

import { createOffscreen } from '@plasmohq/offscreen'; 

// This function should check for existing document behind the scene 
await createOffscreen({
  reasons: [chrome.offscreen.Reason.BLOBS],
  justification: 'Testing'
});

Or maybe abstract this further so that document is created only when user request an operation to it.

For example,

import { sendToOffscreen } from '@plasmohq/offscreen';

// Automatically create document behind the scene if not exist
await sendToOffscreen(
  // Request body
  {
    message: 'Test Message',
  },
  // Config
  {
    reasons: [chrome.offscreen.Reason.BLOBS],
    justification: 'Testing',
  }
);

AaronMBMorse · 2023-08-13T15:07:12Z

I added the three files below, and offscreen permission to my manifest/package.json and it worked.

I am creating this post to compile all the code for a fully working example in one place. The code is primarily from @dimadolgopolovn and @anooppoommen. Thank you guys!

All of these files are should be placed at the root of your project. In my case that is in the src/ directory.

Note: You can move the background.ts file into a background folder if your prefer. In which case it would look like this background/index.ts.

Chrome Developer Docs

packages.json

Permission Docs

{
    "permissions": [
      "offscreen"
    ],
}

background.ts
Note: chrome.offscreen.Reason.WEB_RTC has a few options

import OFFSCREEN_DOCUMENT_PATH from "url:~src/offscreen.html"

async function createOffscreenDocument() {
  if (!(await hasDocument())) {
    await chrome.offscreen
      .createDocument({
        url: OFFSCREEN_DOCUMENT_PATH,
        reasons: [chrome.offscreen.Reason.WEB_RTC],
        justification: "P2P data transfer"
      })
      .then((e) => {
        // Now that we have an offscreen document, we can dispatch the
        // message.
      })
  }
}
createOffscreenDocument()

async function hasDocument() {
  // Check all windows controlled by the service worker if one of them is the offscreen document
  // @ts-ignore clients
  const matchedClients = await clients.matchAll()
  for (const client of matchedClients) {
    if (client.url.endsWith(OFFSCREEN_DOCUMENT_PATH)) {
      return true
    }
  }
  return false
}

offscreen.ts
console.log("Offscreen script loaded")

offscreen.html

<!DOCTYPE html>
<html>

<head>
  <title>Offscreen</title>
</head>

<body>
  <script src="offscreen.ts" type="module"></script>
</body>

</html>

amitrahav-darrow · 2024-09-17T10:49:59Z

On chromium 128.0.6*** this method raises a Content Security Policy error.
And from the v3 of manifest there is no option to include outside scripts, also from localhost.

Any thoughts about how to implement it?

jkkrow added the enhancement New feature or request label Mar 31, 2023

louisgv pinned this issue Jun 13, 2023

louisgv added the help wanted Extra attention is needed label Jun 13, 2023

louisgv self-assigned this Jun 13, 2023

louisgv mentioned this issue Jun 14, 2023

[BUG] Regression in bgsw on Firefox: Could not resolve bundle with id X #628

Closed

3 tasks

louisgv unpinned this issue Jun 29, 2023

WilliamKeating mentioned this issue Nov 6, 2023

[BUG] Plasmo Url import not working #806

Closed

3 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[RFC] Support for Offscreen Documents #527

[RFC] Support for Offscreen Documents #527

jkkrow commented Mar 31, 2023

dimadolgopolovn commented May 12, 2023

louisgv commented May 12, 2023

dimadolgopolovn commented May 13, 2023 •

edited

Loading

jkkrow commented May 14, 2023

anooppoommen commented Jun 12, 2023 •

edited

Loading

dimadolgopolovn commented Jun 12, 2023

anooppoommen commented Jun 12, 2023

jkkrow commented Jun 12, 2023

anooppoommen commented Jun 12, 2023

jkkrow commented Jun 12, 2023

anooppoommen commented Jun 12, 2023 •

edited

Loading

anooppoommen commented Jun 12, 2023 •

edited

Loading

louisgv commented Jun 29, 2023 •

edited

Loading

jkkrow commented Jun 30, 2023

AaronMBMorse commented Aug 13, 2023 •

edited

Loading

amitrahav-darrow commented Sep 17, 2024

[RFC] Support for Offscreen Documents #527

[RFC] Support for Offscreen Documents #527

Comments

jkkrow commented Mar 31, 2023

How do you envision this feature/change to look/work like?

What is the purpose of this change/feature? Why?

(OPTIONAL) Example implementations

(OPTIONAL) Contact Details

Verify canary release

Code of Conduct

dimadolgopolovn commented May 12, 2023

louisgv commented May 12, 2023

dimadolgopolovn commented May 13, 2023 • edited Loading

jkkrow commented May 14, 2023

anooppoommen commented Jun 12, 2023 • edited Loading

dimadolgopolovn commented Jun 12, 2023

anooppoommen commented Jun 12, 2023

jkkrow commented Jun 12, 2023

anooppoommen commented Jun 12, 2023

jkkrow commented Jun 12, 2023

anooppoommen commented Jun 12, 2023 • edited Loading

anooppoommen commented Jun 12, 2023 • edited Loading

louisgv commented Jun 29, 2023 • edited Loading

jkkrow commented Jun 30, 2023

AaronMBMorse commented Aug 13, 2023 • edited Loading

amitrahav-darrow commented Sep 17, 2024

dimadolgopolovn commented May 13, 2023 •

edited

Loading

anooppoommen commented Jun 12, 2023 •

edited

Loading

anooppoommen commented Jun 12, 2023 •

edited

Loading

anooppoommen commented Jun 12, 2023 •

edited

Loading

louisgv commented Jun 29, 2023 •

edited

Loading

AaronMBMorse commented Aug 13, 2023 •

edited

Loading