Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 39 ยท Getting Started

Setting Up and Debugging Web Components

Set up a Web Components project with nothing but a text editor, check browser support, organize files and debug custom elements and shadow roots in DevTools.

One of the nicest things about Web Components is how little setup they need. There is no compiler to install and no project template to generate. A text editor and a browser are enough. This lesson shows the minimal project layout, how to check that a feature is supported, and how to inspect your components with the browser's developer tools.

Browser support

Custom Elements, Shadow DOM and templates are supported in all current versions of Chrome, Edge, Firefox and Safari. Newer pieces have a more recent history: Declarative Shadow DOM, form-associated custom elements, ElementInternals and the adoptedStyleSheets API are all available in current browsers, but very old browsers lack them. Customized built-in elements (is="...") are the one exception: Safari does not implement them, a point covered in the chapter on custom elements.

You can test support in code:

JS Feature detection

Press Run (or Ctrl + Enter) to see the console output here.

No output.

If a row says false in your browser, a feature is missing and you would need a fallback. For a modern audience you rarely need polyfills today.

A minimal project

The smallest possible project is two files. Serve them with any static server (even opening the file directly works for classic scripts).

TEXT
my-components/
  index.html
  hello-card.js
HTML
<!-- index.html -->
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Components</title>
  <script type="module" src="hello-card.js"></script>
</head>
<body>
  <hello-card name="Ada"></hello-card>
</body>
</html>
JavaScript
// hello-card.js
class HelloCard extends HTMLElement {
  connectedCallback() {
    this.textContent = `Hello, ${this.getAttribute("name")}!`;
  }
}
customElements.define("hello-card", HelloCard);

A type="module" script is deferred automatically, so the element definition runs after the HTML is parsed. That means existing <hello-card> tags are upgraded in one pass.

The previews on this site are isolated pages with everything in one file, so the examples put the <script> after the markup. In your own projects, prefer one file per component and load them as modules.

Naming and file conventions

Good habits make a component library easy to scale:

  • One component per file, named after the tag: user-avatar.js defines <user-avatar>.
  • A shared prefix for your library, such as acme-button and acme-dialog, to avoid clashes with other libraries.
  • A single define call at the bottom of the file, guarded when the file might load twice:
JavaScript
if (!customElements.get("acme-button")) {
  customElements.define("acme-button", AcmeButton);
}
  • Export the class so tests and other components can import it.

Debugging in DevTools

Every browser's developer tools understand Web Components. Open the Elements (or Inspector) panel and you will see:

  • #shadow-root (open) nodes under each host. Expand them to inspect internal markup and styles, just like any other part of the page.
  • Computed styles that include rules from the shadow tree's own <style>.
  • Slotted content marked with a "slot" badge, and a reveal link that jumps between a slotted node and its <slot> element.

In the console, a few expressions are useful:

Inspecting a component from code

The last line prints null, which confirms that the paragraph is not part of the document's own tree. That is the most common "bug" beginners hit: a query that works in the shadow root but not on the document, or the other way round.

Common errors and what they mean

Message Cause
Failed to execute 'define' on 'CustomElementRegistry': "x" is not a valid custom element name The name has no dash or contains uppercase letters
this name has already been used with this registry define ran twice for the same name
Failed to construct 'CustomElement': The result must not have attributes The constructor set attributes or children when created by document.createElement
Cannot read properties of null right after attachShadow You used document.querySelector instead of shadowRoot.querySelector

When an element shows as plain text with no behavior, it has not been upgraded yet: either the script did not run, the name is spelled differently in define, or the definition throws. Check the console first.

A handy trick: :defined

Until the browser finds the definition, the tag is an "undefined" element. You can style that state to avoid a flash of unstyled content:

CSS
my-card:not(:defined) {
  display: block;
  min-height: 4rem;
  visibility: hidden;
}

The :defined pseudo-class matches elements that are built in or have been upgraded to a custom definition. Reserving the space prevents the page from jumping when the component loads.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What do you need at minimum to start writing Web Components?

    Web Components are native browser features, so no tooling is required.
  2. 2. Why does document.querySelector('.msg') return null for a paragraph inside an open shadow root?

    You must query the shadow root itself, for example el.shadowRoot.querySelector('.msg').
  3. 3. How do you avoid defining an element twice?

    customElements.get returns the existing class if the name is registered, so you can guard the call.
  4. 4. What does the :defined pseudo-class match?

    Custom elements that are not yet defined do not match :defined, which lets you style the loading state.

Summary

  • Current browsers support all core Web Component APIs; use feature detection for newer ones.
  • A project can be a single HTML file plus one module per component.
  • Prefix tag names, keep one component per file and guard define.
  • DevTools shows #shadow-root nodes and slotted content; query shadow trees through shadowRoot.
  • :not(:defined) helps you manage the loading state.

Next: Autonomous Custom Elements