Call for ideas on webcomponents.org reboot

[justinfagnani]

Where webcomponents.org is at now

webcomponents.org was launched in a very different environment than we have today: the web component specs were at "v0" with v1 not even on the horizon yet, Bower was still relevant, the Polymer Library was the most common way web components were authored, and HTML Imports were the primary loading format.

We've kept webcomponents.org somewhat up-to-date by adding npm support, and support for analyzing Polymer 2, 3, and to some extent "vanilla" web components. But it has fallen behind on the ability to analyze non-Polymer web components like Stencil, LitElement, etc. And it's web components documentation is not prominent or complete enough. The community section is very out of date.

Problems with the current architecture

Lack of introduction and approachability

webcomponents.org is designed primarily as a catalog, and secondarily as a documentation site and blog. This means that the landing page starts with listing elements and element collections, and doesn't even explain what web components are. Given that there's no singular implementor or owner of web components, and therefore no official site like many frameworks and libraries have, webcomponents.org is about as close as we have, but it doesn't introduce potential users to the concepts and benefits.

Complicated and limited analysis/indexing pipeline

The indexing pipeline runs the Polymer Analyzer against source code to determine what elements a package contains and generate documentation and demos. This has a benefit in that often times component maintainers don't need to do anything to support webcomponents.org, but it limits the catalog to the elements that the Polymer Analyzer support, which obviously unfairly tilts the catalog towards the Polymer Library.

Low prominence of documentation

Not enough prominence and attention has been given to documentation. Without a central location for web components information, many libraries have had to duplicate documentation on shared foundational concepts like custom elements and shadow DOM, and few seem to link to webcomponents.org for this information.

What would a reboot look like?

We'd like to kick off a community-driven, collaborative reboot of webcomponents.org. Google can provide guidance, resources, and contributions, but we want the vision to be set, and work to be done, collaboratively with the growing web components community.

The reboot should probably not over-focus on the catalog aspect of the current site. There are several areas of need for the site and the community as a whole, including:

• A great landing page for web components
• Documentation for specs and patterns that apply to all web components
• A library-agnostic catalog
• Links to popular web component helper libraries and frameworks
• Links to tooling, configuration, and guides for users of common tools, eg Rollup, Webpack, Karma, Storybook, etc.

How should we go about this?

In order to have a collaborative effort we'll need a detailed plan and agreement across contributors, so that work from multiple contributors can actually proceed in an organized fashion.

The process could possibly look something like this, though the process itself is open to brainstorming:

1. This issue is the call for ideas and a place to brainstorm.
2. A requirements document as a markdown file in this repo, built via PRs.
3. A detailed design document as a markdown file in this repo, built via PRs.
4. Individual issues for specific questions.
5. Implementation...

[justinfagnani]

cc @thepassle, @LarsDenBakker, @Westbrook, @daKmoR, @bennypowers, @graynorton, @kevinpschaaf, @arthurevans, @treshugart, @matthewp, @adamdbradley, @caridy, @diervo, @robwormald

[thepassle]

Thanks for starting the discussion Justin! As discussed earlier, we at open-wc are very happy to collaborate and contribute to this effort, and very happy with the community driven approach.

I think it would be great if we can get some people from other parts of the web component ecosystem (stencil/hybrids/skate/vue/etc) in this discussion as well to ask about their needs/wishes, and hopefully contributions, so if anyone has any names to tag, please do so.

Im very much on board with making webcomponents.org more of a landing place for web components, perhaps not unlike how frameworks tend to approach these things. Some things that I think would be interesting to somehow address are different usecases for web components;

• developing a single web component (think a <google-maps> type of component)
• developing a UI component library
• developing applications using web components
• using web components in CMS type of environments

One thing that we've had a lot of very good feedback on is our demos. People find it very useful to quickly be able to look at a demo and fiddle with it to discover a pattern on how to do something, that are a little bit more than just reading the MDN documentation. Maybe we can somehow incorporate something similar as well; eg how to use slots, slot changed, attribute reflection, etc. (Disclaimer: our demos are targeted at LitElement, these demos probably should be vanilla)

