GitHub v1.3.1

One Runtime, Every Platform

Guide

Coralite is web-first because every target that matters ships a browser engine. The shared platform stays in core; the platform edges belong to plugins.

The short version

Desktop and mobile shells embed a browser engine. The same HTML, CSS and JavaScript run in a browser tab, an installed web app, an Electron or Tauri window, and a Capacitor or WebView screen. Storage, notifications, window controls and device APIs differ. Core owns the shared platform. Plugins own the edges.

The browser is the common runtime

Most "native" app shells are a packaged browser with a bridge to the operating system. Electron bundles Chromium. Tauri uses the system WebView. Capacitor and similar mobile shells use the platform WebView. In each case the renderer is a browser engine, and the app is the bundle loaded into it.

That is why Coralite does not need a different UI layer per platform. It compiles one component tree that runs in every engine. The differences are at the boundary: how the app is packaged, where it stores data, which privileged APIs it can call, and how the operating system hands it a file, a URL or a notification.

What an app is here

An app is a bundled interface, its local state, and its integration with the platform it runs on. The renderer can be a native toolkit or a browser engine; that choice is a delivery detail, not the architecture.

  • A website is the bundle served over HTTP, usually with a URL bar and no privileged APIs.
  • An installed web app is the same bundle installed with a manifest and, optionally, a service worker.
  • A desktop app is the same bundle inside an Electron or Tauri window, with native menus, files and updates.
  • A mobile app is the same bundle inside a WebView shell, with native storage, permissions, back navigation and store packaging.

"Web app" has a reputation for bloat and slowness. That reputation comes from what gets shipped, not from the browser: oversized frameworks, virtual DOM diffing, hydration of content that never changes, and server code bundled into the client. Coralite removes those causes rather than avoiding the platform.

What is shared

These are core assumptions because they exist in every browser engine Coralite targets:

Layer Shared behavior
Markup and stylingHTML, CSS, custom properties, cascade layers, light DOM, scoped component styles.
RuntimeDOM, events, AbortSignal, CustomEvent, forms, ElementInternals when the engine supports it.
Language and modulesES modules, dynamic import(), Intl, fetch, promises.
CoraliteTemplates, flat tokens, state, getters, slots, context, validation, build output.

What differs

These are not core assumptions. They are supplied by the target, usually through a plugin:

Concern Web Desktop shell Mobile shell
PersistenceCookies, IndexedDB, localStorageNative preferences, local files, SQLiteNative storage, files, keychain
Files and documentsFile input, downloadOpen/save dialogs, filesystem pathsDocument picker, share sheet
Windows and lifecycleTab and page lifecycleWindows, tray, menus, deep linksScreens, back gesture, app lifecycle
NotificationsWeb Notifications, permission promptNative notificationsPush and local notifications
PackagingHosting or CDNInstaller, signing, auto-updateStore bundle, signing, provisioning
Privileged APIsPermissions modelFull OS access through the bridgePermission-gated native modules

A plugin can expose any of these as client.context helpers. Components call storage.save() or window.minimize() without knowing whether the implementation is IndexedDB or a native bridge.

Targets

Web

The default output is static: every route becomes an HTML file plus the assets it needs. Host it on a CDN, an object store, or any static host. Request-time rendering is opt-in through the library API when a page must be assembled per request.

Web-only concerns stay optional: SEO metadata, canonical URLs, CSP, sitemaps, feeds and the SPA router plugin. See Building Applications for the delivery modes.

Installed web

Add a manifest, icons and, if offline behavior is required, a service worker. This is still the web target: installation changes how the app is launched, not how it renders. Service worker generation is a plugin or project concern, not a core assumption.

Desktop shell

Package the built output inside Electron or Tauri. The shell provides the window, menus, file dialogs, auto-update and privileged APIs. A target plugin typically does three things:

  • writes the shell manifest or packaging files in onAfterBuild
  • exposes window, filesystem and updater helpers through client.context
  • adjusts asset paths with baseURL when the bundle is loaded from the filesystem instead of a server

Installers, signing and notarization remain the responsibility of the shell toolchain. Coralite produces the bundle those tools package.

Mobile shell

Package the same output inside Capacitor or a comparable WebView shell. The adapter supplies the native bridge: storage, notifications, permissions, share sheet, back navigation and deep links. The renderer and the component tree do not change.

Two details matter in practice. Absolute route links must be reconciled with the shell's origin, and the back gesture must be mapped to the router or to history. Both belong in the target plugin, not in every component.

What core guarantees

  • Zero client JavaScript by default. A component with no client() and no reactive state ships markup and CSS, not a runtime island.
  • No Virtual DOM. Templates are flat tokens; updates patch the bindings that depend on the changed state.
  • Server code is stripped. server() runs at build time and is removed from the browser bundle by AST analysis.
  • Portable output. Routes become HTML, CSS and ES modules with no Node runtime requirement.
  • Deterministic validation. Invalid templates, imports and component contracts fail before output ships.

Why web-based does not mean slow

The browser is not the bottleneck people remember. The bottleneck was the layer shipped on top of it. Coralite keeps native DOM, native forms and native events, avoids a diffing runtime, and emits only the JavaScript a component actually needs.

That claim is measured rather than asserted. The benchmark section runs the standard js-framework-benchmark suite and reports memory and scripting results against the frameworks that carry the reputation Coralite is trying to avoid.

Native toolkits remain the right choice when an app needs direct access to a platform API from the first frame, or when the product must not ship a browser engine at all. For interfaces that fit HTML, CSS and the DOM, a shell with Coralite's output can reach native-class responsiveness without carrying a framework runtime.

What plugins add

Need Extension point
Change build options for a targetonBeforeBuild returning { options }
Write a manifest, installer config or feedonAfterBuild plus app.writeFile
Rewrite rendered HTML or inject platform metadataonAfterPageRender, mutating result
Ship target componentsserver.components
Expose native capabilitiesclient.context, resolved per instance
Register global platform listenersclient.init with onCleanup
Add routes from a content sourceonPageSet returning paths

See Authoring Plugins for the hook contracts and the definePlugin reference for every option.

Choosing a target

  • Web first when search, sharing and zero-install access matter.
  • Installed web when the same app needs an icon, offline start and a standalone window.
  • Desktop shell when the app needs local files, menus, tray behavior or auto-update.
  • Mobile shell when the app needs store distribution, native storage, push or device permissions.

The components, state and styling stay the same across all four. Only the adapter and the platform-facing components change.