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

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

Core Architecture

This project implements unidirectional data flow using Redux Toolkit 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.

run

Serve app/src with any static web server that falls back to index.html for unknown paths (required for client-side routing).

Launch with browsersync

1. Install browsersync
2. git clone https://github.com/AdamBien/bce.design
3. cd app
4. Run: browser-sync src -f src -b "google chrome" --no-notify --single

The --single flag serves index.html for unknown paths — required for deep links like /add.

Launch with serve

cd app
npx serve -s src

Launch with zws (zero dependencies web server)

With a recent Java installation, serve the assets with zws:

cd app/src
zws.sh --single

The --single flag enables the index.html fallback for client-side routes; without it, deep links like /add return 404.

Launch with Quarkus

Serve the application as static resources using Quarkus:

1. Copy the app/src contents to src/main/resources/META-INF/resources/:

cp -r app/src/* [APP_DIR]/src/main/resources/META-INF/resources/

2. Run in development mode:

cd [APP_DIR]
mvn quarkus:dev

3. Access the application at http://localhost:8080

4. Build for production and run:

mvn package
java -jar target/quarkus-app/quarkus-run.jar

Quarkus automatically serves static files from META-INF/resources/ and provides production-ready features like compression, caching headers, and efficient resource serving.

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

Runtime dependencies (lit-html, Redux Toolkit) are bundled as ES modules into app/src/libs/ and mapped via the import map in index.html. To update, edit package.json in libs, then:

cd libs
npm install
npx rollup -c

external ingredients

1. lit-html
2. redux toolkit
3. rollup (for updates / optional)

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

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
• 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.