RFC: fight for simplicity with regards to Open Web Components project future

RFC: Buildless.md

Goal

1. Help the adoption of Going Buildless by frontend developers, regardless of frameworks or libraries they use.

2. Make the most valuable tools related to Going Buildless easy to discover, use and contribute to.

Overview

@open-wc has become an umbrella project which consists of lots of parts mixed in the same repo and docs site:

• tools:

  • es-dev-server
  • karma-esm
  • @mdjs/core
  • storybook-prebuilt (separate repo)
  • mdjs-viewer (separate repo)

• utilities:

  • building-utils
  • polyfills-loader
  • import-maps-generate
  • import-maps-resolve

• plugins:

  • rollup-plugin-html
  • rollup-plugin-polyfills-loader
  • storybook-addon-web-components-knob
  • storybook-addon-markdown-docs
  • webpack-index-html-plugin

• presets:

  • building-rollup
  • building-webpack

• testing helpers:

  • chai-a11y-axe
  • semantic-dom-diff
  • testing-helpers

• WC helpers:

  • dedupe-mixin
  • lit-helpers

• configs:

  • eslint-config
  • prettier-config
  • testing-karma-bs
  • testing-karma
  • testing

• recommendations:

  • testing-wallaby
  • deploying
  • IDE (VSCode)

• onboarding:

  • create
  • codelabs

• experiments:

  • scoped-elements

Problems

IMHO, the current situation has the following problems, that affect developer experience:

• navigation. I always struggle to find a link to ES dev server docs, due to complex navigation structure. And I'm already an experienced user familiar with the site. What about newbies who just discovered open-wc?

• piling up content. Things like ESLint, Prettier, VSCode or Wallaby are definitely useful for those who never tried them. However, these are also matter of personal preference and probably should be downplayed.

• contributing. The monorepo itself is kinda scary for certain users. It might be easier to maintain, but less clear how to contribute - find an issue, setup the environment locally, submit a PR, deal with CI.

• versioning. Because of Lerna, there are many releases that are version bumps only. That forces me as a user to look through CHANGELOG entries figuring out if there are valid reasons for me to upgrade.

• branding. The joke about WC has been so much repeatedly happening, and honestly now it's too annoying. When you reach out to external developers, their first impression really matters, and now it's a bit weird.

• positioning. Many tools are not specific to web components, and could be used by frameworks users. Unfortunately, there is a somewhat negative feeling about Web Components in certain communitites.

• walled garden. Despite the fact that developing with ES modules is becoming popular (e.g. Snowpack), the tools and libraries by open-wc are mostly used by web components (former Polymer) community.

Proposal

Let me make a suggestion that might tackle some of the problems and help to achieve goals:

• introduce Buildless as a separate brand and GitHub org.

• suggested slogans:

  • "build less, do more"
  • "start with index.html"
  • "you might not need build tools"
  • "forget about JS fatigue"

• move the following packages to separate repos under new org:

  • tools
  • utilities
  • plugins (except storybook-addon-web-components-knob)
  • presets

• create a new website (consider 11ty). These domains are free:

  • https://buildless.dev
  • https://buildless.org

• keep configs, recommendations, codelabs, WC helpers under Open WC

• refer to Buildless as a "sibling" project from https://open-wc.org

• invite other tools authors (Vue.js / Vite, Snowpack) to collaborate

Thoughts?

keep configs, recommendations, codelabs, WC helpers under Open WC

there are many helpers which are useful for DOM or ES in general and are not WC related, I always suggested to move them out of open-wc and create some sort of generic "web-test-utils" library or contribute to existing ones which are used the most by the JS community

Quick (personal) thoughts:

navigation

Big agree. This is a huge problem, and one of the central reasons I'm excited to be working on moving the documentation site away from Vuepress and towards 11ty, even if it is a slow effort on my part. The issue is here and I'd love to break it down into a group effort if others are interested.

piling up content

