cometchat-flutter-v6-patterns
Project wiring for the Flutter v6 UI Kit — navigation (Navigator / go_router / auto_route), state management (bloc / riverpod / provider / getx), config & secrets, platform setup, and web/desktop caveats. Triggers: 'cometchat with go_router', 'cometchat with riverpod', 'where do I put init in flutter', 'dart-define cometchat', 'cometchat flutter web'.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- cometchat-flutter-v6-patterns
- license
- MIT
- metadata
- { "tags": "cometchat flutter patterns navigation state-management go-router riverpod config v6", "author": "CometChat", "version": "1.0.0" }
- description
- Project wiring for the Flutter v6 UI Kit — navigation (Navigator / go_router / auto_route), state management (bloc / riverpod / provider / getx), config & secrets, platform setup, and web/desktop caveats. Triggers: 'cometchat with go_router', 'cometchat with riverpod', 'where do I put init in flutter', 'dart-define cometchat', 'cometchat flutter web'.
- compatibility
- Flutter >=3.38.9; cometchat_chat_uikit ^6.2.0 (6.2.x; catalog compiler-verified vs 6.1.0, source-checked vs 6.2.0)
03 SKILL.md 正文
Ground truth: the CometChat side is
cometchat-flutter-v6-core; this skill only adds the DELTA for a given toolchain. Framework mechanics (go_router, riverpod,--dart-define) are baked Flutter knowledge, not kit API. Kit symbols come from the catalog.
Companion skills (read first)
cometchat-flutter-v6-core— install, credentials, the settings asset,init→login→render. This skill ASSUMES it.cometchat-flutter-v6-placement— WHERE the surface goes; this skill is HOW it hooks into your app's plumbing.
Use this skill when
Wiring the kit into a specific project shape, or debugging "where does init go" / "the theme resets on navigation" / "my secrets are in git".
Prerequisites & install
Covered by core. No new package.
Navigation (BAKED — the delta per router)
The kit uses plain Navigator.push/pop internally and in every recipe, which works under all of these — you do not have to convert its recipes.
- Plain
Navigator— nothing to do. Core's recipes are already this. go_router— register chat screens as routes and push withcontext.push('/chat/:uid'). The kit's own internal pops still work because go_router sits on the sameNavigator. Put the init/login gate above the router (wrapMaterialApp.router's builder, or gate inredirect) so no chat route can build before login resolves.auto_route— same principle: anAutoRouteGuardthat waits for login is the idiomatic gate.- Calling adds one requirement:
navigatorKey: CallNavigationContext.navigatorKeyonMaterialApp(→-calls). Withgo_router, pass the same key into the router config rather than creating a second one.
State management (BAKED)
The kit is self-contained — every widget drives its own BLoC internally. You do not wire the kit into your app's state layer, and you do not need flutter_bloc yourself.
- bloc / cubit — expose the logged-in user from your auth cubit; gate chat routes on it. Do not try to own the kit's internal blocs.
- riverpod — a
FutureProviderthat performsinitFromSettings+loginand which chat screens.when(...)on, is the cleanest gate. - provider / getx — same shape: one async init future, everything chat-related below it.
- Reading kit state —
CometChatUIKit.loggedInUseris the sync getter. For list state, use the widget'sstateCallBack/onLoad, not a global store.
Config & secrets (BAKED — Flutter-specific)
initFromSettings reads a bundled asset, so it cannot read --dart-define. Two honest options; state the trade-off and let the user choose:
- Keep
initFromSettingsand generatecometchat-settings.jsonat build time from your existing secret source (CI writes the file). KeepsintegrationSource="ai-agent"telemetry. - Use the classic
UIKitSettingsBuilder+CometChatUIKit.init(...)with--dart-definevalues. Works, but loses telemetry attribution.
Either way the Auth Key ends up in the app bundle and is dev-only — production means a server-minted auth token +
loginWithAuthToken(core'slifecycle.md). Do NOT gitignore the registeredcometchat-settings.jsonasset (a fresh clone / CI build then fails with "No file or variants found for asset") — commit a placeholder version (no real Auth Key) that dev/CI overwrite, and guard the real key with a pre-commit/CI check.
Platform setup (BAKED)
- Android —
minSdk = 26inandroid/app/build.gradle.kts(the docs' 24 is too low); INTERNET permission; calling adds camera/mic. - iOS —
platform :ios, '15.1'in the Podfile, thenpod install; photo/camera/mic usage strings for attachments and calls. Both floors come fromcometchat_calls_sdk, which the kit depends on unconditionally — they apply whether or not you use calling (DOCS-BACKLOG D7). - Web — the kit supports web, but plugin-backed features (media picker, calling) behave differently; verify anything you promise.
flutter run -d chromewith the same settings asset. - Desktop — not a documented target; if asked, say so honestly rather than guessing.
Common pitfalls (BAKED)
- Init inside a screen that can be re-entered (or inside a route builder) → repeated init. Gate ONCE at the root (
lifecycle.md). - A chat route reachable before login resolves → blank screen. Guard the route, not just the widget.
- Expecting
initFromSettingsto read--dart-define— it reads an asset. See above. - Adding
flutter_blocto "connect" the kit — unnecessary; the kit owns its blocs. - Two navigator keys when calling is on — the router and
CallNavigationContextmust share one. cometchat-settings.jsoncommitted — the Auth Key is in your repo.- Forgetting
WidgetsFlutterBinding.ensureInitialized()before an asset-reading init.
Verify it works
The app builds on each target platform you claim; chat routes are unreachable until login resolves; navigating away and back does not re-init; secrets are not in git; with calling on, an incoming call presents from any route.
04 同仓库更多 Skills
worktable-review-with-annotations
Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.
worktable-find-and-synthesize-context
Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.
worktable-create-or-update-docs
Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.
worktable-create-or-manage-records
Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.
worktable-create-or-manage-interactive-html
Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.
worktable-collaborate-threads
Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.