Svelte integration RFC

[jamesgpearce]

Hello everyone!

I'm proposing a new ui-svelte module for TinyBase that would provide first-class Svelte integration, similar to how the existing ui-react module provides React integration. This would enable Svelte developers to build reactive, local-first applications with TinyBase using idiomatic Svelte patterns.

Motivation

TinyBase currently has comprehensive React support through the ui-react module, which provides:

• 80+ reactive hooks for data access and mutations
• Pre-built components for declarative rendering
• Context-based dependency injection
• Full TypeScript support

However, Svelte is growing rapidly as a framework, particularly in the local-first and lightweight application space where TinyBase likes to live. Svelte's compile-time reactivity model and minimal runtime overhead make it a natural fit for TinyBase's philosophy of being tiny, fast, and developer-friendly.

Currently, Svelte developers can use TinyBase directly, but I suspect they miss out on the ergonomic, framework-specific bindings that make development smoother and more idiomatic.

Proposed Solution

I'd like to create a ui-svelte module that adapts TinyBase's reactive capabilities to Svelte's reactivity model. The module would provide three main categories of functionality:

1. Reactive Stores

Instead of React hooks, we'd provide factory functions that return Svelte readable/writable stores. These would automatically subscribe to TinyBase changes and clean up listeners on unsubscription.

Example - basic data access:

// Data reading stores
export function cell(tableId, rowId, cellId, store);
export function row(tableId, rowId, store);
export function table(tableId, store);
export function tables(store);
export function value(valueId, store);
export function values(store);

// Derived data stores
export function sortedRowIds(tableId, cellId, descending, offset, limit, store);
export function rowIds(tableId, store);
export function cellIds(tableId, rowId, store);

Usage in Svelte:

<script>
  import { cell, row } from 'tinybase/ui-svelte';
  import { myStore } from './store.js';
  
  const color = cell('pets', 'fido', 'color', myStore);
  const fidoData = row('pets', 'fido', myStore);
</script>

<div>Color: {$color}</div>
<div>Species: {$fidoData?.species}</div>

Example - more advanced features:

// Queries
export function resultTable(queryId, queries);
export function resultRow(queryId, rowId, queries);

// Indexes
export function sliceRowIds(indexId, sliceId, indexes);

// Metrics
export function metric(metricId, metrics);

// Relationships
export function linkedRowIds(relationshipId, firstRowId, relationships);
export function remoteRowId(relationshipId, localRowId, relationships);

// Checkpoints
export function checkpointIds(checkpoints);
export function checkpoint(checkpointId, checkpoints);

2. Writable Stores for Mutations

