You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit a5f34de
Browse filesBrowse the repository at this point in the historyBrowse files
Publishing a 0.8 app moves it to the current Zero whenever nothing would be
lost, and otherwise publishes 0.8 with diagnostics naming each blocker.
sf zero migrate app becomes a preview of that conversion.
Copy file name to clipboardExpand all lines: content/(dynamic)/zero-migrate.mdx
+24-15Lines changed: 24 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,17 +1,17 @@
1
1
---
2
2
title: Migrate from Zero 0.8
3
-
description: Zero 0.8 apps keep working and publishing. Automatic migration to the current Zero is coming; until then, port the source by hand with sf zero migrate app.
3
+
description: Publishing a Zero 0.8 app moves it to the current Zero whenever nothing would be lost. When something would, it publishes as 0.8 and tells you exactly what to change.
4
4
sidebar:
5
5
order: 8
6
6
---
7
7
8
-
Your Zero 0.8 app keeps working. Its Space keeps serving, and you can keep publishing updates to it. New Spaces start on the current Zero, the `zero.config.ts` compiler described in [Dynamic sites with Zero](/zero).
8
+
Your Zero 0.8 app keeps working. Publish it with a current CLI and it moves to the current Zero, the `zero.config.ts` compiler described in [Dynamic sites with Zero](/zero), whenever nothing would be lost. When something would, it publishes as 0.8, keeps serving, and the receipt lists each blocker. New Spaces start on the current Zero.
9
9
10
10
A Zero 0.8 app is one built on `@spacefast/zero`: a `capsule()` in `server/index.ts`, declared in `sf.jsonc` as `"runtime": { "kind": "zero" }`.
11
11
12
12
## Keep working on a 0.8 app
13
13
14
-
A 0.8 app keeps its own local dev server and database commands. The [`sf zero`](/cli/zero) development commands are for `zero.config.ts` apps, not for this one. The exception is `sf zero migrate app`, which [ports it](#port-the-source-now).
14
+
A 0.8 app keeps its own local dev server and database commands. The [`sf zero`](/cli/zero) development commands are for `zero.config.ts` apps, not for this one. The exception is `sf zero migrate app`, which [previews the conversion](#preview-the-conversion).
15
15
16
16
### Run it locally
17
17
@@ -55,21 +55,34 @@ sf db migrate
55
55
56
56
Pass `--port <n>` or `--local-url <url>` to `sf db`, `sf db list`, `sf db dump`, or `sf db export` to read a running `sf dev` server instead of the live version.
57
57
58
-
## What's coming
58
+
## Migrate by publishing
59
59
60
-
Automatic migration is coming. This page will show how to run it when it ships. Until then, nothing changes for your app, and you do not need to do anything.
60
+
From the 0.8 project root, publish as usual:
61
61
62
-
## Port the source now
62
+
```bash
63
+
sf publish --space spc_123 --json
64
+
```
65
+
66
+
The CLI converts the app on your machine and checks the result. Then one of two things happens:
67
+
68
+
| Result | What you see |
69
+
| --- | --- |
70
+
| Nothing would be lost | The Space moves to the current Zero, on its existing tables. `version.zero.migration.status` is `migrated`|
71
+
| Something would be lost | The app publishes as 0.8 and keeps serving. `status` is `refused`, and `diagnostics` lists each blocker with its `code`, `file`, `line`, `feature` and `fix`|
63
72
64
-
To start early, convert the source on your machine. The converter writes a new project and never touches the Space.
73
+
Fix what `diagnostics` names and publish again. Nothing about your app changes until a publish migrates it. `waiting_on_runtime` means the app can move but the Space's runtime can't run the current Zero yet. It publishes as 0.8, and the next publish after the runtime update migrates it.
74
+
75
+
## Preview the conversion
76
+
77
+
To read the converted source before you publish, run the converter yourself. It writes a new project and never touches the Space.
65
78
66
79
```bash
67
80
sf zero migrate app --from zero-0.8 ./old-app --out ./candidate --space spc_123 --dry-run
68
81
sf zero migrate app --from zero-0.8 ./old-app --out ./candidate --space spc_123
69
82
sf zero check ./candidate
70
83
```
71
84
72
-
`./old-app` is the 0.8 project root, the directory with `sf.jsonc` and `server/index.ts`. `--out` must be a new directory, and a refusal writes nothing. Pass the Space's ID with `--space`whenever the capsule declares tables: the converter binds each table to the exact MySQL table the Space already stores it in. Add `--users` when the Space has Space Users turned on but the capsule has no `auth` declaration.
85
+
`./old-app` is the 0.8 project root, the directory with `sf.jsonc` and `server/index.ts`. `--out` must be a new directory, and a refusal writes nothing. Pass the Space's ID with `--space`so the converter binds each table to the exact MySQL table the Space already stores it in, or `--fresh` for an app that has no Space yet. Add `--users` when the Space has Space Users turned on but the capsule has no `auth` declaration.
73
86
74
87
The command prints a JSON report:
75
88
@@ -82,8 +95,6 @@ The command prints a JSON report:
82
95
83
96
The exit code is `0` for a candidate or a clean dry run, `1` for a refusal, and `2` for bad arguments. Fix every `errors` pointer, then read every `review` entry. A candidate with review entries still compiles, but it may not behave the way your 0.8 app did.
84
97
85
-
Keep the 0.8 source, the candidate, its `zero/migrations/`, and `connector-roles.json` together.
86
-
87
98
## What converts
88
99
89
100
| Zero 0.8 | Current Zero |
@@ -116,10 +127,8 @@ The converter refuses these, with a pointer to each:
116
127
117
128
The converter reads only the server. Your `client/` code uses `@spacefast/zero/client`, which has no counterpart: call the generated client in `zero/client/` from your frontend instead, or move the UI to TSX pages.
118
129
119
-
## Publishing the port
120
-
121
-
A Space's data moves with the app. Publishing a `zero.config.ts` app to a Space that still runs Zero 0.8 is refused with `zero_migration_required`, because a plain publish would leave the posts, users, and sessions behind. The automatic migration is the way across. It copies the data and switches the Space in one operation.
130
+
## Publishing a hand-ported app
122
131
123
-
The candidate belongs to this Space. `--space` binds its tables by name to the tables this Space already stores, so it is not a starting point for a different Space.
132
+
Publish the 0.8 project, not a hand-edited candidate. A Space's data moves with the app: publishing a `zero.config.ts` app to a Space that still runs Zero 0.8 is refused with `zero_migration_required`, because it would leave the posts, users, and sessions behind. Once a publish has migrated the Space, edit and publish the current Zero app as usual.
124
133
125
-
A project with both `"runtime": { "kind": "zero" }` in `sf.jsonc` and a `zero.config.ts` fails to publish with `zero_mixed_generation`. Delete that block from the candidate's `sf.jsonc`if it has one.
134
+
A project with both `"runtime": { "kind": "zero" }` in `sf.jsonc` and a `zero.config.ts` fails to publish with `zero_mixed_generation`. Delete that block if it has one.
0 commit comments