Quickstarter and sample application for building non-trivial web applications with minimal tooling, essential dependencies, high productivity, and no migrations.

Web standards first, external libraries last. Built directly on browser APIs - no framework lock-in, just native Web Components, ES modules, and modern JavaScript. Visit bce.design/web-components for more information.

Every external dependency is treated as a liability and continuously replaced with web standards: the Bulma CSS framework was removed in favor of plain CSS design tokens, and Redux Toolkit is superseded by reduction.js, a minimal standards-based store built on structuredClone. The single remaining runtime library is lit-html for declarative templating.

Core Architecture

This project implements unidirectional data flow with a Redux-style store for predictable state management. All state changes flow in one direction: Actions → Reducers → Store → View Components. The application follows the Boundary Control Entity (BCE) pattern for clear separation of concerns.

Two interchangeable store implementations are provided, selected via the import map in app/src/index.html: reduction.js (active default) — a minimal, standards-based implementation of the used Redux Toolkit API (configureStore, createAction, createReducer) that relies on structuredClone instead of Immer — or the original Redux Toolkit vendored in app/src/libs/. Application code imports @reduxjs/toolkit either way; switching is a one-line import map change.

run

There is nothing to build. Serve app/src with any static web server that falls back to index.html for unknown paths (required for client-side routing), e.g. with zws (zero dependencies web server, requires Java):

cd app/src
zws.sh --single

For deployment, copy app/src to any static host — an S3 bucket, a CDN, or the META-INF/resources/ folder of a Quarkus backend.

e2e tests

The e2e tests are available from:

tests

code coverage

The e2e tests with configured global code coverage is available from: codecoverage

IDE

1. Visual Studio Code
2. Setup: JS imports
3. lit-html plugin for syntax highlighting inside html templates
4. redux devtools chrome extension

update dependencies

There is no build system. Runtime dependencies are vendored as self-contained ES modules in app/src/libs/ and mapped via the import map in index.html. lit-html ships as a single dependency-free module, so an update is a plain file copy:

./update-lit-html.sh 3.3.3

external ingredients

1. lit-html
2. redux toolkit (optional — reduction.js, a minimal built-in implementation of the used API, is the active default; switch via the import map in index.html)

Client-side routing is implemented with web standards: the Navigation API and URLPattern — no router dependency required.

standards-based routing

app/src/app.js declares the route table, app/src/router.js implements the mechanics in ~30 lines:

initRouter(document.querySelector('.view'), [
    { path: '/',                 component: 'b-list' },
    { path: '/add',              component: 'b-bookmarks' },
    { path: '/edit/:bookmarkId', component: 'b-bookmarks' }
]);

Navigation is plain HTML: any <a href="/add"> whose URL matches a route is intercepted by the Navigation API and rendered client-side — no Router.go(), no link components. URLPattern uses the same :param syntax as router libraries (both inherit it from path-to-regexp); named path parameters are passed to the routed component as attributes. The edit view demonstrates the pattern: the list renders <a href="/edit/${bookmark.id}">, the router creates <b-bookmarks bookmarkid="...">, and the component loads the bookmark into the form through the control layer.

Deliberate non-features: URLs matching no route fall through to regular browser navigation (external links keep working), and reloads are never intercepted (reload means reload). Both imply the serving requirement above — unknown paths must fall back to index.html.

what is BCE?

Boundary Control Entity (BCE) pattern organizes code by responsibility:

• Boundary: UI components (Web Components) - user interaction layer
• Control: Business logic and orchestration - application behavior
• Entity: State management and data models - domain objects

In this project:

• bookmarks/boundary/ - UI components like List.js, Add.js
• bookmarks/control/ - Logic like CRUDControl.js
• bookmarks/entity/ - State like BookmarksReducer.js

The bookmarks BC is the sample business component that keeps this template runnable and testable. After cloning, remove or replace it with your own BCs. Removing it touches four coupling points: the imports and the route registrations in app/src/app.js, the bookmarks reducer registration in app/src/store.js, the <h1> title in app/src/index.html, and the e2e specs in tests/ and codecoverage/.

BCE eliminates naming debates and provides instant code organization, helping avoid Parkinson's law of triviality. Learn more about BCE

unidirectional data flow

State always travels the same cycle — the view never mutates state directly. A boundary web component (Add.js) forwards user input to the control layer (CRUDControl.js), which dispatches an action to the store; the entity layer reducer (BookmarksReducer.js) computes the next state, and the store notifies all subscribed components (BElement.js), which re-render via lit-html:

graph LR
    Boundary([Boundary<br/>web components]) -->|user event| Control([Control<br/>action creators])
    Control -->|dispatches action| Store([Store<br/>reduction.js or Redux Toolkit])
    Store -->|state, action| Entity([Entity<br/>reducers])
    Entity -->|next state| Store
    Store -->|notifies subscribers| Boundary
    Store -.->|persists state| Storage([localStorage])

    classDef boundary fill:#d5e8d4,stroke:#82b366,color:#000
    classDef control fill:#e1d5e7,stroke:#9673a6,color:#000
    classDef entity fill:#fff2cc,stroke:#d6b656,color:#000
    classDef bc fill:#dae8fc,stroke:#6c8ebf,color:#000
    classDef ext fill:#fff2cc,stroke:#d6b656,color:#000,stroke-dasharray:5 5
    class Boundary boundary
    class Control control
    class Entity entity
    class Store bc
    class Storage ext

static hosting on Amazon S3

resources

Web Standards and Browser APIs Used

• Web Components - Custom Elements, Shadow DOM, HTML Templates
• Custom Elements - Define new HTML elements
• ES Modules - Native JavaScript module system
• Import Maps - Map bare module specifiers to URLs
• Container Queries - Responsive layouts based on container size
• localStorage - Browser storage for state persistence
• structuredClone - Immutable state updates in reduction.js, replacing Immer
• JSON - Data serialization for storage
• querySelector/querySelectorAll - DOM element selection
• ES6 Classes - JavaScript class syntax
• Template Literals - String templates with embedded expressions
• Arrow Functions - Concise function syntax
• Destructuring - Extract values from objects/arrays
• Spread Syntax - Expand arrays/objects
• Navigation API - Intercepts same-origin navigations for client-side routing
• URLPattern - Route matching without a router dependency

Testing & Development Tools

mockend serves as a mock backend with throttling functionality.

Mockend can slow down responses, which simplifies the testing of asynchronous view updates. Fetch requests in the control layer can be delayed for test purposes.

Article: Web Components, Boundary Control Entity (BCE) and Unidirectional Data Flow with redux

AI coding agents

Guidance for AI coding agents (Claude Code, Codex, Gemini CLI, ...) is maintained in AGENTS.md.

powered by airhacks.industries