When we decided that every SpiderPublish component would render inside a Shadow DOM boundary, we knew we were trading simplicity for isolation. After shipping 40+ marketplace components, here’s what we learned.
The Scoping Advantage
Shadow DOM gives us something no other isolation method can: true CSS scoping. A component’s styles cannot leak out, and the host page’s styles cannot leak in. For a marketplace where hundreds of components from different authors coexist, this is non-negotiable.
The querySelector Trap
The most common bug we see from new component authors: using document.querySelector. Inside Shadow DOM, the document doesn’t see your elements. You must traverse from a known root:
var root = this.closest('.wrap').getRootNode();
var el = root.querySelector('.target');Event Delegation
Events that cross the shadow boundary get retargeted. This means event.target will point to the host element, not the actual clicked element inside the shadow. Always use inline handlers or attach listeners within the shadow root.
Theme Tokens
We solved theming by injecting CSS custom properties at the :host level. Every tenant gets their brand colors via var(--spider-primary), var(--spider-text), etc. Components never hardcode colors.