[justinfagnani]

Some of my person ideas:

Landing Page

Web components as a whole really need a home. The equivalent to angular.io, emberjs.com, etc. It should lean towards the high-level, introduce web components to those who are unfamiliar with them, and speak at least a little to the mission and benefits the standards.

Marketing-wise, it could feature a rotation of particularly successful components or projects, like <model-viewer>, a component set, a product (Beaker, Salesforce, Microsoft Edge settings pages, etc).

Catalog

Features

The catalog needs to deliver some value above and beyond npmjs.com in order to be worth it. A few features that would justify its existence:

• Filtered to actual web components
• Structured documentation, especially around web components specifics like slots, custom CSS properties, parts, etc.
• Inline demos
• Inline sample editor
• Component type
• Collections
• Metrics/validation? (Pika does interesting thing around modules, do we have similar for WCs?)

The current demos hosted here work quite well, we should just make sure that any project can include them and that we document how to make them work with our demo server. But we should expand the demos into inline sample editing / playground, like what @e111077 is doing in https://github.com/PolymerLabs/code-sample-editor

Indexing Pipeline

The catalog and indexing pipeline should be built around the custom-elements.json file proposed by @octref in WICG/webcomponents#776

Rather than do any analysis on the webcomponents.org servers, we'll simply read and display the data from custom-elements.json. In fact, a valid custom-elements.json should be required for listing in the catalog, which will help weed out packages that have just added a web-components keyword to their package.json, but aren't actual web components. This will also encourage projects the generate and publish custom-elements.json which will improve editor experiences.

We will probably need to expand on the fields in custom-elements.json for demos and such. (cc @ocrtref and @rictic)

Inclusion Criteria

Lots of people use the term "web components" more generally than we do, and we want to make sure that components here are truly custom elements. We'll have to figure out what to do around frameworks that optionally allow you to wrap or compile to web components, but my inclination would be that if it's published as a custom element it counts, and if not it doesn't. After all, just about anything can be wrapped.

Documentation

We should strive to have the go-to documentation for web components basics, so that every other library, blog post, or spicy Twitter thread can link to well-written nearly canonical docs. This includes:

• Custom elements
• Shadow DOM
• Styling with custom variables, parts, constructible stylesheets
• Accessibility
• Form association
• Data: attributes, properties, children, some class basics like accessors.
• Communication between elements: events, etc.
• Best practices
• Browser support
• Polyfills

Getting Started / Tooling

I think webcomponents.org should have some information on getting started, but stick to the most standards-based, tool-free aspects, ie: write a module with a class, load it into an HTML file, see it go, etc.

More opinionated or tool-specific instructions, ie bundling, compilation, testing, should generally be left to sites like open-wc.org, or library-specific sites. There are some exceptions, like talking about the need for custom elements classes to do real super() calls into HTMLElement's constructor.

We should absolutely talk about the polyfills in this context too.

[matthewp]

Thanks for starting this @justinfagnani. I agree that focusing on documentation is a good way to go. I think the component library still has value though, so I wouldn't want to see it going away.

The polyfill documentation is one thing that I want to link to but it seems outdated.

Another is an explanation on how to use web components with popular frameworks. Frameworks should really host this documentation themselves. But some of them do and it's pretty bad, like this one: https://reactjs.org/docs/web-components.html

It's pretty hard to find good documentation on newer features like ElementInternals, so stuff like that would be great too.

So I'd probably start by coming up with an outline on what this should all look like.

[bennypowers]

One of the things I love about web components is the flexibility they offer for programming styles etc. I'd like to hear from @smalluban, @eavichay, and other web component framework authors how they'd like to see this community resource develop.

---

Syndicated Content

Along the lines of @justinfagnani's idea for a rotating feature of projects, we may consider featuring sites, frameworks, recipes, or projects from the community in a blog. In addition to the low-level, high-quality docs and explainers around the spec that would be the major portion of the site's static content, I think there's an opportunity to highlight (without endorsing as canonical) different approaches and tools as they develop. A blog of news and releases from the community would also show the strength and diversity of thought in the field.

