create-grist-widget 0.3.4 → 0.3.5
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.
- package/package.json +1 -1
- package/template/AGENTS.md +90 -0
- package/template/CLAUDE.md +1 -0
package/package.json
CHANGED
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
# Agent guide — start here
|
|
2
|
+
|
|
3
|
+
> Audience: an agent working inside a widget repo scaffolded from
|
|
4
|
+
> `create-grist-widget` (this file travels with the scaffold), or working on
|
|
5
|
+
> this template's own source under
|
|
6
|
+
> `templates/grist-widget-template-vite/` inside the `grist-widget-sdk`
|
|
7
|
+
> monorepo. This repo is a **distribution artifact** — `main` is force-pushed
|
|
8
|
+
> from a fresh scaffold on every release, not developed on directly upstream.
|
|
9
|
+
> If you're in the monorepo working on the SDK itself, read the root
|
|
10
|
+
> `AGENTS.md` instead.
|
|
11
|
+
|
|
12
|
+
## The widget contract
|
|
13
|
+
|
|
14
|
+
`src/App.tsx` is the whole widget — one file, three exports:
|
|
15
|
+
|
|
16
|
+
```tsx
|
|
17
|
+
export const GRIST_OPTIONS: UseGristOptions = { requiredAccess: "read table" }
|
|
18
|
+
export const WIDGET_METADATA = { title: "...", description: "..." } as const
|
|
19
|
+
export function App() {
|
|
20
|
+
const w = useGrist()
|
|
21
|
+
// ...
|
|
22
|
+
}
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
`src/main.tsx` wires it into Grist: `GristWidgetProvider` (reads `GRIST_OPTIONS`) →
|
|
26
|
+
`GristBoundary` → `GristSdkAlerts` → `<App />`. Access level, column mapping, and
|
|
27
|
+
rendering all live in `src/App.tsx` — that's the one file to edit.
|
|
28
|
+
|
|
29
|
+
## Operating contract
|
|
30
|
+
|
|
31
|
+
1. **Widgets use the SDK.** No direct `window.grist.*` calls — use `useGrist()` and the
|
|
32
|
+
other `grist-widget-sdk` hooks.
|
|
33
|
+
2. **`pnpm dev` shows the showcase hub today, not a seeded preview.** Opened outside Grist
|
|
34
|
+
it renders `TemplateLanding` (onboarding + links to released versions); the widget
|
|
35
|
+
itself only renders once actually embedded in a Grist document. An offline, seeded
|
|
36
|
+
`pnpm dev` loop is planned but not shipped in this template yet — don't describe one as
|
|
37
|
+
if it exists.
|
|
38
|
+
3. **No test command yet.** `package.json` has no `test` script in this template today —
|
|
39
|
+
don't invent one or assume `pnpm test` works here.
|
|
40
|
+
4. **Always develop on `dev`, release by merging to `main`.** Commit and push to `dev` for
|
|
41
|
+
every change — it auto-deploys a live preview at `.../dev/` that self-reloads inside an
|
|
42
|
+
open Grist document a few seconds later. Bump `package.json`'s `version` *before*
|
|
43
|
+
opening the `dev` → `main` PR: merging without a version bump publishes nothing (the
|
|
44
|
+
release build silently no-ops whenever that version's directory already exists — the PR
|
|
45
|
+
merges cleanly and CI reports success either way).
|
|
46
|
+
|
|
47
|
+
## Commands
|
|
48
|
+
|
|
49
|
+
| Intent | Command |
|
|
50
|
+
| --- | --- |
|
|
51
|
+
| Install | `pnpm install` |
|
|
52
|
+
| Dev server (showcase hub outside Grist) | `pnpm dev` |
|
|
53
|
+
| Build | `pnpm build` |
|
|
54
|
+
| Lint | `pnpm lint` |
|
|
55
|
+
| Format | `pnpm format` |
|
|
56
|
+
| Type-check | `pnpm typecheck` |
|
|
57
|
+
| Preview a production build | `pnpm preview` |
|
|
58
|
+
|
|
59
|
+
## Path map
|
|
60
|
+
|
|
61
|
+
| Concept | Path |
|
|
62
|
+
| --- | --- |
|
|
63
|
+
| The widget | `src/App.tsx` |
|
|
64
|
+
| Grist wiring / embed vs. showcase detection | `src/main.tsx` |
|
|
65
|
+
| ui primitives | `src/components/ui/` |
|
|
66
|
+
| Deploy workflow | `.github/workflows/deploy.yml` |
|
|
67
|
+
| Deploy script (version guard, channel logic) | `scripts/deploy.mjs` |
|
|
68
|
+
| Full walkthrough (dev loop, deploying, embedding) | `README.md` |
|
|
69
|
+
| Changelog | `CHANGELOG.md` |
|
|
70
|
+
|
|
71
|
+
## One-time repo settings
|
|
72
|
+
|
|
73
|
+
Only needed once, after the first push triggers the deploy workflow's first run (it
|
|
74
|
+
creates a `gh-pages` branch — these settings can't be applied before that exists):
|
|
75
|
+
|
|
76
|
+
1. Settings → Pages → Source → **Deploy from a branch** → branch `gh-pages`, folder
|
|
77
|
+
`/ (root)`. Not `main` — pointing Pages at `main` serves this repo's raw, unbuilt source
|
|
78
|
+
instead of the built site (symptom: a blank page with a `/src/main.tsx` 404).
|
|
79
|
+
2. If that first workflow run fails with a permissions error pushing to `gh-pages`:
|
|
80
|
+
Settings → Actions → General → Workflow permissions → **Read and write permissions**.
|
|
81
|
+
Most repos don't need this; it depends on account/org defaults.
|
|
82
|
+
|
|
83
|
+
Full detail, including the two live URLs (`/latest/` and `/v<version>/`): `README.md`.
|
|
84
|
+
|
|
85
|
+
## Anti-patterns
|
|
86
|
+
|
|
87
|
+
- Calling `window.grist.*` inside widget code instead of the SDK's hooks
|
|
88
|
+
- Describing a `pnpm test` command or a seeded offline `pnpm dev` preview — neither exists
|
|
89
|
+
in this template yet
|
|
90
|
+
- Merging `dev` into `main` without bumping `package.json`'s `version` first
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
@AGENTS.md
|