Local (Beta)
When to Use Local
Decide when a Tulip module should stay server-first and when a local-first collection adds real value.
Local-first should be a deliberate module-level choice, not a default.
Strong fit for Local
Use a local-first module when most of these are true:
- the UI performs frequent edits, inserts, deletes, or reordering
- optimistic feedback materially improves the workflow
- users stay inside one screen or one record context for a while
- the working set is bounded or can be loaded in focused subsets
- the UI benefits from live derived views, counts, or filtered child lists
Examples:
- project or customer detail screens with nested child records
- inline editing workflows
- boards, lists, or dense management screens where latency is very visible
Weak fit for Local
Stay with the default server-first approach when most of these are true:
- the screen is mostly read-only
- mutations are infrequent
- the dataset is very large and there is no natural working subset
- filters and aggregations are primarily database-driven
- the UI does not need local reactive composition after the initial fetch
Examples:
- reporting screens
- audit or archive views
- high-volume modules where users scan pages instead of actively editing records
Decision guide
| Situation | Recommended approach | Why |
|---|---|---|
| Small or medium module with many inline edits | Full local collection | Best optimistic UX and simple live queries |
| Large module with a clear parent scope | On-demand local collection | Only hydrate the active subset |
| Large global list with mostly browsing | Server-first query | Avoid unnecessary client-side data hydration |
| Module still proving its UX shape | Start server-first, add local later | Keeps the first API smaller |
Important constraint
Local should not become a hidden requirement for Tulip components. Components must keep working for modules that never adopt collections.
That means:
- module APIs should still expose a normal query path
- local helpers should wrap or extend existing behavior instead of replacing it
- docs should always explain the non-local default alongside the local-first option
Practical recommendation
Treat Local as a UX optimization layer for the right modules, not as the new base architecture for all modules.