Skip to content
Source
Sign inSign up
TanStack/store
Open History to see the last commit

quick-start.md

153 lines3.2 KB

1---
2title: Quick Start
3id: quick-start
4---
5​
6TanStack Store is, first and foremost, a framework-agnostic signals implementation.
7​
8It can be used with any of our framework adapters, but can also be used in vanilla JavaScript or TypeScript. It's currently used to power many of our library's internals.
9​
10## Store
11​
12You'll start by creating a new store instance, which is a wrapper around your data:
13​
14```typescript
15import { Store } from '@tanstack/store';
16​
17const countStore = new Store(0);
18​
19console.log(countStore.state); // 0
20countStore.setState(() => 1);
21console.log(countStore.state); // 1
22```
23​
24This `Store` can then be used to track updates to your data:
25​
26```typescript
27const unsub = countStore.subscribe(() => {
28 console.log('The count is now:', countStore.state);
29});
30​
31// Later, to cleanup
32unsub();
33```
34​
35You can even transform the data before it's updated:
36​
37```typescript
38const count = new Store(12, {
39 updateFn: (prevValue) => updateValue => {
40 return updateValue + prevValue;
41 }
42});
43​
44count.setState(() => 12);
45// count.state === 24
46```
47​
48And implement a primitive form of derived state:
49​
50```typescript
51let double = 0;
52const count = new Store(0, {
53 onUpdate: () => {
54 double = count.state * 2;
55 }
56})
57```
58​
59### Batch Updates
60​
61You can batch updates to a store by using the `batch` function:
62​
63```typescript
64import { batch } from '@tanstack/store';
65​
66// countStore.subscribers will only trigger once at the end with the final state
67batch(() => {
68 countStore.setState(() => 1);
69 countStore.setState(() => 2);
70});
71```
72​
73## Derived
74​
75You can also use the `Derived` class to create derived values that lazily update when their dependencies change:
76​
77```typescript
78const count = new Store(0);
79​
80const double = new Derived({
81 fn: () => count.state * 2,
82 // Must explicitly list dependencies
83 deps: [count]
84});
85​
86// Must mount the derived value to start listening for updates
87const unmount = double.mount();
88​
89// Later, to cleanup
90unmount();
91```
92​
93### Previous Derived Value
94​
95You can access the previous value of a derived computation by using the `prevVal` argument passed to the `fn` function:
96​
97```typescript
98const count = new Store(1);
99​
100const double = new Derived({
101 fn: ({ prevVal }) => {
102 return count.state + (prevVal ?? 0);
103 },
104 deps: [count]
105});
106​
107double.mount();
108double.state; // 1
109count.setState(() => 2);
110double.state; // 3
111```
112​
113### Dependency Values
114​
115You can access the values of the dependencies of a derived computation by using the `prevDepVals` and `currDepVals` arguments passed to the `fn` function:
116​
117```typescript
118const count = new Store(1);
119​
120const double = new Derived({
121 fn: ({ prevDepVals, currDepVals }) => {
122 return (prevDepVals[0] ?? 0) + currDepVals[0];
123 },
124 deps: [count]
125});
126​
127double.mount();
128double.state; // 1
129count.setState(() => 2);
130double.state; // 3
131```
132​
133## Effects
134​
135You can also use the `Effect` class to manage side effects across multiple stores and derived values:
136​
137```typescript
138const effect = new Effect({
139 fn: () => {
140 console.log('The count is now:', count.state);
141 },
142 // Array of `Store`s or `Derived`s
143 deps: [count],
144 // Should effect run immediately, default is false
145 eager: true
146})
147​
148// Must mount the effect to start listening for updates
149const unmount = effect.mount();
150​
151// Later, to cleanup
152unmount();
153```