Debugging and common mistakes

See the errors, the theme’s limits, and the most common failures.

​

See the errors

• With developer mode on, uncaught errors from your theme show up as notices: “Theme: Uncaught SyntaxError: …”.
• For the real developer tools (console, inspector, network):

  1. Quit ejGames completely (quick menu → Quit ejGames).

  2. Open it from a cmd window with remote debugging on:

     set WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=9222
     "%LOCALAPPDATA%\ejGames\ejgames.exe"
     

     (change the path if you installed it somewhere else).

  3. In Edge, open edge://inspect (if nothing appears, press Configure… and add localhost:9222) and press inspect on the iframe entry that starts with http://ejg-theme.localhost/ejemplo/. That is your theme’s console: console.log() writes there. You can also inspect the page http://tauri.localhost/ and pick the theme iframe in the console’s context selector (where it says “top”).

​

What a theme cannot do

The theme lives in a closed box, for safety. This does not work:

You want…	What happens	What to do
Data from the internet (fetch, an API)	blocked	Put everything you need inside the theme folder.
Fonts, images or scripts from the internet (Google Fonts, a CDN)	they do not load	Download them into the folder and use relative paths: @font-face { src: url("fonts/my-font.woff2"); }
Read your own files with fetch("datos.json")	also blocked: fetch only reaches library art (http://ejg-media.localhost)	Put the data in a JS module (export default { … }) and load it with import datos from "./datos.js";. The theme’s images, CSS, fonts, audio and video do load in their tags.
localStorage, sessionStorage, IndexedDB, cookies	they throw SecurityError	ejg.storage (below).
alert(), confirm(), prompt()	they do nothing	ejg.ui.toast("Text", "info" | "ok" | "error") or your own HTML dialog.
Open websites	window.open is blocked, and an <a href="https://…"> link opens the site inside the theme, which then disappears (after a few seconds ejGames loads the house theme)	Do not link out to websites.
Reach the disk, other programs, or Tauri	impossible	Only what window.ejg offers.

To store things (the last game you opened, a filter…) use ejg.storage: each theme has 512 KB per profile and can store any JSON value.

await ejg.storage.set("ultimo", 42);
const ultimo = await ejg.storage.get("ultimo"); // 42 (undefined if it does not exist)
const todo = await ejg.storage.getAll();        // { ultimo: 42, … }

Because of these limits, installing someone else’s theme is safe. At most it can launch games from your library or open launcher screens.

​

Common mistakes

Symptom	Likely cause
The theme does not appear in the gallery	theme.json has errors, or the id is not valid (see logs\ejgames.log).
I changed theme.json and nothing happened	It has an error (the theme keeps the previous version): see the log.
I save and it does not reload	Developer mode is off. Meanwhile, F5.
Blank screen	A JavaScript error (turn on developer mode), a bad import (kit paths start with /_sdk/kit/, yours with ./), or the <script> is missing type="module" (without it, await and import fail).
“isn’t responding. The house theme was loaded”	Your code blocks the page (a loop that never ends, a huge calculation at startup).
The controller never reaches a button	It is missing data-focus, or it is hidden or disabled.
The arrows escape a panel	Put data-focus-trap on the panel.
Esc closes your panel and ejGames also acts (in Big Picture, the quick menu opens)	Your back was not treated as handled. In bindNav, do not return false when you did use it.
After closing settings there is no focus	ejg.on("focus-return", () => foco.restore()) is missing.
The focus ring is clipped	content-visibility: auto clips whatever sticks out. Leave padding on the card.
An element with hidden is still visible	Your CSS sets display. Add [hidden] { display: none !important; }.
A click at the top right does not land	That corner belongs to the launcher’s window buttons (windowControls: "host").
A CSS variable does not apply from h()	With style as an object you cannot set variables. Use a string, style: "--tono: 120".