For two-way data binding (leveraging Svelte's bind: directive):

export function cellWritable(tableId, rowId, cellId, store);
export function valueWritable(valueId, store);

Usage:

<script>
  import { cellWritable } from 'tinybase/ui-svelte';
  import { myStore } from './store.js';
  
  const color = cellWritable('pets', 'fido', 'color', myStore);
</script>

<!-- Two-way binding! -->
<input bind:value={$color} />

3. Svelte Components

Pre-built components for declarative rendering:

<!-- CellView.svelte -->
<script>
  import { cell } from 'tinybase/ui-svelte';
  
  export let tableId;
  export let rowId;
  export let cellId;
  export let store;
  export let debugIds = false;
  
  const cellValue = cell(tableId, rowId, cellId, store);
</script>

{#if debugIds}
  <span data-cell-id={cellId}>
{/if}
{$cellValue ?? ''}
{#if debugIds}
  </span>
{/if}

Component hierarchy:

• CellView, RowView, TableView, TablesView
• ValueView, ValuesView
• ResultCellView, ResultRowView, ResultTableView
• SliceView, IndexView
• LinkedRowsView, LocalRowsView, RemoteRowView
• MetricView
• CheckpointView, BackwardCheckpointsView, ForwardCheckpointsView

4. Context Provider

Svelte's context API for dependency injection:

<!-- Provider.svelte -->
<script>
  import { setContext } from 'svelte';
  
  export let store = undefined;
  export let storesById = undefined;
  export let metrics = undefined;
  export let metricsById = undefined;
  export let indexes = undefined;
  export let indexesById = undefined;
  export let relationships = undefined;
  export let relationshipsById = undefined;
  export let queries = undefined;
  export let queriesById = undefined;
  export let checkpoints = undefined;
  export let checkpointsById = undefined;
  export let persister = undefined;
  export let persistersById = undefined;
  export let synchronizer = undefined;
  export let synchronizersById = undefined;
  
  setContext('tinybase', {
    store, storesById,
    metrics, metricsById,
    indexes, indexesById,
    relationships, relationshipsById,
    queries, queriesById,
    checkpoints, checkpointsById,
    persister, persistersById,
    synchronizer, synchronizersById
  });
</script>

<slot />

Usage:

<script>
  import Provider from 'tinybase/ui-svelte/Provider.svelte';
  import { createStore } from 'tinybase';
  
  const store = createStore();
</script>

<Provider {store}>
  <App />
</Provider>

Then in child components:

<script>
  import { getContext } from 'svelte';
  import { cell } from 'tinybase/ui-svelte';
  
  const { store } = getContext('tinybase');
  const color = cell('pets', 'fido', 'color', store);
</script>

5. Action Creators

For callback-based mutations:

export function useSetCell(store) {
  return (tableId, rowId, cellId, value) => {
    store.setCell(tableId, rowId, cellId, value);
  };
}

export function useAddRow(store) {
  return (tableId, row) => {
    store.addRow(tableId, row);
  };
}

export function useDelRow(store) {
  return (tableId, rowId) => {
    store.delRow(tableId, rowId);
  };
}

Usage:

<script>
  import { useSetCell } from 'tinybase/ui-svelte';
  import { myStore } from './store.js';
  
  const setCell = useSetCell(myStore);
  
  function updateColor(newColor) {
    setCell('pets', 'fido', 'color', newColor);
  }
</script>

<button on:click={() => updateColor('brown')}>
  Make Fido Brown
</button>

6. Store Creation Utilities

Memoized store creation (similar to useCreateStore in React):

export function createStoreOnce(initializer);
export function createMetricsOnce(store, config);
export function createIndexesOnce(store, config);
// etc.

Advantages

Hopefully these things would give you some advantages over direct TinyBase usage in Svelte:

1. Automatic Subscription Management: No need to manually add/remove listeners
2. Idiomatic Svelte: Works naturally with $ reactive references and bind: directives
3. Type Safety: Full TypeScript definitions with type inference
4. Reduced Boilerplate: Less code to wire up reactive data
5. Composability: Easy to create derived stores and combine data sources
6. Performance: Svelte's compile-time optimizations mean minimal runtime overhead
7. Consistency: Familiar API for peopl coming from ui-react

Comparison: ui-react vs ui-svelte

Feature	ui-react	ui-svelte
Data Access	Hooks (useCell, useRow)	Store factories (cell, row)
Reactivity	Runtime hooks with deps	Compile-time reactive statements
Mutations	Callback hooks	Action creators + writable stores
Components	JSX/TSX components	.svelte components
Context	React Context + Provider	Svelte context + Provider
Two-way Binding	Controlled components	Native bind: directive
Bundle Size	Runtime + hooks	Compile-time (smaller)
Rules	Rules of hooks	No special rules

Implementation goals

TypeScript Support

I would hope we can provide full type definitions with:

• Generic store types that infer from TinyBase schemas
• Component prop types
• Store factory return types

Testing

Gotta keep the 100% test coverage record up! So...

• Unit tests for store factories using Svelte's testing library
• Component tests for all Svelte components
• Integration tests with TinyBase operations

Documentation

• Comprehensive guide similar to "Using React Hooks"
• API documentation for all stores and components
• Migration examples for developers familiar with ui-react
• Demo applications showcasing Svelte + TinyBase patterns

Open questions for you all

1. Svelte Version: Should we target Svelte 4, Svelte 5, or both?
2. Naming Convention: Should store factories be prefixed (e.g., tinybaseCell) to avoid conflicts?
3. Writable Store API: How aggressive should we be with writable stores? Should every data accessor have a writable variant?
4. Component Customization: What level of component customization should we support (similar to ui-react-dom)?
5. SvelteKit Integration: Should we provide specific utilities for SvelteKit (SSR considerations)?
6. Size vs Features: Should we split into ui-svelte (core) and ui-svelte-components (like ui-react-dom)?

Community feedback requested!

This is a community RFC - I'm interested in feedback before committing to implementation. I'd love to hear from the community, especially:

• Svelte developers: Would you use this? What features are most important?
• ui-react users: What patterns work well that we should replicate?
• TinyBase users: Any concerns about maintaining another framework integration?
• Contributors: Interest in helping build this? 😎

Some specific questions:

1. What Svelte version should we target?
2. Should we provide writable stores for all data, or just selected use cases?
3. Are there Svelte-specific patterns we should embrace that don't exist in React?

Conclusion

A ui-svelte module would bring TinyBase's powerful reactive data management to the Svelte ecosystem with idiomatic, ergonomic bindings. It would reduce boilerplate, improve developer experience, and leverage Svelte's compile-time reactivity for optimal performance.

I believe this would be a valuable addition to TinyBase and would help grow adoption in the Svelte community, which aligns well with TinyBase's tiny and, er, svelte philosophies!

Looking forward to your thoughts and feedback.

[maietta]

Okay, firstly, this is fantastic to see proposed.

The spec and example code are clean, easy to understand, but I would stick to Svelte 5 rather than 4 unless you find it's easy enough to support both. Everything I do now is in Svelte 5 and TypeScript with the Bun runtime, so I am particularly interested. Building a community web portal that updates the UI in real-time right now via PostgreSQL's LISTEN/NOTIFY for backed stuff and Pocketbase for client-specific. Not really ideal.

Site note: I am aiming to begin shipping all my SvelteKit applications as a compiled binary. Some dependencies break this ability, so I would like to also see if the proposed RFC if implemented, would work in this scenario as well. Not a deal break, but it would be nice.

[jamesgpearce]

So basically you think we should lean in to this being more rune-based and target 5 onwards only?

[jamesgpearce]

(you have to be patient with me... I know very little about Svelte so I am trying to get up to speed here!!)

[sacrosanctic]

I don't think anyone is building libs targetting Svelte 4. And we encourage everyone to migrate ASAP.

[jamesgpearce]

OK so here's how I assume we could update this proposal to follow more of a rune-based pattern for Svelte v5.

Instead of store factories, we'd provide hooks that return reactive values directly:

// Data access hooks
export function useCell(tableId, rowId, cellId, store);
export function useRow(tableId, rowId, store);
export function useTable(tableId, store);
export function useValue(valueId, store);

// Two-way bindable hooks
export function useCellBindable(tableId, rowId, cellId, store);
export function useValueBindable(valueId, store);

Which you could then use like:

<script>
  import { useCell, useCellBindable } from 'tinybase/ui-svelte';
  
  // Read-only reactive value (no $ prefix needed!)
  let species = useCell('pets', 'fido', 'species', store);
  
  // Two-way bindable
  let color = useCellBindable('pets', 'fido', 'color', store);
  
  // Derived values with $derived
  let display = $derived(`${species} (${color})`);
</script>

<div>{species}</div>
<input bind:value={color} />

Am I thinking about that right?

One question that I would love the community to guide me on is... would we also need to provide v4 support? Or is everyone moving this way now?

[Chaddeus]

I think you should focus on Svelte 5. With the shift to runes I doubt there will be plans to maintain stores for long. You'd essentially be baking in something that may deprecate on you soon.

Runes are signals based and provide more granular reactivity.

Joy of Code has a lot about Svelte 5 runes: https://www.youtube.com/watch?v=tErKyuUTzsM&list=PLA9WiRZ-IS_zU2j29HQy478UCuHyDZQXC

I wonder if Rich Harris (creator of Svelte) and team would be willing to help?

[ollema]

my two cents: no need to provide Svelte 4 support.

is tinybase normally a client or server/SSR package?

sync/async?

depending on the answers to those questions it could mean that you mat want to look into the new async svelte API

[sacrosanctic]

Have you considered a class based implementation like what ai-sdk had done with their Svelte module.

https://ai-sdk.dev/docs/getting-started/svelte

[jamesgpearce]

Great feedback everyone - very helpful! Let's get this show on the road...

[Savy011]

I was trying to use tinybase for a little project of mine earlier this year and i discovered this repository by @polvallverdu. I extended it a bit to include other hooks which I needed. I was able to work with an API which works somewhat like this

<script>
    import { useLocalRowIds, useRow, useRowIds } from '$lib/db/hooks.svelte';
    import { store, relationships } from '$lib/db/store.svelte';

    let feeds = useRowIds(store, 'rss-feeds');
</script>

<div>
    {#each feeds.value as feedId (feedId)}
        {@const row = useRow(store, 'rss-feeds', feedId)}
        {@const entries = useLocalRowIds(relationships, 'rss-entry-to-rss-feed', feedId)}
        <Tile url="/feed/{row.value.slug}">
            <p>
                {#if row.value.favicon}
                    <img src={row.value.favicon} alt="favicon for {row.value.title}" />
                {/if}{row.value.title}
            </p>
            <p><Link href={row.value.url!}>{row.value.url}</Link></p>
            <p>{row.value.feed}</p>
            <p>Entries: {entries.value.length}</p>
            {#if row.value.lastCheckedAt}
                <Time time={row.value.lastCheckedAt} relative />
            {:else}
                <p>never updated...</p>
            {/if}
        </Tile>
    {/each}
</div>

and I declared the store and relationships like so

import { createStore, createRelationships } from 'tinybase/with-schemas';
import * as s from './schema';

export const store = createStore().setTablesSchema(s.tables);

export const relationshipIds = {
    ENTRY_TO_COLLECTION: 'entry-to-collections',
    RSS_ENTRY_TO_RSS_FEED: 'rss-entry-to-rss-feed',
} as const;

export type RelationshipIds = typeof relationshipIds;

export const relationships = createRelationships(store)
    .setRelationshipDefinition(
        relationshipIds.ENTRY_TO_COLLECTION,
        'entries',
        'collections',
        'inCollection'
    )
    .setRelationshipDefinition(
        relationshipIds.RSS_ENTRY_TO_RSS_FEED,
        'rss-feed-entries',
        'rss-feeds',
        'forRss'
    );

declaring the relationship Ids with that readonly object was basically just a hack to get autocomplete for the hooks cause i wasn't able to figure out how to get those id from the relationship store itself.

[polvallverdu]

Thank you for tagging. I'm open on improving and porting it to full svelte 5 runes, and transfer it to tinybase. It could be a good starting point.

I'm currently using it in https://tools.polv.dev and works really great (polvallverdu/tools.polv.dev in gh)

[polvallverdu]

I started some work on this in polvallverdu/svelte-tinybase#4, just for svelte 5