I agree with some of these like Wallaby (esp Wallaby, does anyone use that?) and we've discussed how to deprecate some of our offerings over time, to be sure. However, others of these tools are things we as engineers have to know how to use in the context of our work. It might be better to position our stance on them differently, but I'm not sure we could downplay or remove most of these.

contributing

The pendulum swings. All the issues of a mono-repo are all the issues of not a mono-repo but inverted, are they not?

versioning

I feel this pain (here and in my own projects), too, but wonder if it's a necessary evil? If something made a change you want, and things depend on it, you should want that too, right? In some ways, this feels like more of an indictment of package.json and semver than of Lerna or anyone project. I'd love to hear more about how this fits into your normal workflow to compare notes on what might be done to mitigate this.

branding

You actually still get comments about this? Interesting. Heard it early in the project, but haven't gotten any feedback on it on any substantial form in ages...

positioning

I'd love to hear more how you think positioning would change the impressions of these same communities that their community solution to the problem of "building" is less the bee's knees than they think it is.

walled garden

This implied a forced lock-in, that recent efforts are pushing further and further away from via more decomposed tooling and configs. This would seem to play really close to the above "positioning" statement and to the idea that a "framework" (usually to imply other frameworks, but more and more I hear people using that word with OpenWC) should ship its own stuff. There's an important greater JS community nut to crack there, I think.

https://buildless.dev

Great idea to squat on this regardless of what happens in the near future.

Overall

Great ideas here. I'd think a lot of the suggestions would suffer from the same issues that you see now if pre-announce partnerships with other groups weren't formed. Do you have any association with established RAV groups that might be interested? Fred over at Snowpack always gets excited, but he seems so overdrawn already, that I'm not bullish on his being able to participate in any new efforts, no matter how central they might seem to his current work.

I really think it would be useful to make a split between web component specific and "general modern web development". I'm not sure if I'd call it buildless, for instance storybook and MDJS definitely have a build going on, but it is a catchy term :)

We don't necessarily have to make a full split though, we could keep it all under one organisation and just have better organised sections.

Whatever we do, we need to make sure we don't over engineer this and create something we can't maintain. We've been growing at a steady pace, we need to be careful we don't overreach.

The RFC is great, thanks @web-padawan!

In general terms I can't be more agree. I enjoy when the things just work without transform, transpiling, etc... Then I really thanks your effort in this way.

Here are my 2 cents

branding

I like the idea of buildless. We can play with the lenguaje and talk about "build less" when you are using tools like storybook or MDJS. But, mosts of cases will be buildless. Also we can take the snowpack approach and build all we need in the prepare script that allow to run es-dev-server buildless and with the flag --watch enable the hot refresh.

I definitely agree that the docs have become somewhat of a beast, and I agree that we can benefit from a separation.

• navigation
  This is very much true, and a separation of content would go a long way here.

• piling up content
  Also true, we'll need to overhaul the docs and filter out outdated or non-essential content.

• contributing & versioning
  I understand the point here, but its also more of a javascript/publishing problem I guess? I do agree we can be more helpful to new contributors. Im not sure if this was actually implemented, but we already had some discussions about commitlint for example.

• branding
  I do agree with this (although I also think the JS community could grow up a little bit 🤷‍♂️), but I'm very much not in favor of renaming open-wc. I think it would be very unfortunate to change the name at a point in time where we've build up quite a following/name recognition

Proposal:

• Buildless
  Im somewhat hesitant of naming it 'Buildless'. While I subscribe to the ideology of going buildless, many 'buildless' tools are very much not buildless, and I just think we're "not quite there" yet. Also I think at this point in time its somewhat of a 'hype' name, I'm not sure how relevant the term 'buildless' will be in a few years from now. (However, I do like the "build less, do more" catch phrase)

• New site
  @Westbrook has been doing some explorations of 11ty, and we've already been looking at migrating the docs to 11ty.

Overall I think a good first step here could be to filter outdated content from open-wc, make a separation of what should be open-wc content or not, and move stuff to a separate (to be named) site.

