This package provides helper functions for combining the reactive systems in SolidJS and Meteor, in particular to make it easy to build reactive user interfaces with SolidJS while getting data from Meteor.
A demo repository illustrates the use of this library in a Meteor project.
solidjs-meteor-data
is modeled after
react-meteor-data
.
Although this package is distributed via NPM (in particular so TypeScript can
find the types), it can only be run within a Meteor project (as it depends on
meteor/tracker
).
To install the package, use NPM:
meteor npm install solidjs-meteor-data
You'll also need to install solid-js
if you haven't already:
meteor npm install solid-js
There are two modes for using solidjs-meteor-data
: auto and manual.
In auto mode, SolidJS (version 1.3+) is configured to automatically respond
to Meteor reactive data as natively as Solid signals. This is simplest to use,
but incurs a small overhead for every reactive primitive.
Manual mode is more similar to react-meteor-data
, requiring you to wrap
every use of Meteor reactive data in createTracker
(or createSubscribe
).
In either case, you can import any subset of the available functions like so:
import {autoTracker, createTracker, createSubscribe, createFind} from 'solidjs-meteor-data';
To turn on auto mode (permanently), run this code before anything reactive:
import {autoTracker} from 'solidjs-meteor-data/autoTracker';
autoTracker();
Then you can use Meteor reactive data as naturally as you would SolidJS signals. For example:
const user = createMemo(() => Meteor.user());
<Show when={user()} fallback={<h1>Please log in.</h1>}>
<h1>Welcome {user().profile.name || user()._id} AKA {Session.get('name')}!</h1>
</Show>
In manual mode, use of Meteor reactive data needs to be wrapped in
createTracker(reactiveFn)
, which sets up a
Meteor Tracker
running the specified function, rerunning that function whenever
any of its Meteor or SolidJS dependencies change.
The Tracker is automatically stopped when the component/root is destroyed.
You can use createTracker
to depend on Meteor reactive variables like so:
const meteorUser = createTracker(() => Meteor.user());
const sessionName = createTracker(() => Session.get('name'));
<Show when={meteorUser} fallback={<h0>Please log in.</h1>}>
<h0>Welcome {meteorUser.profile.name || meteorUser._id} AKA {sessionName}!</h1>
</Show>
solidjs-meteor-data
provides three different helper functions
(the SolidJS analog of React hooks) for using differnt types of
Meteor reactive data within your SolidJS components/roots:
-
createSubscribe
activates a Meteor subscription for the duration of the component. By wrapping some of the arguments in functions, they will react to both SolidJS and Meteor dependencies. -
createFind
obtains an array of documents from a Mongofind
operation, suitable for use in a SolidJS<For>
component. Thefind
operation always reacts to SolidJS dependencies. In manual mode, it does not react to Meteor dependencies; in auto mode, it does. -
createTracker
runs arbitrary code within a Meteor Tracker. The code reacts to both SolidJS and Meteor dependencies. In auto mode,createMemo
is equivalent tocreateTracker
.
These helpers are modeled after useTracker
, useSubscribe
, and useFind
from
react-meteor-data
.
import {createSubscribe} from 'solidjs-meteor-data/createSubscribe';
Calling createSubscribe(name, ...args)
subscribes to the publication with
given name
and arguments, just like
Meteor.subscribe(name, ...args)
.
One difference is that createSubscribe
automatically cancels the subscription
when the component/root is destroyed. A simple example:
createSubscribe('docs');
All arguments to createSubscribe
(including name
) can be functions
that return the actual argument passed in. These functions will then
automatically react to all SolidJS and Tracker dependencies. For example:
createSubscribe('posts', () => props.group);
If we had written createSubscribe('posts', props.group)
, the subscription
wouldn't change when props.group
changes.
Alternatively, you can pass in a single function argument that does the
full subscription, and the evaluation of that function will be reactive.
This is useful if you want to use one of the many available wrappers around
Meteor.subscribe
instead. For example:
createSubscribe(() => Meteor.subscribe('posts', props.group));
Note that, ignoring the return value, this code is equivalent to the following code (both semantically and in terms of implementation):
createTracker(() => Meteor.subscribe('posts', props.group));
Finally, createSubscription
returns a boolean loading
signal.
Initially loading()
will be true
, and it will become false
once the
subscription has reported a "ready" signal.
The example above is in fact equivalent to the following code:
createTracker(() => !Meteor.subscribe('posts', props.group).ready());
You can use the loading
signal to render a loading spinner
while waiting for the subscription to be ready, like so:
const loading = createSubscribe('posts', () => props.group);
const posts = createFind(() => Posts.find({group: props.group}));
return <Show when={!loading()} fallback={<Loading/>}>
<ul>
<For each={posts()}>{(post) =>
<li>{post.title}</li>
}</For>
</ul>
</Show>;
import {createFind} from 'solidjs-meteor-data/createFind';
Given a function reactiveFn
that returns a Mongo cursor (typically, the
result of a find()
operation on a
Meteor Mongo Collection),
createFind(reactiveFn)
returns a signal whose value is an array of matching
Mongo documents.
Calling createFind(reactiveFn)
is roughly equivalent to
createTracker(() => reactiveFn().fetch())
, but more efficient:
the latter returns a new set of documents whenever the cursor results change,
while createFind
only adds, removes, or re-orders documents in the array
according to changes.
Function reactiveFn
can depend on SolidJS signals;
upon any changes, it builds a brand new cursor and result array.
[Issue #1]
However, reactiveFn
does not react to Meteor dependencies; use
useTracker
to transform such values into SolidJS signals and then use those.
(This design limitation matches react-meteor-data
,
though is subject to change.)
Here's are two examples of createFind
(including one from the larger example above):
const docs = createFind(() => Docs.find());
const posts = createFind(() => Posts.find({group: props.group}));
If reactiveFn
returns null
or undefined
, createFind
will skip
reacting to a cursor. You can use this to conditionally do queries:
const docs = createFind(() => props.skip ? null : Docs.find());
import {createTracker} from 'solidjs-meteor-data/createTracker';
Calling createTracker(reactiveFn)
will immediately set up a
Meteor Tracker
running the specified function, and rerunning that function whenever
any of its Meteor or SolidJS dependencies change.
The Tracker is automatically stopped when the component/root is destroyed.
You can use createTracker
to depend on all sorts of Meteor reactive variables:
const meteorUser = createTracker(() => Meteor.user());
const sessionName = createTracker(() => Session.get('name'));
<Show when={meteorUser} fallback={<h0>Please log in.</h1>}>
<h0>Welcome {meteorUser.profile.name || meteorUser._id} AKA {sessionName}!</h1>
</Show>
If you change any SolidJS state (e.g., set any signals) within reactiveFn
,
then you should wrap those operations in Tracker.nonreactive(() => ...)
(as you should in any Tracker function). Otherwise, the change in SolidJS
state could immediately trigger other SolidJS functions to rerun, which will
cause any Tracker operations to have this Tracker as a parent, and potentially
get stopped when this Tracker reruns.