open-wc: a scaffold and a set of defaults for web component projects

The problem open-wc solves is not writing components, it is everything around them

A web component is a class that calls customElements.define. That part is short. The long part is the surrounding project: which test runner, which lint rules, how to compare shadow DOM in assertions, how to bundle for browsers that need polyfills, how to avoid two components registering the same tag name. open-wc positions itself as a set of defaults and recommendations covering developing, linting, testing, building, tooling, demoing, publishing and automating. The audience is teams starting a component project who would rather accept a known set of choices than assemble one from scratch. The repository is a monorepo of packages, not a runtime library: there is no single @open-wc import that gives you components. If you want ready-made buttons and dialogs, this is the wrong repository, and the README's package table makes that clear by listing configuration and tooling packages rather than UI elements.

How the pieces fit: a generator, a config set, and testing helpers

The entry point is the create package, which the README describes as scaffolding web components following open-wc recommendations. It asks whether you want to scaffold a new project or upgrade an existing one, then writes files into your folder. The rest of the repository is a set of packages you can also install individually. eslint-config is a shared ESLint configuration. testing and testing-helpers sit on top of a test runner and add helpers for component tests. semantic-dom-diff exists to compare DOM and shadow DOM trees, which is what makes assertions against a component's rendered output practical instead of string comparison. scoped-elements auto-defines custom elements to scope them and avoid name collisions, which addresses the case where two dependencies both want to register the same tag. building-rollup and polyfills-loader cover bundling and loading polyfills via dynamic imports. One structural detail matters for evaluation: the README points @web/dev-server at modern-web.dev, noting it replaces es-dev-server. Part of the recommendation set now lives outside this repository, so the open-wc package list is not the whole story of an open-wc project.

Installing open-wc and getting a first component under test

The README gives one command, run in a new or existing folder, and states it requires node 10 and npm 6 or higher. It starts a menu, so the first real step is answering a prompt rather than passing flags.

# in a new or existing folder:
npm init @open-wc
# requires node 10 & npm 6 or higher

According to the README, the menu offers two actions. Choosing Scaffold a new project walks through project setup; choosing Upgrade an existing project applies the recommendations to what you already have. You can exit at any point with Ctrl+C or Esc. After the generator finishes, the project has its own package.json with the dependencies and scripts it chose, and from that moment the scaffold is yours to edit. The testing package is published as @open-wc/testing, and the README lists the current release as @open-wc/[email protected]. What you should see after scaffolding is a working project layout with a test command wired up, not a running application. The README does not document a rollback, so if the generated structure does not suit you, removing the added files and dependencies is manual work.

The upgrade path is the weakest documented part

The generator offers Upgrade an existing project, and the repository uses changesets for releases, with a release script that runs changeset publish --provenance. That tells you how packages are versioned, but it does not tell you what the upgrade action rewrites in your files. The README describes the menu entry in one line and stops there. There is no documented diff, no dry-run flag, and no list of files the upgrade touches. For a project whose whole pitch is adopting a set of defaults, that is a real gap: the riskiest operation is the one applied to code you already wrote, and the documentation does not describe its blast radius. Treat the upgrade action as something to run on a clean git working tree, so you can inspect the result as a diff before keeping it.

Where open-wc is the wrong tool

Two cases stand out. The first is anyone looking for a component library: open-wc ships tooling and configuration, and the README's package table contains no UI elements. The second is teams whose test infrastructure has moved on from Karma-style browser runners. The package table still lists testing-karma, testing-karma-bs for Browserstack and testing-wallaby, and the repository keeps web-test-runner.config.mjs alongside a debug variant, so both worlds are present. That means the recommendation set carries history: some packages exist for setups that newer projects may not choose. There is also a scoping limit. scoped-elements solves tag name collisions by auto-defining elements in a scope, which is a workaround for a global registry that has no native scoping. If your components are consumed by applications you do not control, that workaround only helps where the consumer also adopts it. And the polyfills-loader package assumes a build step; if you ship untranspiled modules to modern browsers only, part of the recommendation set is dead weight.

Compared with assembling the same stack yourself

The alternative is not a single competing project. It is installing the pieces directly: a test runner such as @web/test-runner from modern-web.dev, ESLint with your own config, and a bundler of your choice. The difference in approach is who owns the defaults. open-wc hands you a curated combination and a generator that writes it into your project; the direct route leaves every choice open and every incompatibility yours to resolve. The direct route wins when your constraints are unusual, for example a build pipeline that cannot use rollup, or a lint ruleset your organisation already mandates. open-wc wins when your team has no strong opinions and wants a starting point that already accounts for shadow DOM assertions and polyfill loading. Note that the split is not clean: because @web/dev-server is documented on modern-web.dev and described as replacing es-dev-server, an open-wc project already depends on tooling maintained outside this repository, so you are not choosing between one ecosystem and another as much as between a curated bundle and a hand-picked one.

Maintenance, licence and what upgrading costs you

The repository is not archived, and the last push was on 2026-07-13. The most recent releases listed are @open-wc/[email protected] and @open-wc/[email protected], both dated 2026-07-13, with @open-wc/[email protected] on 2026-06-02. The version numbers are worth reading before you plan an upgrade: semantic-dom-diff is still on 0.x, so its API carries no stability promise from the version number alone, while testing has reached 5.0.0, meaning it has had breaking releases. The repository uses changesets, so per-package changelogs are the place to look for what a bump changes. The root package.json marks the repository private and declares the MIT licence, and each published package is separately versioned. MIT is permissive, but this is not legal advice: check the licence file of each package you depend on, since the monorepo contains packages with their own metadata. Practically, the upgrade cost is not the version bump itself, it is the ESLint and test configuration the generator wrote into your project, which you will need to reconcile by hand when a major release changes defaults.

Editorial conclusion

Adopt open-wc if you are starting a web component project and want testing, linting and build defaults chosen for you, or if you already use Lit and want matching test tooling. Do not adopt it if you need a component library to drop into an app, or if you cannot accept Karma-era test setups and rollup-shaped builds. Before committing, run npm init @open-wc in a throwaway folder and read the generated package.json, because the scaffold writes dependencies and scripts you will own from then on.

Frequently asked questions

Official sources

1. License: MIT
2. open-wc/open-wc on GitHub
3. Project website
4. README
5. Releases