Skip to content

Commit d3a9391

Browse files
davidkpianodavidkpiano
committed
Update migration page
1 parent d7ce39c commit d3a9391

File tree

1 file changed

+70
-33
lines changed

1 file changed

+70
-33
lines changed

‎versioned_docs/version-5/migration.mdx

Lines changed: 70 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ XState version 5 is in beta, and compared to XState version 4, it is [feature co
2323

2424
:::
2525

26-
## Creating machines
26+
## Creating machines and actors
2727

2828
### Use `createMachine()`, not `Machine()`
2929

@@ -36,7 +36,7 @@ Breaking change
3636
The `Machine(config)` function is now called `createMachine(config)`:
3737

3838
<Tabs>
39-
<TabItem value="v5" label="XState v5">
39+
<TabItem value="v5" label="XState v5 beta">
4040

4141
```ts
4242
import { createMachine } from 'xstate';
@@ -62,6 +62,43 @@ const machine = Machine({
6262
</TabItem>
6363
</Tabs>
6464

65+
### Use `createActor()`, not `createActor()`
66+
67+
:::breakingchange
68+
69+
Breaking change
70+
71+
:::
72+
73+
The `createActor()` function has been renamed to `createActor()`:
74+
75+
<Tabs>
76+
<TabItem value="v5" label="XState v5 beta">
77+
78+
```ts
79+
import { createMachine, createActor } from 'xstate';
80+
81+
const machine = createMachine(/* ... */);
82+
83+
// ✅
84+
const actor = createActor(machine);
85+
```
86+
87+
</TabItem>
88+
<TabItem value="v4" label="XState v4">
89+
90+
```ts
91+
import { createMachine, createActor } from 'xstate';
92+
93+
const machine = createMachine(/* ... */);
94+
95+
// ❌ DEPRECATED
96+
const actor = createActor(machine);
97+
```
98+
99+
</TabItem>
100+
</Tabs>
101+
65102
### Use `machine.provide()`, not `machine.withConfig()`
66103

67104
:::breakingchange
@@ -73,7 +110,7 @@ Breaking change
73110
The `machine.withConfig()` method has been renamed to `machine.provide()`:
74111

75112
<Tabs>
76-
<TabItem value="v5" label="XState v5">
113+
<TabItem value="v5" label="XState v5 beta">
77114

78115
```ts
79116
// ✅
@@ -125,7 +162,7 @@ Breaking change
125162
The `machine.withContext(...)` method can no longer be used, as `context` can no longer be overridden in this manner. Use [input](input.mdx) instead:
126163

127164
<Tabs>
128-
<TabItem value="v5" label="XState v5">
165+
<TabItem value="v5" label="XState v5 beta">
129166

130167
```ts
131168
// ✅
@@ -135,7 +172,7 @@ const machine = createMachine({
135172
}),
136173
});
137174

138-
const actor = interpret(machine, {
175+
const actor = createActor(machine, {
139176
input: {
140177
money: 1000,
141178
},
@@ -173,7 +210,7 @@ Breaking change
173210
Actions are now in predictable order by default, so the `predictableActionArguments` flag is no longer required. Assign actions will always run in the order they are defined.
174211

175212
<Tabs>
176-
<TabItem value="v5" label="XState v5">
213+
<TabItem value="v5" label="XState v5 beta">
177214

178215
```ts
179216
// ✅
@@ -234,7 +271,7 @@ Breaking change
234271
Implementation functions now take in a single argument: an object with `context`, `event`, and other properties.
235272

236273
<Tabs>
237-
<TabItem value="v5" label="XState v5">
274+
<TabItem value="v5" label="XState v5 beta">
238275

239276
```ts
240277
// ✅
@@ -274,7 +311,7 @@ The `send(...)` action creator is removed. Use `raise(...)` for sending events t
274311
Read the documentation on the [`sendTo` action](actions.mdx#send-to-action) and [`raise` action](actions.mdx#raise-action) for more information.
275312

276313
<Tabs>
277-
<TabItem value="v5" label="XState v5">
314+
<TabItem value="v5" label="XState v5 beta">
278315

279316
```ts
280317
// ✅
@@ -324,7 +361,7 @@ Breaking change
324361
String event types can no longer be sent to, e.g., `actor.send(event)`; you must send an event object instead:
325362

326363
<Tabs>
327-
<TabItem value="v5" label="XState v5">
364+
<TabItem value="v5" label="XState v5 beta">
328365

329366
```ts
330367
// ✅
@@ -356,7 +393,7 @@ Breaking change
356393
String event types can no longer be sent to, e.g., `state.can(event)`; you must send an event object instead:
357394

358395
<Tabs>
359-
<TabItem value="v5" label="XState v5">
396+
<TabItem value="v5" label="XState v5 beta">
360397

361398
```ts
362399
// ✅
@@ -386,7 +423,7 @@ Breaking change
386423
The `cond` transition property for guarded transitions is now called `guard`:
387424

388425
<Tabs>
389-
<TabItem value="v5" label="XState v5">
426+
<TabItem value="v5" label="XState v5 beta">
390427

391428
```ts
392429
const machine = createMachine({
@@ -430,7 +467,7 @@ Breaking change
430467
Properties other than `type` on action objects and guard objects should be nested under a `params` property; `{ type: 'someType', message: 'hello' }` becomes `{ type: 'someType', params: { message: 'hello' }}`:
431468

432469
<Tabs>
433-
<TabItem value="v5" label="XState v5">
470+
<TabItem value="v5" label="XState v5 beta">
434471

435472
```ts
436473
// ✅
@@ -474,7 +511,7 @@ Breaking change
474511
Strict mode is removed. If you want to throw on unhandled events, you should use a wildcard transition:
475512

476513
<Tabs>
477-
<TabItem value="v5" label="XState v5">
514+
<TabItem value="v5" label="XState v5 beta">
478515

479516
```ts
480517
// ✅
@@ -523,7 +560,7 @@ Breaking change
523560
Eventless (“always”) transitions must now be defined through the `always: { ... }` property of a state node; they can no longer be defined via an empty string:
524561

525562
<Tabs>
526-
<TabItem value="v5" label="XState v5">
563+
<TabItem value="v5" label="XState v5 beta">
527564

528565
```ts
529566
// ✅
@@ -577,7 +614,7 @@ Breaking change
577614
External transitions previously specified with `internal: false` are now specified with `reenter: true`:
578615

579616
<Tabs>
580-
<TabItem value="v5" label="XState v5">
617+
<TabItem value="v5" label="XState v5 beta">
581618

582619
```ts
583620
// ✅
@@ -623,7 +660,7 @@ Breaking change
623660
The `in: 'someState'` transition property is removed. Use `guard: stateIn(...)` instead:
624661

625662
<Tabs>
626-
<TabItem value="v5" label="XState v5">
663+
<TabItem value="v5" label="XState v5 beta">
627664

628665
```ts
629666
// ✅
@@ -667,7 +704,7 @@ Breaking change
667704
The `state.history` property is removed. If you want the previous snapshot, you should maintain that via `actor.subscribe(...)` instead.
668705

669706
<Tabs>
670-
<TabItem value="v5" label="XState v5">
707+
<TabItem value="v5" label="XState v5 beta">
671708

672709
```ts
673710
// ✅
@@ -717,7 +754,7 @@ The available actor logic creators are:
717754
See [Actors](actors.mdx) for more information.
718755

719756
<Tabs>
720-
<TabItem value="v5" label="XState v5">
757+
<TabItem value="v5" label="XState v5 beta">
721758

722759
```ts
723760
// ✅
@@ -761,7 +798,7 @@ const machine = createMachine({
761798
</Tabs>
762799

763800
<Tabs>
764-
<TabItem value="v5" label="XState v5">
801+
<TabItem value="v5" label="XState v5 beta">
765802

766803
```ts
767804
// ✅
@@ -801,7 +838,7 @@ const machine = createMachine({
801838
</Tabs>
802839

803840
<Tabs>
804-
<TabItem value="v5" label="XState v5">
841+
<TabItem value="v5" label="XState v5 beta">
805842

806843
```ts
807844
// ✅
@@ -847,7 +884,7 @@ Breaking change
847884
`services` have been renamed to `actors`:
848885

849886
<Tabs>
850-
<TabItem value="v5" label="XState v5">
887+
<TabItem value="v5" label="XState v5 beta">
851888

852889
```ts
853890
// ✅
@@ -899,11 +936,11 @@ Breaking change
899936
The `actor.onTransition(...)` method is removed. Use `actor.subscribe(...)` instead.
900937

901938
<Tabs>
902-
<TabItem value="v5" label="XState v5">
939+
<TabItem value="v5" label="XState v5 beta">
903940

904941
```ts
905942
// ✅
906-
const actor = interpret(machine);
943+
const actor = createActor(machine);
907944
actor.subscribe((state) => {
908945
// ...
909946
});
@@ -924,24 +961,24 @@ actor.onTransition((state) => {
924961
</TabItem>
925962
</Tabs>
926963

927-
### `interpret()` accepts a second argument to restore state
964+
### `createActor()` (formerly `interpret()`) accepts a second argument to restore state
928965

929966
:::breakingchange
930967

931968
Breaking change
932969

933970
:::
934971

935-
`interpret(machine).start(state)` is now `interpret(machine, { state }).start()`
972+
`interpret(machine).start(state)` is now `createActor(machine, { state }).start()`
936973

937-
To restore an actor at a specific state, you should now pass the state into the `state` property of the `options` argument of `interpret(logic, options)`. The `actor.start()` property no longer takes in a `state` argument.
974+
To restore an actor at a specific state, you should now pass the state into the `state` property of the `options` argument of `createActor(logic, options)`. The `actor.start()` property no longer takes in a `state` argument.
938975

939976
<Tabs>
940-
<TabItem value="v5" label="XState v5">
977+
<TabItem value="v5" label="XState v5 beta">
941978

942979
```ts
943980
// ✅
944-
const actor = interpret(machine, { state: someState });
981+
const actor = createActor(machine, { state: someState });
945982
actor.start();
946983
```
947984

@@ -969,11 +1006,11 @@ Breaking change
9691006
Subscribing to an actor (`actor.subscribe(...)`) after the actor has started will no longer emit the current snapshot immediately. Instead, read the current snapshot from `actor.getSnapshot()`:
9701007

9711008
<Tabs>
972-
<TabItem value="v5" label="XState v5">
1009+
<TabItem value="v5" label="XState v5 beta">
9731010

9741011
```ts
9751012
// ✅
976-
const actor = interpret(machine);
1013+
const actor = createActor(machine);
9771014
actor.start();
9781015

9791016
const initialState = actor.getSnapshot();
@@ -1012,7 +1049,7 @@ Breaking change
10121049
The `actor.batch([...])` method for batching events is removed.
10131050

10141051
<Tabs>
1015-
<TabItem value="v5" label="XState v5">
1052+
<TabItem value="v5" label="XState v5 beta">
10161053

10171054
```ts
10181055
// ✅
@@ -1048,7 +1085,7 @@ Breaking change
10481085
The `machineConfig.schema` property is renamed to `machineConfig.types`:
10491086

10501087
<Tabs>
1051-
<TabItem value="v5" label="XState v5">
1088+
<TabItem value="v5" label="XState v5 beta">
10521089

10531090
```ts
10541091
// ✅
@@ -1096,7 +1133,7 @@ Breaking change
10961133
`machineConfig.tsTypes` has been renamed and is now nested as `machineConfig.types.typegen`:
10971134

10981135
<Tabs>
1099-
<TabItem value="v5" label="XState v5">
1136+
<TabItem value="v5" label="XState v5 beta">
11001137

11011138
```ts
11021139
// ✅

0 commit comments

Comments
 (0)