Yax.com Daily Worklog
I believe there is a new way to build websites that doesn’t require frameworks or build tools. If this is true, there’s no need for a beginner to learn the complexities of a framework like React or Rails and the path from simple websites to sophisticated web applications can become easier for anyone. If this is true, Yax.com can be an inspiration for both simple websites and sophisticated web applications, providing examples of how to build websites without frameworks or build tools.
In July, I explored the possibilities of building websites without frameworks or build tools. As I explored the possibilities, I took extensive notes and continued writing tutorials about what I learned.
I began building a suite of websites:
- yax.com (for the main landing page)
- try.yax.com (for a demonstration)
- blog.yax.com (for this blog)
- assets.yax.com (for assets shared among the sites)
- api.yax.com (for the programs that build and deploy websites)
I extended last month’s exploration of web component technology and built custom elements to share among the suite of Yax sites. As I built the library of custom elements, I wrote a tutorial, How to Build a Custom Tag Library. I also built a collection of web components to use for the tutorials website itself. This was an exercise in “bootstrapping and dogfooding.” I did something similar for the RailsApps tutorials six years ago and I’m following the same approach this time: learning, building, and documenting what I learn so others can follow easily.
I found it took three weeks to master and explain everything from first principles, since I’m writing for a neophyte audience. For me, there is always tension between wanting to push ahead and build what I need, versus taking time to document what I’ve learned. Here the mission is to teach as well as learn or build, so I’m exercising patience.
Rather than describing the daily drudgery of writing the tutorial, I’ll just highlight the interesting things I learned.
July 1, 2020
I started naming custom elements and quickly discovered there’s a naming convention for custom elements (two words separated with hyphens). Apparently the convention is necessary so a browser can distinguish custom elements from standard HTML elements.
July 3, 2020
I needed questions answered and found the Polymer Slack channel. It’s really the “Lit-Element Slack channel” as the Polymer project has been superseded by Lit-Element. I asked a question about how to use HTML semantic tags with custom elements and got a helpful and quick response from Benny Powers.
July 4, 2020
Here in Bali it is the Saraswati holiday, a day dedicated to the goddess of knowledge. I spent the day catching up with colleagues by email and WhatsApp.
July 5, 2020
I started learning about CSS in custom elements. Discovered quickly that it is complicated. There’s an inherent architectural conflict between HTML (a single file that is declarative for a single page) and CSS (multiple stylesheet files applying styles across an entire website) that makes it difficult for beginners to learn how to use CSS with custom elements. HTML custom tags and CSS do not fit together easily, which is partly why it has taken many years for web components to become part of the HTML standard. It took me five days to write a practical introduction to CSS for custom elements.
July 7, 2020
Spoke with Guy Bedford about his JSPM project.
July 8, 2020
A recruiter hiring for a CTO role contacted me. I told him I’m not available (at least not until I run out of money). Also posted to Hacker News about the Fig terminal tool, a project I’ve been following.
July 9, 2020
I read about the new Constructable Stylesheets specification. It provides better performance for custom elements.
July 10, 2020
I looked at Microsoft FAST web components. Like other innovations in the .NET world, it doesn’t seem to be well-known outside the .NET world. The fast-element library is similar to Google’s Lit-Element as a convenience API for building custom elements. Also was reading today about pwa-auth from Microsoft’s PWAbuilder project, a new sign-in component I’d like to try out.
July 11, 2020
Today I learned about a common styling problem with custom elements: They look weird if the developer doesn’t set display: block because custom elements default to display: inline.
July 12, 2020
I read the proposal for Declarative Custom Elements which would allow people to create custom elements without JavaScript. Just one of those things we should have had in the HTML specification from the very beginning.
July 13, 2020
Today I learned how to apply an external stylesheet to a custom element. Because people will ask, “How do I use Bootstrap with my web components?”
July 14, 2020
One way of applying an external stylesheet to a custom element is to disable the Shadow DOM in Lit-Element. It sounds mysterious but it is just three lines of code and simplifies styling. And lets you use Bootstrap (or any other favorite CSS framework).
July 16, 2020
I wrote about “Sharing an Assets Library” for the tutorial and explained how to use a Git submodule. Later I realized it’s better to avoid Git submodules (especially for any beginner). It’s easier to just set up an assets server on Netlify or Vercel.
July 17, 2020
I wrote about “Publishing an Assets Library” for the tutorial and explained how to publish a package on NPM. It took three days to find a way explain it adequately for a beginner.
July 18, 2020
Read comments on Hacker News about web components after Kenneth J Hughes submitted a link to an article about over thirty ways to create custom elements. Judging from the comments, many web developers are new to web components. This validates my impulse to write tutorials and produce example projects.
July 20, 2020
I sorted out my questions about main and module fields in package.json and looked at how CDNs deliver JavaScript modules. Finished up the tutorial by publishing my example custom elements library to NPM for testing.
July 21, 2020
I’ve finished drafts of two tutorials (one basic, one advanced) about web components. Today I started building the tutorials.yax.com website where I will publish the tutorials. I followed the general format of the RailsApps Tutorials landing page. I’m considering trying the business model I used for RailsApps: Publish open source examples, offer basic free tutorials, and encourage developers to support the project by offering subscriptions for advanced tutorials.
July 22, 2020
I set up a local Git repo for tutorials-yax-com and worked on a landing page design for the tutorials website. Spent two days to get it to my liking. With the landing page done, I’ll extract the navbar and footer to reuse as web components for other pages.
July 24, 2020
Distractions today. Indonesia’s Director General of Immigration announced that, “Holders of the free visa, who have been granted an Emergency Stay Permit, must leave Indonesia in 30 days from the date of this letter.” Please, I don’t want to go back to the United States while the pandemic is raging at a worldwide peak. Few other countries are open to foreigners so it’s either USA or stay. Felt a lot of anxiety. Finally on August 3rd the Indonesian Immigration authorities adjusted the policy and announced they would allow visa applications for foreigners who are stuck here in Indonesia. I’d like to just settle in and work on yax.com. Relocating is disruptive, with or without a pandemic.
July 25, 2020
I built custom tags for a footer and navbar for the tutorials website, applying the knowledge I’d developed writing the tutorial.
July 26, 2020
I created a private GutHub repo with just the tutorials landing page, deployed it to Netlify, and set up a custom domain for tutorials.yax.com. Next I looked at layouts for tutorial pages that are based on Bulma (including https://www.fastify.io/docs/latest/Getting-Started/). I started using a layout generator, Bulma Builder, to create a layout for tutorial pages but found the generator can’t do sidebars. So I just handcrafted a layout. Created a few pages for two tutorials to get a sense of the user experience. Looks great but building the pages by hand requires repetitive HTML copy and pasting followed by customizing, especially for the tutorial titles and internal navigation links. I’ll work to replace the repetitive markup with custom elements. I’m thinking of populating the titles and links with data from a manifest file. My idea of a tutorial structure is a folder containing Markdown files for each section of the tutorial, plus a manifest file containing the tutorial titles and internal navigation links, plus a simple HTML file template that gets hand copied (with minimal changes) for each of the Markdown files. The alternative is to use a static site generator like Hugo, but I think using web components will be simpler than using a static site generator.
July 27, 2020
I looked at creating custom elements that read data from a file. Wanted to figure out how to create a <yax-tutorial-hero> tag that reads data from a manifest.json file to display a tutorial title.
July 28, 2020
After figuring out how to read a tutorial title from a manifest.json file, I added an array of page titles to the file. That gave me everything I needed to create a full set of custom elements for:
- table of contents
- navigation breadcrumbs
- previous/next pagination
July 29, 2020
Woek up and found all my custom tutorial tags failed overnight! What happened? Tracked the failure to the release of a pre-release version of Lit-Html that slipped through the JSPM CDN. Turns out my code was loading Lit-Html twice from different versions, creating a version collision. Got great help from Hubert Sablonnière on the Polymer Slack channel to understand the problem. Submitted a bug report to JSPM and got a fast fix from Guy Bedford. Submitted an issue “add error reporting when html template versions conflict” for the Lit-Html project and Justin Fagnani replied quickly.
July 30, 2020
I foudn there was an issue with the tutorial tags that used the Lit-Html until directive. Worked to develop the simplest possible implementation using a delay that returns a JavaScript Promise. Solved the issue and refactored the tutorial custom tags.
July 31, 2020
Followed up on my issue report on Lit-Html and tried to understand how the JavaScript module system is supposed to handle conflicts when two different versions of a library are imported. I know André Arko worked hard to solve this problem in Bundler for Ruby. Wondering how it’s been solved in JavaScript. Tomorrow, if I have no distractions, I’ll publish this July worklog. I’ll also create a separate subdomain for blog.yax.com and modify the blog and the main site to use the navbar and footer custom tags.
Previous: Worklog for June 2020 - Next: Worklog for August 2020