Technical Decision and Practices of Using Web Components in EE NEXT SDK
This document details the EE NEXT SDK team's technical decisions to adopt Web Components for front‑end component development, explains the benefits and drawbacks of Custom Elements and Shadow DOM, outlines challenges such as cross‑stack compatibility, bundle size, style isolation, and provides practical implementation guidance and best‑practice recommendations.
Introduction
This document describes the EE NEXT SDK team's technical decisions for developing front‑end components with Web Components, and interleaves introductions to Web Component standards such as CustomElement and Shadow DOM, including their advantages, pitfalls, and lessons learned.
What is EE NEXT SDK?
EE NEXT SDK is a collection of functional front‑end business components created by ByteDance's Efficiency Engineering middle‑platform front‑end team. It exposes capabilities like AI search, employee information lookup, and AI‑enhanced data as reusable components delivered via CDN.
The SDK includes components such as search, employee cards, and knowledge cards, each backed by corresponding backend services.
<!document>
<head>
<script async src="https://{{cdn-host}}/{{cdn-path}}/user-card-v1.0.0.js"></script>
</head>Practice of Web Components in EE NEXT SDK
Brief Introduction to Web Components
Web Components are a W3C standard that includes CustomElement, Shadow DOM, Slot, and HTML Template APIs, enabling cross‑stack and cross‑browser reusable components.
Why Use Web Components in EE NEXT SDK
The cross‑platform and style‑isolation features of Web Components address long‑standing issues of middle‑platform components, such as being limited to React 16, style pollution, and cumbersome usage.
Technical Background
The team needed a new employee‑card component to display name, email, city, etc., across various applications (Feishu Recruitment, Feishu OKR, etc.) built with different stacks (React 15/16, Vue.js) and environments (browsers, WebView).
Technical Challenges
Cross‑stack and cross‑environment compatibility
Minimizing component bundle size
Ensuring style protection
Improving usability and decoupling from business‑line build processes
Can Traditional React Components Meet These Scenarios?
React components are tied to high‑version React, increasing development and maintenance cost for lower‑version or Vue.js environments.
Runtime size of React is large, making bundle‑size control difficult for CDN delivery.
Style isolation often requires CSS‑in‑JS solutions (e.g., emotion), which introduced leakage issues.
What Problems Web Components Solve
High Compatibility : Native browser support allows usage across stacks and browsers without extra runtime.
Small Size : No large runtime needed; the browser handles lifecycle, keeping compiled size low.
Style Isolation : Shadow DOM provides natural style encapsulation, preventing external CSS interference.
Ease of Use : Used like ordinary HTML elements.
Robustness : Works well in micro‑frontend architectures, avoiding side‑effects during mount/unmount.
Final Decision
Adopt Web Component as the technology stack for the employee‑card component.
What Is a Web Component?
Web Component development relies heavily on CustomElement and Shadow DOM.
Quick Start
Example steps include creating a custom-button element, defining it with customElements.define , attaching a Shadow Root, and inserting the element into the DOM.
Creating a CustomElement
Define a class extending HTMLElement .
Register it with customElements.define('custom-button', CustomButton) .
Instantiate and insert the element via standard DOM APIs.
Using Shadow DOM for Style Protection
Attach a Shadow Root to the custom element.
Insert a style sheet inside the Shadow Root to style internal elements without affecting the outer page.
Reference: https://codepen.io/weidongxin/pen/MWmNgOb
Final Page Structure
CustomElement
CustomElements enable reusable web components that behave like ordinary HTMLElements.
Advantages
Works in any browser or WebView supporting the standard.
No extra runtime, keeping file size small.
Complete lifecycle methods for managing side effects.
Simple usage—treated as regular HTML tags.
Low development difficulty; only ES6 class knowledge required.
Disadvantages
Compatibility requires ES6 class; may need polyfills for older browsers.
Once defined, a CustomElement cannot be unregistered, leading to potential naming conflicts.
Props are typically strings; passing complex objects requires manual handling.
Limited integration with JSX; custom events need explicit handling.
class CustomButton extends HTMLElement { /* ... */ }
// Define custom-button element
window.customElements.define('custom-button', CustomButton);
const customButton = document.body.querySelector('custom-button');
// Pass reference‑type props
customButton.message = { name: 'xxx' };
customButton.setParams({ age: 23 });Example of handling a custom event in React:
// Home.tsx
const Home: FC = (props) => {
const onPopout = () => {};
return
;
};
// Ref‑based workaround
const Home: FC = (props) => {
const onPopout = () => {};
const ref = useRef
(null);
useEffect(() => {
if (!ref.current) return;
ref.current.addEventListener('popout', onPopout);
return () => { ref.current?.removeEventListener('popout', onPopout); };
}, [ref]);
return
;
};Shadow DOM
Shadow DOM creates an isolated DOM subtree whose styles and behavior do not affect the outer page, and vice versa.
Advantages
Child elements are insulated from external styles.
Internal styles do not leak out.
Acts as a DocumentFragment without influencing its children.
Purpose
Its natural style isolation makes Shadow DOM ideal for protecting third‑party front‑end components, especially in EE NEXT SDK scenarios.
Common Pitfalls and Solutions
1. Shadow DOM Is Not Completely Isolated
CSS inheritance can still affect elements inside the Shadow Root. A common fix is to place a wrapper div at the root of the Shadow DOM to block inherited properties.
Reference: https://codepen.io/weidongxin/pen/NWgpJPJ
2. Light DOM, Shadow DOM, and Slot
Light DOM refers to the host element’s regular children, distinguished from Shadow DOM. Slots allow Light DOM nodes to be projected into Shadow DOM.
When both Light DOM and Shadow DOM exist simultaneously, Light DOM may not render unless explicitly slotted.
Solution: Use <slot> inside Shadow DOM to project Light DOM content.
3. Shadow DOM Is Not Exclusive to CustomElements
Any HTMLElement can attach a Shadow Root, providing style protection without defining a CustomElement.
4. Shadow DOM Does Not Cause Mysterious Style Issues
Most style problems can be resolved with standard CSS techniques; Shadow DOM itself rarely introduces unexpected styling bugs.
ByteFE
Cutting‑edge tech, article sharing, and practical insights from the ByteDance frontend team.
How this landed with the community
Was this worth your time?
0 Comments
Thoughtful readers leave field notes, pushback, and hard-won operational detail here.