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/westhost-gets-rails/","title":"✍🏻 WestHost gets Rails","summary":"I received an email announcement yesterday that WestHost (my host of choice) is going to be offering Ruby on Rails for install through its Site Manager. I guess it means that, sometime this month, my tutorial on the subject will no…","content_html":"I received an email announcement yesterday that WestHost (my host of choice) is going to be offering Ruby on Rails for install through its Site Manager. I guess it means that, sometime this month, my tutorial on the subject will no longer needed. Still, I’m glad it will be a bit easier to set up Rails on WestHost now.
\n","url":"https://www.aaron-gustafson.com/notebook/westhost-gets-rails/","tags":["web development","open source"],"date_published":"2006-04-14T14:50:29Z"},{"id":"https://www.aaron-gustafson.com/notebook/oracle-opens-up/","title":"✍🏻 Oracle opens up","summary":"In hopes of stemming the massive explosion of open source database use, Oracle is preparing an “express” version of it’s Oracle Database 10g line: Oracle Database XE . Like many things on the web right now, it’s currently in beta, with…","content_html":"In hopes of stemming the massive explosion of open source database use, Oracle is preparing an “express” version of it’s Oracle Database 10g line: Oracle Database XE. Like many things on the web right now, it’s currently in beta, with a full release planned for late this year.
\nCourting the open source set is an interesting move for Oracle. PHP developers are the obvious target right now, but I wouldn’t be surprised to see some of the focus shifted to Rails developers in the near future.
\nHere’s a breakdown of some of the features/limitations:
\nI haven’t downloaded it to play yet, but there seems to be some fairly detailed instructions on both install and integration on the PHP end.
\n","url":"https://www.aaron-gustafson.com/notebook/oracle-opens-up/","tags":["open source","software development","business"],"date_published":"2005-11-03T15:25:17Z"}]}