Skip to main content

Tool Embedding Architecture

Goal​

Provide a unified way to embed external tool pages inside Docusaurus, keep page structure consistent, and reduce maintenance cost for each tool page.

Code Structure​

  • src/config/tool-registry.ts
    • Centralized tool configuration (title, description, iframe URL, timeout, new-tab URL, etc.).
  • src/components/ui/EmbeddedToolFrame.tsx
    • Renders iframe in a unified way and handles loading, timeout, errors, and retries.
    • Supports reusing the same iframe instance across routes to reduce reloads during navbar navigation.
  • src/pages/*.tsx
    • Pages only read registry config and render EmbeddedToolFrame.

Configuration Fields​

Main fields of EmbeddedToolConfig:

  • id: Unique tool identifier, also used as the iframe reuse key.
  • pageTitle / description: Page metadata.
  • iframeTitle: iframe title.
  • src: iframe source URL.
  • openInNewTabUrl: URL to open in a new tab when loading fails.
  • timeoutMs: iframe loading timeout in milliseconds.
  • persistAcrossNavigation: Whether to keep iframe alive across route navigation.
  • sandbox: iframe sandbox attribute (configure per page requirements).
  • referrerPolicy: iframe referrer policy.

Current Tool Mapping​

  • /product-list -> https://novastar.show/
  • /calibration-request -> https://calib.novastar.wiki/
  • /download -> /proxy/download (forwarded by Pages Functions)

Page Integration Pattern​

import React from 'react'
import Layout from '@theme/Layout'

import { EmbeddedToolFrame } from '../components/ui'
import { EMBEDDED_TOOLS } from '../config/tool-registry'

export default function ProductListPage() {
  const tool = EMBEDDED_TOOLS.productList

  return (
    <Layout title={tool.pageTitle} description={tool.description}>
      <main className="w-full">
        <div id="tw-scope" className="w-full">
          <EmbeddedToolFrame config={tool} />
        </div>
      </main>
    </Layout>
  )
}

Verification Commands​

bun run typecheck
bun run build