Connect by JBRH Open Connect

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 What this means
Audience
both, developer
Last verified
Product version
6.3.2

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

Where Connect uses it#

Place in ConnectWhat 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).
  • 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#

QuestionAnswer
LicenceConnect's own code; vendored libraries keep their own licences
CostNone
VersionES2020 or later in current browsers
CompatibilityCurrent 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).

Official references#

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.