Imo open-wc should be all about getting started with web components, and making it easy for people to build web components or apps with web components. This includes guides/codelabs/examples, but also build/test/lint etc configurations. We've also discussed giving more advanced/in-depth guidance on building apps.

The 'sister' site could then be for the more tooling kind of stuff.

plugins (except storybook-addon-web-components-knob)

If we move the tooling to a separate site, we should also move web component related tooling to that site.

I can't be more agree, thanks @web-padawan!

If my experience helps:

• I use OWC for getting started with almost anything, and also refer others here in Austin who are otherwise weirded out that the world isn't still fixated on their own React or Angular or even JQuery worlds from 2016 or 2013 or before. OWC establishes credibility for a look at shifting to WC, ESM et al.

• It's a challenge for me to "sort out" the vectors I am interested in. Example: we don't do buildless AT ALL, but we still use all the rollup help we can get from OWC, which is considerable. Too many other examples to cite here.

• OWC's guides - especially having them centrally referenced from a credible site - are super critical to many new experimenters at many junctures.

If there is one weakness to the OWC committers it is being too contextually immersed. Which is weird because this group does more to bridge to those who have zero context than anyone else I am aware of. Anything you can do to keep from distancing yourself unintentionally via TMI is probably a good thing. Note I am not prescribing how :(

If there is one weakness to the OWC committers it is being too contextually immersed.

Could you elaborate on what you mean with this exactly? How could we improve on this?

Could you elaborate on what you mean with this exactly? How could we improve on this? re: contextually immersed.

OK, funny story should do the trick.

I have to work constantly at not over-explaining things to the point of getting eye rolls - just a personal problem - and being elderly doesn't help. So I put together a 5 minute video on how to do something - instead of a 30 minute - to compensate for over-explaining. It was good enough. Who would watch a 30 minute video? Nobody, for this.

So my boss goes over it and then begins to rake me over the coals because I didn't tell him about how to use nvm when he had the wrong version of node to run the process. So now Mr Over-explainer is called out for under-explaining - yeesh.

So to him, I was too contextually immersed. I already knew how to work within this context and wasn't going to predict how inadequate his skills were, to the task. This happens so often to me, here in Austin - and believe me I'm not advanced.

I spend hours every week for years reading every ridiculous detailed post that Benny or Lars might make, only to have to research "WTF? What is a CSS variable? Oh, that."

You were correct, Pascal. Sometimes "I also think the JS community could grow up a little bit" too. But at times you guys have no idea how ignorant some of us are, on this channel. You have all picked up so much over the years (contextually immersed). My boss takes one look at a WC and asks "how do I import bootstrap and jquery?" It's a different world.

Okay yeah, thats fair. I do relate to that, in my blogposts I always try to make things as accessible/approachable as possible as well. In docs especially its a hard balance to strike as well. Its definitely something we can keep in mind moving forward.

I do want to clarify a bit though:

"I also think the JS community could grow up a little bit"

What I meant with this was that I think its a bit childish to make toilet jokes because of the 'wc' in the name - i definitely was not referring to different levels of development knowledge

I finally took time to read this and I 100% agree with @web-padawan.

We've had a lot of discussion on this topic within the team, and will have another discussion on it this weekend. We should be able to share some more info on this soon :)

Quoting and fully agreeing with @thepassle

Imo open-wc should be all about getting started with web components, and making it easy for people to build web components or apps with web components. This includes guides/codelabs/examples, but also build/test/lint etc configurations. We've also discussed giving more advanced/in-depth guidance on building apps.

I truly do not want to see "how to use WC with Vue" or "how to use WC with React". I don't even think tools that are usable by other frameworks should even mention those other frameworks on open-wc. Those specific tools have their own documentation on how to use them with other frameworks. What is missing from most of those tool's sites are how to use them with standard web components. And that is where open-wc fills a gap.

@LarsDenBakker, I gather that https://github.com/modernweb-dev/web is the direction that this is headed? Could we get perhaps a broad overview/philosophy of how the @open-wc projects are going to get split between the two org repos? It's great to see this project maturing.