generatesaas 3.30.0 → 3.31.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: landing-animations
|
|
3
|
+
description: Build, change or review the landing page's animated product tour (the hero's tabbed scenes in apps/web/components/landing/hero/, hero-scenes.css) and the feature grid's scroll reveal (bento.css) - CSS-only motion with a resting frame that equals the final frame, 8s stories, a scripted pointer, a phone camera and reduced-motion support. Use when the user asks to add, replace, remove, retime or fix a hero tour scene, make the landing page animated, show their own product in the hero, or when a scene looks wrong on a phone, in dark mode or with reduced motion.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Landing animations
|
|
7
|
+
|
|
8
|
+
The landing hero plays a tabbed tour of the real app: one 1120x630 artboard per scene, scaled to the page in CSS, each scene an 8 second story told by a scripted pointer. Everything moves with CSS keyframes in `apps/web/components/landing/hero/hero-scenes.css`; the only JavaScript is one `setTimeout` in `hero-showcase.tsx` that switches tabs.
|
|
9
|
+
|
|
10
|
+
## Where things live
|
|
11
|
+
|
|
12
|
+
| File | Role |
|
|
13
|
+
| --- | --- |
|
|
14
|
+
| `components/landing/hero/landing-hero.tsx` | Headline, sub-line, CTAs, trust row, then the showcase (server component) |
|
|
15
|
+
| `components/landing/hero/hero-showcase.tsx` | Tab strip, timer, hover pause, reduced-motion handling (client) |
|
|
16
|
+
| `lib/landing/hero-scene-ids.ts` | Scene ids in tour order, and the config flag that gates each one |
|
|
17
|
+
| `lib/landing/hero-scenes.tsx` | Registry: id to scene component, window chrome and address |
|
|
18
|
+
| `components/landing/hero/scenes/<id>-scene.tsx` | One scene's markup, in artboard px |
|
|
19
|
+
| `scenes/scene-app-shell.tsx` | The app's real sidebar and top bar, drawn at 1440x755 and scaled 7/9 |
|
|
20
|
+
| `scenes/scene-frame.tsx`, `mockups/animated/mockup-viewport.tsx` | Window chrome, the 1120x630 artboard and the phone camera wrapper |
|
|
21
|
+
| `scenes/scene-cursor.tsx`, `scenes/scene-step.ts`, `scenes/scene-ui.tsx` | Pointer, stagger helper, shared glyphs and page parts |
|
|
22
|
+
| `lib/landing/hero-scene-world.ts` | Demo names, addresses and amounts (data, not copy) |
|
|
23
|
+
| `components/landing/bento.css` | The feature grid's scroll-driven reveal |
|
|
24
|
+
| `packages/i18n/translations/en/web.json` | `landing.hero.tabs.*`, `landing.hero.tabs_short.*`, `landing.hero.tab_captions.*`, `demo.hero_scenes.<id>.*` |
|
|
25
|
+
|
|
26
|
+
## The stack
|
|
27
|
+
|
|
28
|
+
- CSS only. Never add framer-motion, GSAP, Lottie or any animation library, and never animate per frame from JS (no `requestAnimationFrame`, no ResizeObserver).
|
|
29
|
+
- Scenes are server-rendered DOM - no video, no image, no chart library - so every caption ships in the HTML and the tour is crawlable.
|
|
30
|
+
- `MockupViewport` scales the artboard with `.fm-viewport { container-type: inline-size }` and `.fm-artboard { scale: calc(100cqw / var(--fm-artboard-w)) }`: the first paint is already scaled. Never use `tan(atan2())` for the ratio - WebKit computes it wrong and flips the tour upside down on iPhones.
|
|
31
|
+
|
|
32
|
+
## The CSS contract (header of `hero-scenes.css`)
|
|
33
|
+
|
|
34
|
+
1. **Resting frame = final frame.** Default styles are the finished frame, shown with no JS, under reduced motion and before hydration, and they must equal each story's 100% frame.
|
|
35
|
+
2. **Every `animation-*` declaration lives in the one `@media (prefers-reduced-motion: no-preference)` block.** `@keyframes` stay outside it.
|
|
36
|
+
3. **Longhand only.** A `var()` inside the `animation` shorthand hides the keyframe name from the minifier and the keyframes get dropped as unused.
|
|
37
|
+
4. **At most one `hs-*` animation class per element.** Two would cascade, not merge. Nest a wrapper to combine (the wrapper owns WHEN, the inner `.hs-blink` owns the loop).
|
|
38
|
+
5. **No Tailwind `translate-*` / `scale-*` on an element with transform keyframes.** Tailwind v4 emits the standalone `translate` / `scale` properties, which compose with the animated `transform`.
|
|
39
|
+
6. **Stories run once and hold:** `animation-iteration-count: 1` plus `animation-fill-mode: forwards` (or `both` when a `--hs-step` delay needs its pre-delay frame; never a bare `backwards`). Only `.hs-blink`, `.hs-spin` and `.hs-pulse` are `infinite`.
|
|
40
|
+
|
|
41
|
+
Also: every keyframe states an explicit `100%` frame; no story keyframe ends by restating its 0% frame from 86% on; every scene owns its keyframe families (`hs-<id>-*`) - the only shared one is `hs-scene-enter`; never write `{ ... }` inside a comment in the no-preference block (the stylesheet specs parse it).
|
|
42
|
+
|
|
43
|
+
## Timing
|
|
44
|
+
|
|
45
|
+
| What | Value |
|
|
46
|
+
| --- | --- |
|
|
47
|
+
| Tab length = story length | `intervalMs = 8000`; every story `animation-duration: 8s` |
|
|
48
|
+
| Story curve | `cubic-bezier(0.22, 1, 0.36, 1)` |
|
|
49
|
+
| Typing | `steps(N, end)`, one step per character, animating `width` (with a caret) or `clip-path` |
|
|
50
|
+
| Caret and placeholder cuts | `steps(1, end)` |
|
|
51
|
+
| Ambient ticks | `.hs-blink` 0.8s `steps(1, end)`; `.hs-spin` 1s linear; `.hs-pulse` 2s `cubic-bezier(0.4, 0, 0.6, 1)` |
|
|
52
|
+
| Scene entrance | `hs-scene-enter`: opacity 0 / `translateY(12px)` to in place by 5.5% |
|
|
53
|
+
| Cascades | one keyframe per family, delayed by `--hs-step` via `step(seconds)` from `scene-step.ts` |
|
|
54
|
+
| Percent to time | 1% = 80 ms; 6.25 points = 0.5 s |
|
|
55
|
+
|
|
56
|
+
A changed number never counts up: stack the old and new values in one grid cell (`col-start-1 row-start-1`) and crossfade them. A scroll inside a scene is a `transform`.
|
|
57
|
+
|
|
58
|
+
## One beat at a time
|
|
59
|
+
|
|
60
|
+
One thing moves at a time and the pointer leads it. No two story beats in a scene may start within 6.25 points (0.5 s) of each other, except the pointer with the control it presses, and two halves of one change (`-old`/`-new`, a field and its caret, a container and its part). Resolve rows one by one on `--hs-step`; move summary figures as one later beat. Give each scene one cause and one effect - not two stories in 8 seconds. Land the payoff before 74%, while a phone is still zoomed in.
|
|
61
|
+
|
|
62
|
+
## The pointer
|
|
63
|
+
|
|
64
|
+
- `<SceneCursor className="hs-<id>-cursor" />`, once per scene. It never fades: no `opacity` in its keyframes. Re-declare `.hs-<id>-cursor { opacity: 1; transform: translate(Xpx, Ypx); }` after `.hs-cursor` and before the no-preference block, and make that park equal the keyframes' 100% frame.
|
|
65
|
+
- Enter from off the right edge; every later waypoint keeps the arrow on the artboard (0-1102 x, 0-612 y).
|
|
66
|
+
- A press: pointer `scale(0.9)` on the press frame, ring from `scale(0.6)` at opacity 1 to `scale(1.35)` at opacity 0, the pressed control `scale(0.88)`.
|
|
67
|
+
- Travel: one leg is one gesture - `ease-in` on its first frame, `linear` inside, `ease-out` on the frame that starts its last segment (a one-segment leg takes `ease-in-out`); split any segment longer than about 220px.
|
|
68
|
+
- Park in clear space just right of or below the result the pointer produced - never over text.
|
|
69
|
+
- A scene whose settled screen draws nothing alive can pass `breathing` and bring the ring in with its own `hs-<id>-rest-ring` keyframes (opacity 0 until 89%, 1 from 95%).
|
|
70
|
+
|
|
71
|
+
## The phone camera
|
|
72
|
+
|
|
73
|
+
Under 768px each scene's `.hs-camera.hs-<id>-camera` wrapper zooms on the story's beats. Its keyframes live in a `@media (max-width: 767px)` block nested in the no-preference block, with the resting `scale(1) translate(0px, 0px)` declared in the same width query. Origin is the artboard centre; every translate is a focal offset from it.
|
|
74
|
+
|
|
75
|
+
- Open wide and hold the whole screen for at least 12 points (`0%, 20%`), then ease in over a few stops.
|
|
76
|
+
- Every zoomed frame sits between 18% and 85%; the pull-back is finished before 86% and held to 100%.
|
|
77
|
+
- Peak at least 1.8 somewhere in the story; a table frame stays near 1.35-1.8x so a row keeps its label column.
|
|
78
|
+
- Frame the LABEL column (the name plus its first value), keep the sidebar and every line of text fully in or fully out - never cut mid-word - and show a wide beat (labels at the far edge, a toast across the window) wide.
|
|
79
|
+
- Hold ONE frame for a cause and its effect (a click and the list it changes, a send and the reply), and hold each frame for the whole beat: a pan that lands on a beat shows a phone reader nothing.
|
|
80
|
+
- Measure, do not guess: mark targets with `data-hs-at` and read their boxes in artboard coordinates. The pointer's coordinates start under the window chrome (44px with an address bar, 33px without).
|
|
81
|
+
|
|
82
|
+
## Fidelity to the real app
|
|
83
|
+
|
|
84
|
+
- A scene shows the real screen as it is today. Draw the app shell with `SceneAppShell` (the real sidebar classes, rows from `apps/web/config/sidebar.ts`, labels from the app's own messages, the settings rail from `settingsNavGroups`; `surface="desktop"` for the desktop app's window and side panel) - never a hand-tuned sidebar.
|
|
85
|
+
- Write the page body in the app's own pixels with the real screen's own classes and components (`Card`, `buttonVariants`, `ProviderCard`, ...); the shell lays the 1440x755 window out and scales it 7/9 into the artboard. Dialogs and toasts go in `overlay`, over the whole window. A page longer than the window scrolls with a `hs-<id>-scroll` wrapper transform.
|
|
86
|
+
- Fake data is fine; a fake layout is not. Show only behaviour the app has. Numbers must agree with themselves.
|
|
87
|
+
- Colours come from the theme tokens (`bg-primary`, `text-muted-foreground`, ...). Never hand-pick a colour.
|
|
88
|
+
- Every visible string is a message: tab labels and captions under `landing.hero.*`; the real screen's own keys for everything the real screen prints; `demo.hero_scenes.<id>.*` only for copy the web bundle does not carry (desktop- and mobile-only strings, seeded content). Names, addresses, amounts and file contents are data in `hero-scene-world.ts` or the scene.
|
|
89
|
+
- Gate a scene on the flag of the surface it shows (`SCENE_GATES` in `hero-scene-ids.ts`), so a build that switched AI, payments, organizations, desktop or mobile off never advertises it.
|
|
90
|
+
|
|
91
|
+
## Reduced motion, SSR and layout
|
|
92
|
+
|
|
93
|
+
- Nothing animates outside the no-preference block, so a reduced-motion visitor sees every scene's resting frame. `HeroShowcase` reads the preference with `useSyncExternalStore`: no auto-advance and no countdown bar under reduce.
|
|
94
|
+
- From `lg` the tab strip is one pill. Below `lg` it is a compact grid, flush with no card and without More: `compactTabColumns` picks as few rows as hold five tabs each (ten tabs make 2 x 5, six make 2 x 3), the stylesheet reads it as `--hs-cols` and centres a short last row, and a phone shows each scene's short label (`landing.hero.tabs_short.<id>`). Never let the strip scroll sideways.
|
|
95
|
+
- All panels and captions are in the HTML; inactive ones are `hidden` (which cancels their animations; showing one restarts them from 0%).
|
|
96
|
+
- No layout shift: the viewport reserves `aspect-ratio: 1120 / 630`, scenes are absolutely positioned inside a fixed, `overflow-hidden` artboard, and the headline has no entrance animation.
|
|
97
|
+
|
|
98
|
+
## The feature grid reveal (`bento.css`)
|
|
99
|
+
|
|
100
|
+
The grid's tiles rise in as they enter the viewport with a scroll-driven animation and no JS: `animation-timeline: view()` inside `@supports (animation-timeline: view())` inside the reduced-motion gate, the range staggered with `--bento-lag` (a view timeline ignores `animation-delay`), the same story curve, resting on the finished frame, and no colour written.
|
|
101
|
+
|
|
102
|
+
## Add or replace a scene
|
|
103
|
+
|
|
104
|
+
1. Pick the screen and the ONE story: what the pointer does, what changes, where it ends. Screenshot the real screen first.
|
|
105
|
+
2. Add the id to `HERO_SCENE_IDS` (tour order) and its flag to `SCENE_GATES` in `lib/landing/hero-scene-ids.ts`; add the tab label, its short phone label and the caption under `landing.hero.tabs.<id>`, `landing.hero.tabs_short.<id>` and `landing.hero.tab_captions.<id>` in `en/web.json`.
|
|
106
|
+
3. Create `components/landing/hero/scenes/<id>-scene.tsx`: a root `<div className="hs-<id>-enter absolute inset-0">`, the page inside `SceneAppShell` (or the scene's own native surface), the real screen's keys plus `demo.hero_scenes.<id>` for the rest, and one `<SceneCursor className="hs-<id>-cursor" />`.
|
|
107
|
+
4. Register it in `SCENES` in `lib/landing/hero-scenes.tsx` with its chrome and address (built from `config.domain` and `config.routes`).
|
|
108
|
+
5. In `hero-scenes.css`: a commented section with the resting frame (final frame) and the cursor park; the rules inside the no-preference block (`.hs-<id>-enter` runs `hs-scene-enter`); the camera rule inside its width query; the `@keyframes hs-<id>-*` below.
|
|
109
|
+
6. To replace a demo scene, delete its scene file, its CSS section, its keys and its id from `CHOREOGRAPHED_BEFORE_RULE` in the loop stylesheet spec.
|
|
110
|
+
7. Run `pnpm --filter web test tests/components/landing` and do the QA pass below.
|
|
111
|
+
|
|
112
|
+
## QA checklist
|
|
113
|
+
|
|
114
|
+
- Each scene's settled frame at 1280px, light and dark: the pointer parked off text, nothing half-faded, the final state readable.
|
|
115
|
+
- At 390px, frames at 25%, 40%, 55% and 70% of each scene (pause the panel's animations and set their `currentTime` to `pct * 80` ms): every frame shows what changes AND what it belongs to.
|
|
116
|
+
- Reduced motion: every scene still reads as the finished product shot.
|
|
117
|
+
- Hover the frame: the scene and the countdown freeze together.
|
|
118
|
+
- No layout shift as the hero loads.
|
|
119
|
+
|
|
120
|
+
## Tests to keep
|
|
121
|
+
|
|
122
|
+
| Spec | Pins |
|
|
123
|
+
| --- | --- |
|
|
124
|
+
| `tests/components/landing/hero-scenes-loop-stylesheet.test.ts` | 8s stories run once and hold, typing on steps, only ambient loops, explicit 100% frames, rest equals end, no rewind, camera rules, one beat at a time, own keyframe families |
|
|
125
|
+
| `tests/components/landing/hero-scenes-cursor-stylesheet.test.ts` | Pointer park equals its last waypoint, no fade, every waypoint on the artboard |
|
|
126
|
+
| `tests/components/landing/hero-scenes.test.tsx` | Registry order, per-flag gates, artboard and camera, one pointer, one animation class per element, own families, no raw message keys |
|
|
127
|
+
| `tests/components/landing/hero-showcase.test.tsx` | Panels, auto-advance, visible-time counting, frame-only pause, reduced motion, countdown, keyboard |
|
|
128
|
+
| `e2e/landing-motion.spec.ts` | Real-browser motion contract: hs-* only, stories once, freeze on hover, nothing under reduced motion |
|
|
129
|
+
|
|
130
|
+
The two stylesheet specs read the CSS file from disk - the one place the animation facts exist - and are listed as cross-artifact checks in `packages/e2e-support/src/test-contract-debt.ts`.
|
|
131
|
+
|
|
132
|
+
## Mistakes to avoid
|
|
133
|
+
|
|
134
|
+
| Mistake | Fix |
|
|
135
|
+
| --- | --- |
|
|
136
|
+
| Keyframes looping with a wind-down, so a late tab switch replays the opening | Stories run once and hold their 100% frame |
|
|
137
|
+
| A keyframe list with no 100% frame - the scene slides back to its resting look | State the 100% frame outright |
|
|
138
|
+
| Resting style differs from the 100% frame - reduced motion sees another ending | Rest equals end, every property |
|
|
139
|
+
| `animation` shorthand with `var()` - keyframes tree-shaken | Longhand properties |
|
|
140
|
+
| Tailwind `translate-*` on an animated element - transforms compose | Position with a wrapper |
|
|
141
|
+
| Camera zoomed at 0.4 s - phones never see the whole screen | Hold wide through 20% |
|
|
142
|
+
| Camera centred on numbers - phones see "27,100 · 41" with no label | Frame the label column, cap tables near 1.8x |
|
|
143
|
+
| Zoomed frame cutting sidebar words | Sidebar fully in or fully out |
|
|
144
|
+
| Pointer parked over text | Park in clear space right of or below the result |
|
|
145
|
+
| Two things moving at once, or two stories in one scene | One beat at a time, one cause and effect |
|
|
146
|
+
| A hand-tuned sidebar drifting from the real app | `SceneAppShell` with the app's own classes |
|
|
147
|
+
| Payoff landing during the pull-back | Land it before 74% |
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: og-image
|
|
3
|
+
description: Redraw the site's social share card (apps/web/public/og.png, the Open Graph / Twitter image every shared link shows) from the product itself - the landing page's hero panel captured in dark mode, framed under the logo and site name in the theme's own colours - and keep the generated per-page cards (og-card.tsx) in the same colours. Use when the user asks to redo, update, refresh or rebrand the OG image, share card, social preview or link preview, or after the logo, the brand colours in tooling/styles/theme.css, the site name, or the landing hero / dashboard demo changed.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# OG image
|
|
7
|
+
|
|
8
|
+
The static card at `apps/web/public/og.png` is what every shared link to the site shows. It should be **the product**, not a template box: the theme's dark ground with a soft primary glow off the top edge, the square logo beside the site name, and the landing page's own hero panel in a framed window that bleeds off the bottom edge. `pnpm og-image` builds it from the project's own files and the running site, so nothing in it is invented or eyeballed.
|
|
9
|
+
|
|
10
|
+
## When to run it
|
|
11
|
+
|
|
12
|
+
- The logo (`config.logo.square`), the site name (`config.siteName`) or the brand colours (`tooling/styles/theme.css`) changed.
|
|
13
|
+
- The landing hero changed - a new hero visual, a dashboard tour, new demo data.
|
|
14
|
+
- The project still carries the boilerplate's card.
|
|
15
|
+
|
|
16
|
+
If the landing demo is out of date with the real app, fix the demo first: the card advertises it.
|
|
17
|
+
|
|
18
|
+
## What it reads
|
|
19
|
+
|
|
20
|
+
| Input | Source | Override |
|
|
21
|
+
| --- | --- | --- |
|
|
22
|
+
| Colours | `--background`, `--foreground`, `--primary`, `--muted-foreground` from the `.dark` block of `tooling/styles/theme.css` (falling back to `:root`), verbatim | Change the theme, never the script |
|
|
23
|
+
| Site name | `config.siteName` from `@repo/config` | - |
|
|
24
|
+
| Logo | `config.logo.square` under `apps/web/public/` - an SVG is inlined so it scales crisply, a raster file is embedded | - |
|
|
25
|
+
| Display font | The first font file in `apps/web/assets/fonts/` (weight 600) | `--font <path> --font-weight <n>` |
|
|
26
|
+
| Panel | The landing page's `#hero` element | `--selector "<css>"` |
|
|
27
|
+
| Page | `http://localhost:3000` | `--url <url>` (local dev or production) |
|
|
28
|
+
|
|
29
|
+
## Steps
|
|
30
|
+
|
|
31
|
+
1. **Run the web app** (`pnpm dev`, or point `--url` at the deployed site). The landing page must render; no sign-in is involved.
|
|
32
|
+
2. **Pick the panel.** The default `#hero` captures the landing hero. If the landing has a product panel of its own - a dashboard tour scene, a framed app screenshot with demo data - capture that instead: find its element id in `apps/web/components/landing/` and pass `--selector "#<id>"`. A panel that carries its own window chrome wants `--fit box --margin 0`. Never capture a signed-in page or stage data for the shot: the card shows what the public landing shows.
|
|
33
|
+
3. **Generate:** `pnpm og-image` (add the flags from step 2). It opens the page in headless Chromium at 1440x1000, 2x, dark colour scheme; waits for `load` plus `--wait` ms (default 5000) so tours and entrance animations settle; **removes** - never clicks - the cookie/consent banner, chat widgets and the Next dev badge (`--remove "<css>"` adds more); settles every animation; and screenshots the panel. It then composes the 1200x630 card, renders it at 1x, checks the size and writes `apps/web/public/og.png`.
|
|
34
|
+
4. **Keep the per-page cards in step.** The same run resolves the four tokens to sRGB hex through a canvas (Satori, which draws `apps/web/components/seo/og-card.tsx`, cannot parse `oklch()`) and rewrites the `BRAND` constant there; the site name on those cards is drawn in the primary colour. `--no-og-card` skips this.
|
|
35
|
+
5. **Look at the result.** Open `apps/web/public/og.png` and judge it: the logo and name sharp and centred, the panel readable, no banner, cursor, dev badge or half-finished animation in the frame, dark mode throughout. Re-run with a different `--selector`, `--wait`, `--fit` or `--margin` until it is right. The script prints the file's size and byte count; the card must be exactly 1200x630, which the layout's `og:image` tags declare.
|
|
36
|
+
6. **Ship it.** Commit `og.png` and `og-card.tsx` together. If anything references the image with a cache key (`/og.png?v=N`), bump it. Social sites cache OG images for days: after deploying, force a refresh with the Facebook Sharing Debugger, LinkedIn Post Inspector and the X card validator.
|
|
37
|
+
|
|
38
|
+
## Flags
|
|
39
|
+
|
|
40
|
+
| Flag | Default | Use |
|
|
41
|
+
| --- | --- | --- |
|
|
42
|
+
| `--url` | `http://localhost:3000` | The landing page to capture |
|
|
43
|
+
| `--selector` | `#hero` | The panel element |
|
|
44
|
+
| `--fit` | `content` | `content` keeps only the part of the element that paints (drops empty bands of a vertically centred hero); `box` takes the element's whole box |
|
|
45
|
+
| `--margin` | `40` | Pixels of page kept around the panel |
|
|
46
|
+
| `--wait` | `5000` | Milliseconds after `load` before the capture |
|
|
47
|
+
| `--remove` | consent, chat, dev badge | One more selector to remove before the capture (repeatable) |
|
|
48
|
+
| `--font`, `--font-weight` | first file in `apps/web/assets/fonts`, `600` | The display font for the site name |
|
|
49
|
+
| `--out` | `apps/web/public/og.png` | Where the card is written |
|
|
50
|
+
| `--no-og-card` | - | Leave `og-card.tsx` untouched |
|
|
51
|
+
|
|
52
|
+
## Rules
|
|
53
|
+
|
|
54
|
+
- Colours come from `tooling/styles/theme.css` only. To change how the card looks, change the theme - never hand-pick a colour in the script, the card or `og-card.tsx`.
|
|
55
|
+
- Never click the consent banner: a screenshot must not imply a choice. The script removes it from the DOM.
|
|
56
|
+
- Do not wait for `networkidle` - pages that poll never settle; the script uses `load` plus a fixed wait.
|
|
57
|
+
- A Chromium is needed: if Playwright reports a missing browser, run `pnpm --filter web exec playwright install chromium`.
|
|
@@ -525,7 +525,7 @@ Config files are the most commonly customized.
|
|
|
525
525
|
|
|
526
526
|
1. Merge the upstream schema change into `packages/database/src/db/*.ts` (user review first, as above).
|
|
527
527
|
2. Run `pnpm --filter @repo/database generate`. Drizzle diffs the project's own latest snapshot against the merged schema and writes a fresh migration carrying a current timestamp, the next `idx`, a correct `prevId`, and a snapshot that describes the project's real schema.
|
|
528
|
-
3. Open the upstream `.sql` under `.generatesaas/staging/packages/database/drizzle/` and
|
|
528
|
+
3. Open the upstream `.sql` under `.generatesaas/staging/packages/database/drizzle/` and carry over any hand-written statements - seeds, backfills, data copies, `ON CONFLICT` guards - which `generate` cannot infer. Put them in a migration of their own, never in the generated file: run `pnpm --filter @repo/database generate --custom --name <what-it-does>`, which writes an empty `.sql` with its own journal entry after the generated one, and paste them there. The generated file then stays pure `generate` output that the next diff can trust. Only a statement that must run in the middle of the structure change - a backfill before the `NOT NULL` it satisfies - stays inside the generated file, at that point.
|
|
529
529
|
4. Run `pnpm --filter @repo/database migrate`.
|
|
530
530
|
|
|
531
531
|
**Why the upstream file cannot just be added.** Drizzle applies a migration only when its journal `when` value is greater than the `created_at` of the last migration already applied to the database. A project that generated its own migration after the upstream one was authored sits above that mark, so a copied-in upstream file is **skipped silently and permanently**: no error, no warning, no log line, and `migrate` still exits 0. The table or column it was supposed to create never exists, and the miss surfaces later as runtime failures on whatever code path needs it. Taking the upstream `_journal.json` and snapshots instead of the project's own is the second half of the same trap: the final snapshot then knows nothing about the project's own tables, so the next `generate` re-emits `CREATE TABLE` for tables that already exist.
|