Workflow and Tooling Docs

A question: while we all agree on things like what the Shadow DOM is and how the custom elements API works, there still is (and maybe always will be) tonnes of room for opinionated approaches in terms of workflow and tooling. Is there some threshold that a given tool can pass at which point it would be considered canonical enough to warrant pride of place on wc.org? For example, does the custom-element.json spec meet that criteria? If we decide to document any kind of tooling or workflow, How will we decide that a given tool has enough community buy-in? Alternatively, do we want to set a clear boundary now that anything that runs in-browser as part of the web platform is in the docs, and anything that doesn't is better addressed in syndicated posts or by open-wc et al?

More generally, how will we balance the standards-based, low level, and stylistically permissive nature of the field with the desire to provide that framework-like homepage feeling that developers crave?

Window on the Spec Process

webcomponents.org should also be a central location for exposing the broader community to the goings-on of the specification process. There's so much interesting information available in tersely annotated minutes of whatwg or tc39 meetings and in w3c/webcomponents issue and pr threads, and there are things like is and css modules which have tremendous developer appeal but have perhaps failed to catch among implementers. webcomponents.org is the ideal place to publish explainers and canvas developer opinion.

[diervo]

We would love to be heavily involved (speaking as Salesforce) as resources allow. So much we can help and contribute specially when it comes to polyfills and tools (which I know Google is heavily invested in as well).

Already sent emails internally see how much we can commit as an ongoing basis, but for sure Caridy and I will be helping.

