Share the rules, respect the platform

[ 01 ]

Shared code is not identical behavior

A field operator with intermittent connectivity and a desktop administrator reviewing a report may use the same underlying workflow but need different interactions. Reusing the business rule is valuable; forcing identical layouts and navigation onto both screens is not.

React and TypeScript can share domain models, validation and API clients. Ionic React and Capacitor provide a route to mobile packaging and device integrations while retaining a web stack. A responsive web application or PWA may be a better fit when distribution, device APIs and offline behavior do not justify native packaging. The choice should follow actual operational requirements.

[ 02 ]

Keep platform boundaries visible

Put domain decisions behind platform-neutral functions and isolate device capabilities behind narrow interfaces. A notification adapter, camera integration or secure credential store can have a native implementation and a browser implementation with clearly stated limitations. Components should not assume that a plugin exists merely because the same code compiled.

API contracts deserve the same discipline. Parse and validate responses, map transport errors into actionable states, and keep the server authoritative for permissions and consequential writes. A Next.js web application can use server rendering for public content; it is not a requirement for an Ionic application, and introducing it does not automatically solve mobile offline concerns.

Share a design vocabulary rather than a fixed component hierarchy. Large touch targets, safe-area insets, keyboard behavior and screen-reader labels need device-specific testing. A compact desktop table may need a card or detail view on a phone.

[ 03 ]

Make synchronization a product decision

Offline support is not a checkbox. Decide which actions can be read from a cache, which can be queued and which must be blocked without a live connection. A queued draft is different from a remotely confirmed valve operation. The interface should communicate that distinction before the user relies on it.

For queued writes, persist a stable operation identifier and retry only operations the backend can safely deduplicate. Define conflict rules for concurrent edits: a version check may reject a stale change, while a field-level merge requires clear ownership and user feedback. Expire commands that should not be replayed after a long outage.

type SyncState =
  | { kind: 'local-draft' }
  | { kind: 'queued'; operationId: string }
  | { kind: 'confirmed'; serverVersion: string }
  | { kind: 'needs-review'; reason: string };

[ 04 ]

Measure the experience on the device

Large lists, high-frequency telemetry and unnecessary re-renders can exhaust a mid-range phone long before a desktop browser shows a problem. Virtualize long lists when appropriate, batch live updates and stop listeners when a view leaves the foreground. Profile memory and battery behavior as well as initial load time.

Keep the critical path small: defer optional modules, cache assets intentionally and provide a meaningful loading or error state. A stale service-worker cache can be worse than no cache if it serves an incompatible application shell after a backend contract changes. Version and test update behavior.

[ 05 ]

Choose a runtime from operational constraints

A responsive browser application is often the lowest-friction choice when a reliable network and browser capabilities are sufficient. A PWA can add installation and selected offline capabilities, but support for background execution and device integrations varies by platform and browser. Verify the target environment instead of assuming that installation gives a web app every native capability.

Capacitor packages a web application with access to native APIs through plugins. That can be a productive way to share a React codebase, but it introduces native build tooling, platform permissions, plugin maintenance and store release processes. A fully native implementation may be appropriate when the experience depends heavily on platform-specific interaction or a capability that a maintained plugin cannot support.

The decision is reversible only at a cost. Keep domain rules and network contracts independent of the runtime so a change in presentation or packaging does not require rewriting the business logic. Measure delivery speed against the ongoing cost of testing each supported platform and device class.

[ 06 ]

Design the local queue as durable work

A local queue should survive an application restart, preserve a stable operation identifier and record enough context to explain an item to the user. It also needs a retention policy and protection appropriate to the data stored on the device. Do not persist a bearer token in an arbitrary local database merely because the queue needs to authenticate later.

When connectivity returns, refresh identity and permission context before replaying work. Send operations in the order required by their dependencies, but avoid blocking an entire queue indefinitely behind one invalid item. A rejected operation should move to a review state with a reason and a safe next action rather than disappearing or retrying forever.

Conflict resolution is domain-specific. A stale note may be mergeable; an inventory adjustment or approval can require revalidation against current server state. Show the local version, the server version and the consequence of a proposed resolution when a person must decide. Automatic last-write-wins is a policy choice, not a universal synchronization algorithm.

[ 07 ]

Plan for clients that cannot update immediately

A web deployment can reach browsers quickly, but cached assets and open tabs can remain on an older version. Mobile app-store users may stay on a release for weeks. Backward-compatible API changes, explicit deprecation windows and observability by client version are therefore practical requirements, not only release-management details.

Additive response fields are generally easier to introduce than changing the meaning of an existing field. For a breaking change, support both contracts for a defined period or introduce a versioned operation. Test an old client against the new backend and test what happens when a new client receives a response from an older deployment during a rolling release.

A service worker update can also interrupt a workflow if it replaces assets while a user has unsaved work. Communicate when an update is ready, preserve drafts where appropriate, and ensure the new shell and its assets are compatible. A forced refresh should have a clear reason and should not quietly discard an operator’s input.

[ 08 ]

Test context, not just screen size

A responsive breakpoint does not simulate a field worker wearing gloves, using a low-brightness screen or moving between networks. Test keyboard and screen-reader access, touch target size, safe-area insets, orientation changes and the on-screen keyboard. Exercise the same critical task with slow responses and interrupted connectivity.

Operational data may contain private information. Limit local storage to what the workflow needs, remove data when a user signs out according to the product policy, and consider what happens on a shared or lost device. Platform secure storage can help protect credentials, but it is not a substitute for server-side revocation.

Collect errors in a way that distinguishes a network outage from a validation failure and an incompatible client version. Use privacy-conscious identifiers and avoid sending the contents of forms by default. A supportable mobile workflow is one where an operator and an engineer can both understand what happened without reconstructing it from screenshots.

Include installation and sign-in in device testing. A user switching organizations or signing out should not see the previous organization’s cached records on the next session. Verify that downloads, camera permissions and deep links fail with an explanation when the operating system denies access or the required capability is unavailable.

A release checklist should cover more than a successful build: test upgrade from the previous supported version, clean installation, recovery after an interrupted update and rollback of a backend change. Capture the versions of the app, operating system and API when diagnosing a failure, subject to the product’s privacy policy.

Support teams need a way to distinguish data that is saved on the server from data that remains only on a device. Expose that distinction in the workflow itself, not just in diagnostic logs. Before deleting local application data or reinstalling, a user should be warned if unsynchronized work would be lost.

[ 09 ]

Release is part of the architecture

Browser deployment and app-store distribution have different review, rollback and update cycles. Native plugins may require platform permissions and version-specific configuration. Test device permissions, background behavior, push notification delivery and deep links on real target platforms rather than assuming a browser simulation covers them.

A practical release plan includes compatible API versions, observable failures, secure secret handling and a way to diagnose errors without exposing private data. Feature flags can reduce rollout risk, but they add combinations to test and need an owner and retirement date.

I find the most useful shared abstraction is the one that protects an invariant across platforms. The UI can adapt to its environment while the rules for scope, validation and confirmed state remain consistent.

A mobile client that reports an unsent action as complete has not made the workflow simpler; it has hidden a failure.