Skip to main content

Running netDecor

Integration methods​

netDecor can be integrated in a website in two ways:

  1. Via <iframe> tag
  2. Directly mounting in an element on the page

Both methods are fully supported and have their own advantages and disadvantages. While direct mounting provides easier access to the netDecor API, you have to keep in mind, that it does not fully isolate styles and layouts from the rest of the page. Iframe provides better isolation, but it may not work properly on dynamic pages and SPA. In such cases, we recommend using direct mounting.

Caching strategies​

To prevent users from loading stale assets after an update, prefer the versioned artifacts described in Package content and deployment: load netdecor-{version}-cdn.js and netdecor-{version}-cdn.json (or append a ?v={version} query param) so the URL changes on each release and naturally busts caches. For the unversioned netdecor.js and netdecor.json (useful during development), configure your server to send Cache-Control: no-store (or at least no-cache, must-revalidate) and enable ETag/Last-Modified so browsers always revalidate; you can also force-refresh JSON by adding a short cache-busting query string, for example netdecor.json?v=2025-10-10. When using a CDN, watch for aggressive edge caching and delayed invalidations that may serve stale files; set short TTLs for JSON, use per-path rules, and ensure correct CORS and CSP/SRI settings if assets are cross-origin.

Running the program​

The netDecor package contains a example.html file that can be used to run the program. It is a simple HTML file that contains the netDecor script and a container element. You can open it in your browser to see how the program works.

Example HTML and mounting options​

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" href="favicon.ico" />
    <meta name="theme-color" content="#000000" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>netDecor</title>
  </head>
  <body style="height: 100vh; display: flex; flex-direction: column;">
    <div id="root" style="display: flex; flex-grow: 1; max-height: 100%;"></div>
    <script type="module" src="./netdecor.js"></script>
    <script>
      window.onload = async () => {
        const instance = await window.createNetDecorInstance("./", { database: "./database/" });

        // Delayed two-step mounting: initialize first, mount when you decide
        instance.initialize(null).then(() => {
          console.log("Application API initialized");
        });
        //...other code...
        //--------------------------------
        // Mount the UI
        instance.mount(document.getElementById("root"));

        // Direct one-step mounting: pass the container to initialize
        // instance.initialize(document.getElementById("root")).then(() => {
        //   console.log("Application API initialized");
        // });
      }
    </script>
  </body>
  </html>
  • Direct mounting (one step): Pass the container element to initialize(container). netDecor initializes the API and mounts the UI when initialization completes. This is simplest and ensures immediate UI appearance.
  • Delayed mounting (two steps): Call initialize(null) (or without a container) to prepare the API, and later call mount(container) exactly when you want the UI to appear (e.g., after route guards, data prefetch, or a user action). This is useful in SPAs where you control when to mount/unmount the view. In the snippet above we mount right after initialize, but you can defer mount(...) until any later moment.

Unmounting in SPA components​

Call instance.unmount() in your component cleanup (React useEffect return, Vue onUnmounted, Svelte onDestroy). This detaches UI, listeners, and observers.