feat: web support [#237] by Silfalion · Pull Request #362 · clerk/clerk-sdk-flutter

Silfalion · 2026-03-10T15:40:41Z

Hi there, saw that we were waiting on the web support so thought I'd make a PR for it, hope this is ok. Summary down below.

Fixes: #237, #302

Depends on: #373

Summary

Add web platform support to the Clerk Flutter SDK.

Persistor refactor: Split DefaultPersistor into platform-specific implementations
(file system on native, localStorage on web) using conditional exports. A separate
barrel file (clerk_auth_persistor_web.dart) provides the web persistor to web-only
consumers, since package:web can't be exported from the main library.
Caching persistor: Split DefaultCachingPersistor into IO (file-based) and web
(IndexedDB) implementations with ETag support on both platforms.
Widget updates: Replace dart:io usage with universal_io across widgets for
cross-platform compatibility.
Misc: Replace dart:io with universal_io in API, telemetry, and logging internals.
Remove unused is_web utility files.

Copilot

Pull request overview

This PR adapts the Clerk Flutter + Dart SDKs to work on web by removing dart:io-based image/file handling, introducing conditional IO/web persistors, and switching image/logo/avatar flows to operate on raw bytes (Uint8List) with web storage via IndexedDB/localStorage.

Changes:

Replace File-based image handling with Uint8List across auth APIs and Flutter widgets (use Image.memory).
Split persistors into IO vs web implementations via conditional exports; add an IndexedDB-backed file-byte cache on web.
Add web-focused dependencies (universal_io, web) and a browser-only test scaffold for the web persistor.

Reviewed changes

Copilot reviewed 36 out of 36 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
packages/clerk_flutter/test/utils/default_caching_persistor_web_test.dart	Adds browser-only tests for the web persistor behavior.
packages/clerk_flutter/pubspec.yaml	Updates dependencies (adds `universal_io`/`web`, changes `clerk_auth` reference).
packages/clerk_flutter/lib/src/widgets/user/clerk_user_profile.dart	Switches profile image update API from `File` to `Uint8List`.
packages/clerk_flutter/lib/src/widgets/user/clerk_user_button.dart	Switches org creation logo parameter from `File` to `Uint8List`.
packages/clerk_flutter/lib/src/widgets/ui/platform_styled_dialog.dart	Replaces `dart:io` platform check with `universal_io`.
packages/clerk_flutter/lib/src/widgets/ui/editable_profile_data.dart	Reads picked images as bytes and passes `Uint8List` through callbacks.
packages/clerk_flutter/lib/src/widgets/ui/clerk_cached_image.dart	Renders cached images from bytes via `Image.memory`.
packages/clerk_flutter/lib/src/widgets/ui/clerk_avatar.dart	Allows avatar override via bytes instead of a `File`.
packages/clerk_flutter/lib/src/widgets/organization/create_organization_panel.dart	Reads logo bytes and uses `Image.memory` preview.
packages/clerk_flutter/lib/src/widgets/organization/clerk_organization_profile.dart	Updates org logo update path to accept `Uint8List`.
packages/clerk_flutter/lib/src/widgets/organization/clerk_organization_list.dart	Wires org creation panel submission to `Uint8List` logo.
packages/clerk_flutter/lib/src/utils/get_cache_directory.dart	Adds conditional export for cache directory getter.
packages/clerk_flutter/lib/src/utils/get_cache_directory_web.dart	Web cache directory getter returns null.
packages/clerk_flutter/lib/src/utils/get_cache_directory_io.dart	IO cache directory getter uses `path_provider`.
packages/clerk_flutter/lib/src/utils/default_caching_persistor.dart	Adds conditional export for IO vs web caching persistor.
packages/clerk_flutter/lib/src/utils/default_caching_persistor_web.dart	Implements web persistor + IndexedDB byte cache and network fetch.
packages/clerk_flutter/lib/src/utils/default_caching_persistor_io.dart	Updates IO persistor to cache/stream bytes instead of `File`.
packages/clerk_flutter/lib/src/utils/clerk_file_cache.dart	Changes `ClerkFileCache.stream` contract to return bytes.
packages/clerk_flutter/lib/src/utils/clerk_auth_config.dart	Uses conditional cache-directory getter when constructing default persistor.
packages/clerk_flutter/example/pubspec.yaml	Switches example to local path deps for `clerk_flutter`/`clerk_auth`.
packages/clerk_flutter/example/macos/Flutter/GeneratedPluginRegistrant.swift	Updates generated plugin registration list.
packages/clerk_flutter/example/lib/main.dart	Removes `exit(1)` usage and returns instead (no `dart:io`).
packages/clerk_auth/pubspec.yaml	Adds `universal_io`/`web` deps and normalizes quoting.
packages/clerk_auth/lib/src/utils/logging.dart	Switches to `universal_io` and gates `stdout.flush()` for web.
packages/clerk_auth/lib/src/models/api/api_response.dart	Uses `universal_io` `HttpStatus` for web compatibility.
packages/clerk_auth/lib/src/clerk_auth/persistor.dart	Removes IO-only `DefaultPersistor` implementation from the shared file.
packages/clerk_auth/lib/src/clerk_auth/persistor_web.dart	Adds web `DefaultPersistor` backed by `localStorage`.
packages/clerk_auth/lib/src/clerk_auth/persistor_io.dart	Adds IO `DefaultPersistor` backed by filesystem JSON cache.
packages/clerk_auth/lib/src/clerk_auth/persistor_default.dart	Adds conditional export to pick IO vs web persistor.
packages/clerk_auth/lib/src/clerk_auth/http_service.dart	Removes `dart:io` dependency (uses pure `http`).
packages/clerk_auth/lib/src/clerk_auth/auth.dart	Updates avatar/logo APIs to accept `Uint8List` instead of `File`.
packages/clerk_auth/lib/src/clerk_api/token_cache.dart	Uses `universal_io` for headers/constants.
packages/clerk_auth/lib/src/clerk_api/telemetry.dart	Uses `universal_io` for web-safe IO symbols.
packages/clerk_auth/lib/src/clerk_api/api.dart	Switches uploads from `File` to byte uploads (`Uint8List`).
packages/clerk_auth/lib/clerk_auth.dart	Exports conditional default persistor entry point.
packages/clerk_auth/lib/clerk_auth_persistor_web.dart	Adds explicit web-only persistor entry point for web consumers.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

MarkOSullivan94 · 2026-03-23T17:12:48Z

Hey @Silfalion 👋

Thank you for your contribution with this PR.

I've just ran your branch locally and I can see that the Clerk UI is not showing when runningclerk_flutter example on web:

I ran the web version with wasm and it required some changes to get it to run but afterwards the end result was the same as when I ran the dart2js version of the web build the Clerk UI is not displayed

I've pushed these changes to your branch:

6b31a1d
40ab3a4

Make sure you pull the changes before pushing to your branch

MarkOSullivan94 · 2026-03-23T17:16:50Z

I've fixed the merge conflicts after rebasing this branch on top of main

Silfalion · 2026-03-23T17:20:11Z

Hi @MarkOSullivan94 👋

Thank you as well for taking the time to check it.

The lack of UI is due to the change in dependencies of clerk_auth. The PR works on both packages so clerk_flutter needs to use clerk_auth from the PR instead of the published one.

Regarding this specifically, I should've mentioned a pubspec_overrides.yaml was needed for testing, sorry. Could you check again after adding it, please?

MarkOSullivan94 · 2026-03-23T17:32:04Z

@Silfalion I've just pushed another two commits, one is to add passkeys-js bundle which is required by passkeys package to work on web.

Silfalion · 2026-03-23T17:36:13Z

No worries at all! And thank you for the commit.

MarkOSullivan94 · 2026-03-23T17:38:32Z

@Silfalion can you adjust the title and the description of the PR?

The standard we use for the title is something like this:

feat: documentation [#341]

We always do this for the description:

Resolves #341

Silfalion · 2026-03-23T17:41:07Z

Of course, should I reference this issue?

#237

MarkOSullivan94 · 2026-03-23T18:14:37Z

Of course, should I reference this issue?

#237

Yes please!

Also can you add #373 in the description

Silfalion · 2026-03-23T18:27:38Z

Done @MarkOSullivan94 :)

MarkOSullivan94 · 2026-03-23T22:03:57Z

I'm on vacation the rest of the week so further updates will come either from @shinyford or @slightfoot until I return on Monday

Silfalion · 2026-03-24T01:01:13Z

Sounds good, have a good one!

…ations # Conflicts: # packages/clerk_auth/lib/src/clerk_auth/persistor.dart

…support

- Restore hosted clerk_auth version constraint (path: was dev-only) - Use barrel import for get_cache_directory instead of inline conditional - Add IndexedDB error handling in web persistor initialize() - Narrow catch block to http.ClientException in web persistor - Fix stale doc comments (files->bytes, localStorage->IndexedDB) - Rename misleading test to match actual assertions

…from persistor

shinyford · 2026-03-30T14:46:28Z

Hi - the following is now working:

Compiles to js
Compiles to wasm
Working login flows:
- password
- phone code
- email code
- email link

Not working:

oauth sign in (scheme not registered issue)
passkeys (not working: will raise separate ticket)

Please take a look and check that things are happening as you expect.

Cheers

Nic

shinyford · 2026-03-30T15:04:18Z

BTW @Silfalion, ~~this PR also resolves issue #302. Please could you add that to the opening post? Cheers!~~ Don't worry, turns out I can edit it myself. Done. Cheers!

clerk#237]

…kage

…to package

MarkOSullivan94

LGTM 👍

MarkOSullivan94 · 2026-03-30T16:27:52Z

Before merging we should get @slightfoot to review this PR

artob · 2026-04-14T15:45:16Z

@slightfoot @MarkOSullivan94 Any news on this, pretty please?

Copilot AI review requested due to automatic review settings March 10, 2026 15:40

Copilot started reviewing on behalf of Silfalion March 10, 2026 15:41 View session

Copilot AI reviewed Mar 10, 2026

View reviewed changes

diegotori suggested changes Mar 19, 2026

View reviewed changes

Comment thread packages/clerk_auth/lib/src/clerk_api/api.dart

MarkOSullivan94 force-pushed the feat/web-support branch from 40ab3a4 to 778acc3 Compare March 23, 2026 17:16

MarkOSullivan94 marked this pull request as draft March 23, 2026 17:34

Silfalion changed the title ~~Feat/web support~~ feat: web support [#237] Mar 23, 2026

MarkOSullivan94 mentioned this pull request Mar 23, 2026

chore(clerk_flutter): web support preparation [#373] #374

Closed

Silfalion and others added 11 commits March 30, 2026 11:01

feat(clerk_auth): refactor persistor into platform-specific implement…

608d0de

…ations # Conflicts: # packages/clerk_auth/lib/src/clerk_auth/persistor.dart

chore(clerk_auth): update API, telemetry, and misc internals for web …

00f9bd4

…support

feat(clerk_flutter): split caching persistor for web with IndexedDB

67e0852

fix(clerk_flutter): update widgets for web compatibility

32be14e

chore(clerk_flutter): update dependencies and example app

81a5c47

test(clerk_flutter): add web caching persistor tests

25d7ecc

chore(clerk_flutter): upgrade app_links version in example [clerk#373]

d1fb1d3

fix(clerk_flutter): example index.html for wasm [clerk#373]

b2ea20d

refactor(clerk_flutter): remove DefaultPersistor and DirectoryGetter …

f00274a

…from persistor

feat(clerk_flutter): added passkeys web js bundle

fd6ead8

MarkOSullivan94 force-pushed the feat/web-support branch from 1799263 to fd6ead8 Compare March 30, 2026 09:01

MarkOSullivan94 and others added 4 commits March 30, 2026 12:30

fix(clerk_flutter): platform safe platform check

b067fb5

fix(clerk_flutter): etag null check

c0073a0

feat: upgrade flutter to support web/wasm [clerk#237]

7b0e316

fix: stop cached images flickering [clerk#237]

19aae58

MarkOSullivan94 force-pushed the feat/web-support branch from ca67e8b to 19aae58 Compare March 30, 2026 14:31

fix: improve passkeys on web [clerk#237]

6f923b9

MarkOSullivan94 marked this pull request as ready for review March 30, 2026 14:56

feat(clerk_auth): global isWeb platform check [clerk#237]

06c9761

MarkOSullivan94 reviewed Mar 30, 2026

View reviewed changes

Comment thread packages/clerk_auth/lib/src/utils/logging.dart Outdated

MarkOSullivan94 added 2 commits March 30, 2026 18:04

refactor(clerk_auth): renamed persistor files and moved inside package [

ab63dc2

clerk#237]

refactor: formatting [clerk#237]

4c041c1

MarkOSullivan94 reviewed Mar 30, 2026

View reviewed changes

Comment thread packages/clerk_flutter/lib/src/widgets/ui/clerk_vertical_card.dart

refactor(clerk_flutter): renamed get_cache_directory and added to pac…

37df739

…kage

MarkOSullivan94 force-pushed the feat/web-support branch from 1d60c62 to 37df739 Compare March 30, 2026 16:17

refactor(clerk_flutter): renamed default_caching_persistor and added …

c1a9cae

…to package

MarkOSullivan94 approved these changes Mar 30, 2026

View reviewed changes

slightfoot self-requested a review April 7, 2026 11:18

slightfoot assigned MarkOSullivan94 Apr 7, 2026

slightfoot added enhancement New feature or request clerk_auth package: clerk_auth clerk_flutter package: clerk_flutter labels Apr 7, 2026

MarkOSullivan94 modified the milestone: v0.0.16-beta May 1, 2026

Conversation

Silfalion commented Mar 10, 2026 • edited by shinyford Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

MarkOSullivan94 commented Mar 23, 2026

Uh oh!

MarkOSullivan94 commented Mar 23, 2026

Uh oh!

Silfalion commented Mar 23, 2026

Uh oh!

MarkOSullivan94 commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Silfalion commented Mar 23, 2026

Uh oh!

MarkOSullivan94 commented Mar 23, 2026

Uh oh!

Silfalion commented Mar 23, 2026

Uh oh!

MarkOSullivan94 commented Mar 23, 2026

Uh oh!

Silfalion commented Mar 23, 2026

Uh oh!

MarkOSullivan94 commented Mar 23, 2026

Uh oh!

Silfalion commented Mar 24, 2026

Uh oh!

shinyford commented Mar 30, 2026

Uh oh!

shinyford commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

MarkOSullivan94 left a comment

Choose a reason for hiding this comment

Uh oh!

MarkOSullivan94 commented Mar 30, 2026

Uh oh!

artob commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

Silfalion commented Mar 10, 2026 •

edited by shinyford

Loading

MarkOSullivan94 commented Mar 23, 2026 •

edited

Loading

shinyford commented Mar 30, 2026 •

edited

Loading

artob commented Apr 14, 2026 •

edited

Loading