On the documentation aspect, the team recently built our docs (https://lwc.dev/) architecture purely on markdown and web components, so hopefully an interesting architecture to consider for making it accessible for everyone to contribute easily.

@justinfagnani let us know how and when you want to proceed to move this forward.

[justinfagnani]

@thepassle

One thing that we've had a lot of very good feedback on is our demos. People find it very useful to quickly be able to look at a demo and fiddle with it to discover a pattern on how to do something, that are a little bit more than just reading the MDN documentation. Maybe we can somehow incorporate something similar as well; eg how to use slots, slot changed, attribute reflection, etc. (Disclaimer: our demos are targeted at LitElement, these demos probably should be vanilla)

I like this idea, but I also like just how far you've run with these types of samples on open-wc.org. To scope things down for an initial version, I'd probably start with editable samples demonstrating usage of the components in the catalog itself. Even that may be a bit much for a first cut.

[justinfagnani]

@bennypowers

A question: while we all agree on things like what the Shadow DOM is and how the custom elements API works, there still is (and maybe always will be) tonnes of room for opinionated approaches in terms of workflow and tooling. Is there some threshold that a given tool can pass at which point it would be considered canonical enough to warrant pride of place on wc.org?

This is a great question. I'd personally draw the line extremely close to "no tools" as possible, and leave everything else up to sites like open-wc.org and libraries.

For example, does the custom-element.json spec meet that criteria?

custom-element.json would deserve documentation as the way to get components into the catalog in the first place, and as best practices in order to integrate with other tools and IDEs. It itself isn't a specific tool though, but a bridge across many.

I'd stick to simple things in any examples, like:

• create a module JS file
• extend HTMLElement
• load the module into HTML with <script type="module">
• serve the module with just about any static file server
• see the result

With some references like "if you need to load modules into browsers that don't support them, see {these tools | these lists of recommendations}".

If we decide to document any kind of tooling or workflow, How will we decide that a given tool has enough community buy-in?

Exactly why I'd steer clear of this area :) Also, there are clearly quite a few tools with enough adoption to warrant documentation somewhere. wc.org likely can't or shouldn't host them all.

Not to mention that most of the tools-specific documentation amounts to "get your tools to support modules and modern JavaScript fully". That can happen elsewhere while we just use modules and modern JavaScript as needed on wc.org.

[pshihn]

Agree with @matthewp about documentation about frameworks - Very commonly asked.
Also useful would be:

• Best practices for publishing on npm - package.json etc
• Docs on accessibility
• Much better demos/code especially in the catalog
• Perhaps hosting a REPL (or links to codesandbox) with Vanilla Javascript, lit, stencil, other libs

[petecarapetyan]

If webcomponents.org had its own slack feed, that would allow for a lot of the same kind of discussion that is both helpful to members and inappropriate for some of the more canonical aspects of the site - especially as distinct from the Polymer feed.

A pipe dream:
No idea how, but if there were a way to share ratings or other validations of best and worst aspects of each listing - that would be nifty. For example, I think the world of the captain's efforts to microsize his own material clones, but other folks would have different metrics for what they want from a component.
Usage would be super interesting to me also. If I know that something is used by a lot of shops that I respect, that means something to me. But how would one even think about collecting and presenting
that kind of data?

[bennypowers]

slack feed

https://gitter.im/webcomponents/home

[web-padawan]

I'm also interested in contributing to the project reboot. Let me add some notes.

Knowledge base

I already collected a lot of web components resources in the "awesome" list:
https://github.com/mateusortiz/webcomponents-the-right-way

And I think we could represent such resources in a better way than long README.
These could fit into https://www.webcomponents.org/community with some additions such as

• thumbs (pictures),
• categories (e.g. "tutorial", "video", "podcast")
• tags (e.g. "polymer", "stencil" etc),
• year filter.

Community

One real problem is that web components do not have a community where e.g. LitElement and Stencil users could reach one another.

The more I stay in Polymer Slack channel (despite I learned a lot from there), the more it feels like staying in the "walled garden", as Polymer has pretty much closed ecosystem at the moment.

https://gitter.im/webcomponents/home

Gitter does not provide a good UX to me. How about https://spectrum.chat community?
It seems also to be a better alternative than Slack in terms of SEO (e.g. forum with permalinks).

Demo snippets

I feel that we lack a framework-agnostic multi purpose demo snippet component.
We could investigate using @pikapkg CDN as part of the setup for such a component.

I see it as a common base, which could be extended and reused e.g. by lit-html demo snippet (accepting a html tagged literal) or any other library-specific demo snippet.

[georges-gomes]

Hi All, we just opened https://webcomponents.dev and I think it could be a nice addon to webcomponents.org to show case components and frameworks (@matthewp we just added Haunted yesterday ;)).

Our starter kits are simple but they have links to the reference materials.
Our demos could be improved, for each framework and it would be a nice playground/learning experience.
Don't take my word for it! Please check it out! https://webcomponents.dev

We are happy to improve it to fit the need of webcomponents.org via embeds and contribute to the documentation.

Web components with ❤️

[smalluban]

@bennypowers Thanks for mentioning, I wasn't aware of this discussion. From my observation, web components from the catalog have docs at a very different level. Some of them are even useless, as they show more general information about the project, but not about a specific element. It would be great to go with custom-elements.json idea. I think it could be possible to create a tool for an automatic generation of that file for easy migration (for sure, for hybrids). Then we could give up on just copying README from the project.

I would like to suggest another addition to the site. For now, we don't have the recommended solution for web components distribution. In hybrids, you can export the structure of the element, and leave the define step to the user. It is pretty the same in other libraries, or with vanilla ones. The web component author might export class definition, or use customElements.define in the body of the element. I am not sure which solution is more appropriate. I suppose, that web components authors too. The problem applies also to file format - should we only support ES modules, or should we build for older browsers, etc.. I think wc.org could provide a helpful section for web components authors, where they can learn what is the best way to distribute their components (with the docs for custom-elements.json file requirement).

A section like this could encourage tool authors to wrap them into the custom elements and distribute them for the community.

[web-padawan]

@georges-gomes congrats with the launch!

I think it would make sense for us to cooperate more, rather than building a bunch of similar projects independently. So I really hope we all can merge the effort at some point.

Also, the domain name is really cool (I recently checked it and noticed the "coming soon" redirect).