# The no-build browser frontend

Connect's screens are plain JavaScript ES modules, HTML and CSS, served exactly as they are in the repository. There is no bundler, no transpiler and no `package.json`. The browser resolves the imports itself. Third-party browser code is vendored as single files with recorded checksums, and heavy features such as the softphone and the 3D office load only when opened.

- **Status:** Reference
- **Audience:** both, developer
- **Last verified:** 2026-11-02
- **Canonical:** https://connectbyjbrh.com/docs/technology/browser-modules/

## What it is

ES modules are JavaScript's native module system, supported by every current browser. A file declares `import` and `export`, and the browser fetches the graph. There is no build step between the source and what runs.

Connect's frontend is organised as a tree. `FRONTEND-MAP.md` says which file owns a route, an element and a style layer. The six product apps live under `webapp/apps/`, the Owner console under `webapp/src/`, and shared design tokens in `apps/shared/tokens.css`.

**Category** — Frontend architecture
**Build step** — None. Files are served as committed
**Check** — `tools/frontend_check.py`: every import resolves, every export exists, everything parses
**Reference** — [MDN: JavaScript modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules)

## Where Connect uses it

| Place in Connect | What it does there |
|---|---|
| `webapp/src/` | The Owner console: features, services (`session.js`, `stream.js`, `tenant-adapt.js`) and UI |
| `webapp/apps/` | Email, WhatsApp, Voice, CRM, Sales and Operations |
| `webapp/vendor/` | JsSIP, three.js, GSAP, Lenis and AutoAnimate, checksummed |
| `webapp/docs/` | This documentation: generated static HTML with no framework |

## How it connects

1. The browser loads `index.html` and the entry module
2. Imports are fetched as the graph needs them
3. Heavy features (`softphone`, Live Office) are dynamically imported on first use
4. Services talk to `/api/*` and the event stream
5. `tenant-adapt.js` rewrites Owner paths for customer sessions

## Benefits and limits

What it gives Connect:

- What is reviewed is what runs: no build output to drift from the source.
- Deploys copy files, with nothing to compile on the host.
- Dynamic imports keep a failure in one feature from breaking the whole app.

Where it stops, and what Connect does about it:

- No tree-shaking or minification for Connect's own code. File size is managed by splitting and lazy loading.
- A dependency published only as CommonJS must be bundled once by hand and vendored. JsSIP is the example.
- One unresolved static import breaks every module that depends on it. A JsSIP CDN build once took the whole site down this way, which is why the frontend check exists.

## Security and privacy

- A strict Content Security Policy is easier to keep with no inline script and only same-origin modules ([CSP](/docs/technology/csp/)).
- Vendored files carry sha256 records, so a change to third-party code shows up in review.
- `tenantAdapt` is a convenience, not the boundary. The server's allowlist decides what a customer may call.

## Licence, cost and versions

| Question | Answer |
|---|---|
| Licence | Connect's own code; vendored libraries keep their own licences |
| Cost | None |
| Version | ES2020 or later in current browsers |
| Compatibility | Current Chrome, Edge, Firefox and Safari; checked from 320 to 1440 px |

## Troubleshooting

**A blank app after a change** — A module failed to resolve or parse. Run `python tools/frontend_check.py`, and read the browser console's first error.
**A feature works for the Owner and 403s for a customer** — An Owner path without a tenant rewrite or allowlist entry.
**An old screen after a release** — The browser cached a module. The application's cache headers make a revalidation fetch it ([HTTP caching](/docs/technology/http-caching/)).

## Official references

- [MDN: JavaScript modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules)
- [MDN: dynamic import()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import)
- [HTML standard: module scripts](https://html.spec.whatwg.org/multipage/webappapis.html#module-script)

## Questions

### Why no React or build tool?

Fewer moving parts. The deployed files are the reviewed files, deploys need no toolchain, and the module graph is checked by a script on every change. The trade-off is hand-managed splitting.

### Is the documentation built the same way?

The docs are pre-rendered HTML from `docs-source/` by `tools/docs_build.py`. They have no client-side framework and only a small script for the theme and search.

## Related

- [Content Security Policy](https://connectbyjbrh.com/docs/technology/csp/)
- [HTTP caching and revalidation](https://connectbyjbrh.com/docs/technology/http-caching/)
- [JsSIP browser softphone library](https://connectbyjbrh.com/docs/technology/jssip/)
- [three.js and the Live Office](https://connectbyjbrh.com/docs/technology/threejs/)
- [Web accessibility](https://connectbyjbrh.com/docs/technology/accessibility/)

## What this page is based on

- AGENTS.md §2 (Frontend)
- `webapp/vendor/README.md`
- `tools/frontend_check.py`
- `FRONTEND-MAP.md`
