Content Scripts

A content script is JavaScript that gets injected into a page at runtime. It runs in the same environment as the page, so it can use React hooks, read from the database, and call RPC methods. Content scripts target views by type, so you can inject into specific views or use "*" to inject into all of them.

Use cases

• Add UI that appears on every page, like a devtools panel or a chat overlay.
• Add UI to a specific page without modifying that page’s source code.
• Let a plugin contribute visible elements to the host app.

Registering a content script

Call this.injectContentScript(...) from a service:

import { Service } from "@zenbujs/core/runtime"

export class DevtoolsService extends Service.create({ key: "devtools" }) {
  evaluate() {
    this.setup("inject", () =>
      this.injectContentScript({
        view: "*",
        modulePath: "src/content/toolbar.tsx",
      }),
    )
  }
}

Field	Meaning
view	The view type to inject into. Pass "*" to inject into every view.
modulePath	Path to the script. Relative paths resolve against the plugin’s directory; absolute paths are accepted as an escape hatch.

The call returns an unsubscribe function, so wrapping it in this.setup() ensures cleanup on hot reload.

Authoring a content script

A content script is a module that runs when the page loads. It can mount its own React tree into the DOM. This example adds a toolbar using a shadow root to keep its styles separate from the host page:

src/content/toolbar.tsx

import { StrictMode } from "react"
import { createRoot } from "react-dom/client"
import { ZenbuProvider } from "@zenbujs/core/react"
import { Toolbar } from "./Toolbar"

function mount() {
  if (document.body?.dataset.myToolbarMounted === "1") return
  document.body.dataset.myToolbarMounted = "1"

  const host = document.createElement("div")
  document.body.appendChild(host)
  const shadow = host.attachShadow({ mode: "closed" })
  const reactRoot = document.createElement("div")
  shadow.appendChild(reactRoot)

  createRoot(reactRoot).render(
    <StrictMode>
      <ZenbuProvider>
        <Toolbar />
      </ZenbuProvider>
    </StrictMode>
  )
}

mount()

Content scripts vs advice

Content scripts add new UI alongside the host view’s component tree. They cannot replace or wrap existing components. For that, use advice instead.