Introducing Native Web

A tiny library for simple web components.

Native Web

There are many popular web app frameworks out there. But if you’re building a website, like a blog, a portfolio or a company site, where do you start these days?

The cost

Most people will go with one of these big frameworks. One they are comfortable with. But at what cost? It might cost you slower load times with all these kB added to your pages for features you won’t use. And it might add complexity where you don’t need, with these pages and pages of documentation you’ll have to learn, especially if you are starting out.


So vanilla HTML, CSS and JS, is it then? Yes and no. One thing that most of these frameworks have in common, and for good reasons, is a component-based architecture. No matter how big or small your project is, splitting your code into reusable components is always a good idea for maintainability. There is a way to incorporate encapsulated styles and scripts natively in components, and it’s supported in all modern browsers right now.

Web Components

Web Components are the primitive that we need and can use for a cost of 0kB. The problem with Web Components is that they are not the most user friendly, they require too much boilerplate code, and you’ll definitely miss some features from your favourite frameworks.

Native Web

Introducing Native Web. It brings all the basic features you’ll need, reduces boilerplate code and simplifies the use of Web Components. All in the smallest footprint possible. It’s the minimum viable library.

1kB gzipped


All it takes is one command to get started. It initializes a starter with build tools and base files. It uses the extremely fast bundler, esbuild. But of course, you can also add it to an existing project by importing it from npm.

npm init nativeweb


At its core, Native Web uses decorators. It’s an upcoming JavaScript spec that can be used right now with Babel’s decorators proposal. You’ll need it in your project, but it’s already included in the starter. With Babel included, you also have the benefit of being able to use the latest JavaScript syntax and any other proposals.


The decorators in Native Web simplifies component definition, adding styles, attribute properties, event listeners, custom external events and query selectors.


The @event decorator is particularly interesting because it enables multiple features and is different than what you generally see. Events are easily visible at the top of your component. Not scattered everywhere in your “HTML” like we generally see these days. They can be component events, child element events and external component events. They reduce duplication. Instead of inlining the event name and function on every element that needs it, Native Web uses a simple tag @name to link the event to the declaration at the top, and they’re grouped by event type.

External events

The @customEvent decorator creates namespaced global events. You can listen to other components dispatched custom events by specifying the component name in the event decorator. These events are automatically destroyed when the component is disconnected.


Styles can live within your component file or in an external .css.js file. They are shared between component instances with Constructable Stylesheets. It can be a single tagged template literal or an array of them to import global styles and settings. Postcss is included in the starter to enable the latest and future CSS specs, like nesting and custom media.


One thing that is not included in Native Web is some kind of virtual DOM or diffing. It can be helpful for an app where multiple parts need updating on state changes. But for most websites, it adds a lot of weight for not much use. It’s also a completely different mental model to learn and apply across your site. It can add complexity when you don’t need it. With Native Web, you simply have query selectors scoped to your components and global namespaced events.


One similar thing you can do natively with Web Components is to watch for attribute changes. You can update parts of your component or rerender it completely with this.update(). In Native Web, all Web Components lifecycle methods can be used without the word callback in the name and without the need of super. For simplicity’s sake.


This is only the first version of the library and the starter. There is much more to come. Next will be styleless base components. Stay tuned. In all, the goal is to release a complete toolbox of simple tools for building fast websites.