Creating a new web component from scratch involves a lot of boilerplate—testing setup, build configuration, linting, CI/CD, documentation structure, and more. After building — and refining/rebuilding — numerous web components, I’ve distilled all that work into a starter template that lets you focus on your component’s functionality rather than project setup.
\nThe Web Component Starter Template is based on the architecture and patterns I’ve refined across my web component work, incorporating Google’s Custom Element Best Practices and advice from other web components practitioners including the always-brilliant Dave Rupert.
\nThe template provides everything you need to create a production-ready web component:
\nGetting started is straightforward. If you’re a GitHub user, you can create a new repository directly from the template. Alternatively, clone it locally:
\ngit clone https://github.com/aarongustafson/web-component-starter.git my-component\ncd my-component\nnpm install\nnpm run setupThe setup wizard asks for your component name and description, then automatically:
\nYou’re left with a fully scaffolded repository, ready for you to develop your component.
\nOne of the key features is support for multiple registration patterns. Users of your component can choose what works best:
\nManual registration for full control:
\nimport { ComponentNameElement } from '@yourscope/component-name';\n\ncustomElements.define('my-custom-name', ComponentNameElement);Auto-define for convenience:
\nimport '@yourscope/component-name/define.js';Or call the helper directly:
\nimport { defineComponentName } from '@yourscope/component-name/define.js';\n\ndefineComponentName();The auto-define approach includes guards to ensure it only runs in browser environments and checks if customElements is available, making it safe for server-side rendered (SSR) scenarios.
The template includes a comprehensive testing setup using Vitest:
\nimport { describe, it, expect } from 'vitest';\n\ndescribe('MyComponent', () => {\n it('should render', () => {\n const el = document.createElement('my-component');\n expect(el).toBeInstanceOf(HTMLElement);\n });\n});Happy DOM provides a lightweight browser environment, and the included scripts support:
\nnpm testnpm run test:runnpm run test:uinpm run test:coverageThe template is configured for secure automated publishing to npm using OpenID Connect (OIDC), which is more secure than long-lived tokens. After you manually publish the first version and configure OIDC on npm, create a GitHub release and the workflow handles publishing automatically.
\nManual publishing is still supported if you prefer that approach.
\nThe template bakes in best practices from the start:
\nThe included WEB-COMPONENTS-BEST-PRACTICES.md document explains the reasoning behind each pattern, making it a learning resource as well as a starter template.
After creating components like form-obfuscator, tabbed-interface, and several others, I found myself copying and adapting the same project structure each time. This template captures those patterns so I — and now you — can start building components faster.
\nIf you build something with it, I’d love to hear about it!
\n","social_text":"Start building web components the right way with this production-ready template.","url":"https://www.aaron-gustafson.com/notebook/a-web-component-starter-template/","tags":["web components","JavaScript","open source","developer tools","best practices"],"date_published":"2026-01-02T00:06:37Z"},{"id":"https://www.aaron-gustafson.com/notebook/be-a-good-localstorage-neighbor/","title":"✍🏻 Be a good localStorage neighbor","summary":"Most JavaScript developers are keenly aware of what they add to the global object and do their best to namespace their work or sequester it in closures . Namespacing and closures reduce the likelihood that necessary functions and…","content_html":"Most JavaScript developers are keenly aware of what they add to the global object and do their best to namespace their work or sequester it in closures. Namespacing and closures reduce the likelihood that necessary functions and variables will be accidentally overwritten, causing errors to be thrown and interfaces to break. Unfortunately, the localStorage API (available in most modern browsers) doesn’t inherently support creating isolated caches for each script because the cache is site-specific and consists simply of key-value pairs. Internet Explorer’s userData behavior (which is available all the way back to IE5) does support sequestering the cache to a degree because you need to provide a name for it, but the API doesn’t make a whole lot of sense and isn’t at all equivalent to localStorage.
Using the native APIs, it’s quite easy to accidentally overwrite an existing key in the cache. Beyond that, a simple call to localStorage.clear() will wipe out not only your own data, but anything else stored in the local cache. It’s not good.
While working on eCSStender’s implementation of client-side caching, I came to realize the problems with the current state of things and sought to address them by implementing faux namespacing via prefixed keys. I’ve since copied that code out of eCSStender and created a small library named Squirrel.js that not only evens out the differences between localStorage and userData, but also makes it easier to manage your client-side data store in a manner unlikely to cause issues with other scripts also using client-side caching.
Here is a quick rundown of how Squirrel.js works:
\n```js\n // create a Squirrel instance\n var $S = new Squirrel( 'scale-song' );\n// write a value to the cache\n$S.write( ‘doe’, ‘ray’ );\n// read it back\n$S.read( ‘doe’ ); // ‘ray’
\n// write a value to a sub-cache\n$S.write( ‘song’, ‘doe’, ‘a dear, a female dear’ );\n// read back the original value\n$S.read( ‘doe’ ); // ‘ray’\n// read back the sub-cached value\n$S.read( ‘song’, ‘doe’ ); // ‘a dear, a female dear’
\n// removing a single property from the sub-cache\n$S.remove( ‘song’, ‘doe’ );\n// try to read the sub-cached value\n$S.read( ‘song’, ‘doe’ ); // null\n// read the root value\n$S.read( ‘doe’ ); // ‘ray’
\n// add some more content to the sub-cache\n$S.write( ‘song’, ‘doe’, ‘a dear, a female dear’ );\n$S.write( ‘song’, ‘ray’, ‘a drop of golden sun’ );\n// clear the whole sub-cache\n$S.clear( ‘song’ );\n// check that it’s been cleared\n$S.read( ‘song’, ‘doe’ ); // null\n$S.read( ‘song’, ‘ray’ ); // null\n// check that the root value’s still instact\n$S.read( ‘doe’ ); // ‘ray’
\n// remove a property form the main cache\n$S.remove( ‘doe’ );\n// check it’s value\n$S.read( ‘doe’ ); // null
\n// write a bit more data in the root and in a sub-cache\n$S.write( ‘doe’, ‘ray’ );\n$S.write( ‘song’, ‘doe’, ‘a dear, a female dear’ );\n$S.write( ‘song’, ‘ray’, ‘a drop of golden sun’ );\n// clear the whole cache\n$S.clear();\n// check it’s all gone\n$S.read( ‘song’, ‘doe’ ); // null\n$S.read( ‘song’, ‘ray’ ); // null\n$S.read( ‘doe’ ); // null
\n<p>For more, check out <a href="http://github.com/easy-designs/Squirrel.js">the Github page</a>. Feel free to let me know your thoughts on how easy it is to use and how it can be improved.</p>\nAs any competent JavaScript knows, it’s not cool to litter the global namespace with variables, functions, and the like. It’s far better to encapsulate your code in an object, a series of objects, or even a closure, exposing only what you absolutely need to via the global namespace. This helps reduce the potential for collisions that will probably cause your site to break.
\nOccasionally, however, even closures won’t help you trap a given variable. Case in point:
\n```js\n (function(){\n var a = b = 0;\n })();\n```\nIf you’re familiar with languages like PHP, you might think this simple closure creates two variables with the same value, but you’d be wrong. It creates a local variable, a and a global variable b, both of which have their value set to 0.
?>
\n<p>In exp:easy_gists this means of sharing the value assignment of variables is perfectly legit; the difference, however, is how JavaScript and PHP treat variable scope. By default, every variable declared in PHP is scoped to the function it is called within. Global variables only come into play when you use the <code class="php">global</code> declaration or the <code class="php">$_GLOBALS</code> array. In JavaScript, by contrast, any variables not instantiated with a <code class="js">var</code> are added to the global namespace. Hence the namespace pollution in the above example.</p>\n<p>Revisiting the closure, it’s best to rewrite it in one of two ways to maintain the variable scope:</p>\n```js\n (function(){\n var a = 0, b = 0;\n })();\nor
\n```js\n (function(){\n var a = 0, b = a;\n })();\n```\nWhich solution will work best is dependent solely on context. If you’re minifying the code and the value being assigned is anything more than a single character, the latter is probably the way to go.
\nTo help you discover and mitigate pollution in your own scripts (or to help you see what additions your standard JavaScript libraries are making to the global namespace), I’ve created a little script called EmissionsTest.js. It’s pretty easy to use, you simply include it as the first script on your page (preferably in the head of your document) and it does the rest. It will attempt to report its findings to the console (if your browser has one) or it will create a floating notice at the top of the page.
You won’t want to include this script on a production site and it’s still pretty basic, but it could be very useful for tracking down any accidental emissions in your script.
\n","url":"https://www.aaron-gustafson.com/notebook/give-a-hoot/","tags":["JavaScript","best practices"],"date_published":"2010-07-19T19:06:57Z"},{"id":"https://www.aaron-gustafson.com/notebook/disneystorecouk-in-retrograde/","title":"✍🏻 DisneyStore.co.uk in retrograde","summary":"Andy’s beautiful standards-based design is gone, replaced by a table-based pile of (ahem) tag soup. Being the gentleman that he is, Andy has chosen to remain silent on the issue , but he has provided a forum for anyone else who wants to…","content_html":"Andy’s beautiful standards-based design is gone, replaced by a table-based pile of (ahem) tag soup. Being the gentleman that he is, Andy has chosen to remain silent on the issue, but he has provided a forum for anyone else who wants to chime in. Molly posted an open letter to Disney which I think sums the whole thing up quite well:
\n\n\n","url":"https://www.aaron-gustafson.com/notebook/disneystorecouk-in-retrograde/","tags":["web standards","best practices"],"date_published":"2005-11-03T11:08:29Z"},{"id":"https://www.aaron-gustafson.com/notebook/new-tutorial-westhost-on-rails/","title":"✍🏻 New tutorial: Westhost on Rails","summary":"I have been hosting on Westhost for a little over four years now with no major complaints and I also host the majority of my clients there. They offer a lot of options for very little money and are always adding new features to the…","content_html":"Shame on you Disney.
\n
I have been hosting on Westhost for a little over four years now with no major complaints and I also host the majority of my clients there. They offer a lot of options for very little money and are always adding new features to the accounts. Unfortunately, Ruby on Rails is not one of them… yet.
\nAs I have begun working a bit more with Rails, I have been looking to get it installed on my server (as well as some of my clients’). One of the major half-truths of Rails evangelism is the ease of install, especially with a host running Apache 1.3. After doing a few rather painful installs myself for some new projects, I finally decided to document the process of installing Ruby on Rails at Westhost for my own knowledge and to help any others who may be trying to do the same. Hopefully, Westhost will soon start to offer Rails installs as part of their hosting packages, but, until then, I offer up this humble tutorial.
\n","url":"https://www.aaron-gustafson.com/notebook/new-tutorial-westhost-on-rails/","tags":["web development","best practices"],"date_published":"2005-10-02T15:40:20Z"},{"id":"https://www.aaron-gustafson.com/notebook/death-to-bad-dom-implementations/","title":"✍🏻 Death to bad DOM Implementations","summary":"I just encountered a DOM implementation issue in IE which took about three hours to solve (and like a year off my life). The story goes like this:","content_html":"I just encountered a DOM implementation issue in IE which took about three hours to solve (and like a year off my life). The story goes like this:
\nI could not, for the life of me, figure out why a form submitted in Firefox was coming through perfectly while it was missing fields in IE. The form in question has some normal fields and some dynamically generated ones (if JavaScript is enabled). The normal stuff was coming through fine, but I was getting no values for the dynamically generated fields when the form was submitted in IE. I checked the $_REQUEST variable (I am using PHP) to see what was coming through, just to be sure.
I immediately figured it was missing name attributes, but I was using the proper syntax to create the input elements via the DOM (note: the actual JS is more generic than this)
Indeed, when I looked at the page through the Web Accessibility Toolbar’s View Generated Source, it was indeed missing the name attribute:
After about another hour or two of fruitless Google-ing, I finally typed in the magic phrase (setting the name attribute in Internet Explorer) and ended up on Bennett McElwee’s blog post of the same name. Suddenly it was all clear and (as I expected) IE’s botched implementation of the DOM’s createElement function was to blame.
According to the MSDN page on the name attribute (linked and quoted in the blog entry):
\n\nThe NAME attribute cannot be set at run time on elements dynamically created with the createElement method. To create an element with a name attribute, include the attribute and value when using the createElement method.
\n
It continued with the following example:
\n\n```js\n var oAnchor = document.createElement(\"\");\n```\n
The script “solution” Bennett posted was somewhat of a red herring, however, as Firefox would actually execute the createElement intended for IE and end up with an element named “<input name=”company” />” which would be rendered on the page as
Perhaps you can see why this would be problematic.
\nI augmented Bennett’s script slightly and renamed the function createElementWithName so I wouldn’t have to use it on every element I created in the script:
I am not a super fan of the reference to document.all as it feels so much like browser sniffing. I am up for suggestions to improve the function if you have any ideas.
Anyway, I am posting this to hopefully save someone else from the major headache I had today.
\n","url":"https://www.aaron-gustafson.com/notebook/death-to-bad-dom-implementations/","tags":["JavaScript","web development","best practices"],"date_published":"2005-09-02T19:10:52Z"}]}