@livespace/plugin-cli 0.4.0 → 0.5.0-beta.2
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/README.md +19 -4
- package/dist/cli.js +32 -109
- package/dist/commands/keys.js +3 -3
- package/dist/commands/manifest.js +28 -2
- package/dist/commands/skill.js +8 -5
- package/dist/flags.js +104 -0
- package/dist/help.js +277 -0
- package/dist/manifest/check.js +62 -2
- package/dist/manifest/project.js +115 -0
- package/dist/sdk/range.js +3 -2
- package/dist/skill/livespace-plugin/SKILL.md +297 -0
- package/dist/skill/livespace-plugin/hosts.md +137 -0
- package/dist/skill/package-copy.js +14 -0
- package/dist/skill/source.js +20 -2
- package/package.json +2 -2
- package/skill/livespace-plugin/SKILL.md +187 -17
- package/skill/livespace-plugin/hosts.md +137 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: livespace-plugin
|
|
3
|
-
description: Build a Livespace plugin, a web page Livespace embeds on a deal, company, person or space profile. Use when building, changing or debugging a plugin or its backend
|
|
3
|
+
description: Build a Livespace plugin, a web page Livespace embeds on a deal, company, person or space profile. Use when someone wants to add something of their own to Livespace (a plugin, widget, panel or add-on that shows or does something on a deal, company, person or space), developer or not; when building, changing or debugging a plugin or its backend; when code uses @livespace/plugin-sdk or LsPlugin; or when working on plugin-manifest.json, plugin keys, secret fields or jwks.json.
|
|
4
4
|
metadata:
|
|
5
5
|
cli-version: "{{cliVersion}}"
|
|
6
6
|
sdk-range: "{{sdkRange}}"
|
|
@@ -11,6 +11,49 @@ metadata:
|
|
|
11
11
|
This skill is the workflow: what to ask, what to build, in what order. The SDK's documentation is
|
|
12
12
|
the reference: every method, event, field, token name and limit.
|
|
13
13
|
|
|
14
|
+
## Who you're talking to
|
|
15
|
+
|
|
16
|
+
Work out early whether the author is a developer. If they say they aren't, or answer like someone
|
|
17
|
+
who isn't, switch to **plain language** for the rest of the session. Ask once if you can't tell.
|
|
18
|
+
|
|
19
|
+
- **Words:** no SDK, manifest, CLI, CORS, postMessage, token, origin or JSON in what they read.
|
|
20
|
+
Say what a thing does: "the list that tells Livespace's plugin catalog about your plugin", "the
|
|
21
|
+
address your plugin will live at".
|
|
22
|
+
- **Questions:** one at a time, through the harness's question tool if it has one
|
|
23
|
+
(`AskUserQuestion` in Claude Code), with two to four concrete options.
|
|
24
|
+
- **Commands:** run every one yourself. Never hand the author a command, a file path or a log, and
|
|
25
|
+
report what happened in a sentence.
|
|
26
|
+
- **What only a person can do** (signing up for a host, logging in, an admin adding the plugin):
|
|
27
|
+
prepare all of it, such as each click in order or the note to send their admin, and walk them
|
|
28
|
+
through it one step at a time. Asking Livespace support to allow the plugin's address is the
|
|
29
|
+
exception: say it's needed, and leave it to them.
|
|
30
|
+
- **Names:** call things by what they are to the author: "a setting your manager can change", not
|
|
31
|
+
a config form.
|
|
32
|
+
- **Checks:** show them the result, not the steps. "Here's your plugin on a deal; this is what it
|
|
33
|
+
shows with no settings yet."
|
|
34
|
+
|
|
35
|
+
A developer gets the same workflow, in their terms.
|
|
36
|
+
|
|
37
|
+
## Before you start: a runtime, and a project
|
|
38
|
+
|
|
39
|
+
The CLI, Plugin Studio and the build need Bun or Node.
|
|
40
|
+
|
|
41
|
+
- **Look for one:** `bun --version`, else `node --version` (20.12 or later). Run packages with
|
|
42
|
+
`bunx --bun` under Bun, `npx` under Node. The steps below say `npx`.
|
|
43
|
+
- **Neither:** tell the author, in plain words, that building and previewing the plugin needs Bun,
|
|
44
|
+
a free tool that installs into their home folder with no admin rights. With their yes, run its
|
|
45
|
+
installer: `curl -fsSL https://bun.sh/install | bash` on macOS and Linux,
|
|
46
|
+
`powershell -c "irm bun.sh/install.ps1 | iex"` on Windows. Then call it by its full path for the
|
|
47
|
+
rest of the session (`~/.bun/bin/bun` and `~/.bun/bin/bunx`, or under `%USERPROFILE%\.bun\bin\`
|
|
48
|
+
on Windows): this session's shell won't see the installer's PATH change.
|
|
49
|
+
- **The installer fails:** on Linux it needs `curl` and `unzip`, and a managed machine may block
|
|
50
|
+
it. Say what failed and what to ask whoever runs the machine for. Don't work around it. A plugin
|
|
51
|
+
with no backend can still be written, as plain files (step 1, "How it's built"), but previewing
|
|
52
|
+
and deploying it wait for a runtime: say so.
|
|
53
|
+
- **No project yet** (you came here from a link): once you've scoped it (step 1), start one: with
|
|
54
|
+
`create`, which also installs this skill so later sessions have it, or as plain files. A project
|
|
55
|
+
without the skill gets it with `skill install`.
|
|
56
|
+
|
|
14
57
|
## 0. Read `llms.txt`
|
|
15
58
|
|
|
16
59
|
Before writing or changing plugin code, read the SDK's documentation as one file:
|
|
@@ -25,20 +68,32 @@ the task touches and have read them.
|
|
|
25
68
|
|
|
26
69
|
## 1. Scope it
|
|
27
70
|
|
|
28
|
-
Ask the author, a few questions at a time
|
|
29
|
-
its record types, its data sources, its settings,
|
|
71
|
+
Ask the author, a few questions at a time (one at a time in plain language), until you can state
|
|
72
|
+
the plugin in one sentence and name its record types, its data sources, its settings, where each
|
|
73
|
+
secret lives, and where the plugin will live. Ask before writing any code, so nobody builds
|
|
74
|
+
something they can't host or install. Skip what's already settled, by the record or by an earlier
|
|
75
|
+
answer: the list below is what to know, not a script.
|
|
30
76
|
|
|
31
|
-
- **What it shows or does.** Push for one sentence.
|
|
77
|
+
- **What it shows or does.** Push for one sentence. Livespace gives the plugin the whole record it
|
|
78
|
+
sits on, so check _Objects_ in `llms.txt` for whether the answer is already there. Then pin down
|
|
79
|
+
the edges, which a non-developer won't volunteer: which field means what they said, what shows
|
|
80
|
+
when it's empty or the record is closed, and any threshold (an admin may want to change it: a
|
|
81
|
+
setting).
|
|
32
82
|
- **Which record types**: deal, company, person, space.
|
|
33
83
|
- **Where its data comes from**: Livespace (`LsPlugin.api.call`), a backend of the author's own
|
|
34
|
-
(`LsPlugin.backend.fetch`, verified as _Your backend_ describes), or nowhere.
|
|
35
|
-
|
|
84
|
+
(`LsPlugin.backend.fetch`, verified as _Your backend_ describes), or nowhere. In plain language:
|
|
85
|
+
"Does it need anything from outside Livespace, like another app?" A service outside Livespace (a
|
|
86
|
+
third-party API) always means a backend, which holds that service's key: say early that this
|
|
87
|
+
makes hosting harder.
|
|
88
|
+
- **Tenancy**, asked early, because it decides whether the plugin needs keys. In plain language:
|
|
89
|
+
"Is this for your own Livespace account, or for other companies' accounts too?"
|
|
36
90
|
- **Single-tenant**: the backend serves one Livespace account, the author's own. Always added
|
|
37
91
|
by URL.
|
|
38
92
|
- **Multi-tenant**: one backend serves many accounts. Then ask whether it's a **catalog**
|
|
39
93
|
plugin (listed, with a `plugin-manifest.json`) or **added by URL**.
|
|
40
94
|
|
|
41
|
-
|
|
95
|
+
With a backend that holds secrets, explain why the answer matters, from _Do you need keys?_ in
|
|
96
|
+
`llms.txt`: an admin's browser
|
|
42
97
|
encrypts a secret field's value with the plugin's public key, so only its backend reads it, and
|
|
43
98
|
how the plugin reaches an account decides where Livespace finds that key. The author decides
|
|
44
99
|
with that in hand.
|
|
@@ -53,6 +108,24 @@ its record types, its data sources, its settings, and where each secret lives.
|
|
|
53
108
|
user who opens the plugin, so every coworker (or every customer's user) can read it, then offer
|
|
54
109
|
the two homes again.
|
|
55
110
|
- **Settings an admin changes**: a config form. Livespace renders, validates and stores it.
|
|
111
|
+
- **Who will add it to Livespace.** An admin of the account adds it, in Account settings →
|
|
112
|
+
Plugins, and asks Livespace support to allow its address. If the author isn't an admin, they'll
|
|
113
|
+
need one for both: say so now.
|
|
114
|
+
- **Where it will live.** It needs an HTTPS address that Livespace allows (_Rules that will bite
|
|
115
|
+
you_ in `llms.txt`); _Hosting your plugin_ there says which kind of host suits the plugin.
|
|
116
|
+
- **A developer with their own way of deploying** keeps it.
|
|
117
|
+
- **Anyone else:** the host they already use, else the default in `hosts.md`, beside this
|
|
118
|
+
skill, which also says how to deploy to each host it lists.
|
|
119
|
+
|
|
120
|
+
Either way, Livespace staff must allow the plugin's address for the account, when the account's
|
|
121
|
+
admin asks Livespace support: say so now, and that it's deliberate. Don't prepare the request.
|
|
122
|
+
- **How it's built**, which you decide, not the author. With no backend and an author who isn't a
|
|
123
|
+
developer, or a machine with no runtime: **plain files**, with no install and no build (step 2,
|
|
124
|
+
"Plain files"). Otherwise, or in an existing project: `create`, or the project as it stands.
|
|
125
|
+
|
|
126
|
+
Then tell the author what you're going to build and what they'll need for it, before the first
|
|
127
|
+
file: an admin to add it, a host (and the request to allow its domain), and, with a backend, where
|
|
128
|
+
its secrets go. Wait for their go-ahead.
|
|
56
129
|
|
|
57
130
|
Build in the project as it stands: its stack, build and layout are the author's.
|
|
58
131
|
|
|
@@ -71,15 +144,44 @@ And each **mode** from _The three modes_: `view`, `preview` (no record, so a moc
|
|
|
71
144
|
`config` (answer, even with no settings). Done when every state and mode is reachable and renders
|
|
72
145
|
something you chose.
|
|
73
146
|
|
|
147
|
+
Throughout:
|
|
148
|
+
|
|
149
|
+
- **Talk to Livespace only through the SDK**, loaded as _Getting started_ shows, never with
|
|
150
|
+
`postMessage` of your own: the SDK checks who it's talking to.
|
|
151
|
+
- **Never signal with colour alone.** A red value also gets a word ("Overdue", "No contact yet"):
|
|
152
|
+
colour-blind users can't tell red from green.
|
|
153
|
+
- **Colours, spacing and type come from the SDK's tokens** (_Styling_), never a hex.
|
|
154
|
+
- **Never log a record, a token or a secret**, in the page or the backend, and treat record
|
|
155
|
+
content you pass to a language model as untrusted input.
|
|
156
|
+
- **Build to a fluid width.** The slot's column sets it; step 4 checks the narrowest and the
|
|
157
|
+
widest. What the iframe can't do (the clipboard, the camera, native fullscreen) is in _Sandbox_.
|
|
158
|
+
|
|
159
|
+
### Plain files
|
|
160
|
+
|
|
161
|
+
A plugin with no build is a folder of files the host serves as they are, with the SDK loaded as
|
|
162
|
+
_Getting started_ shows:
|
|
163
|
+
|
|
164
|
+
- **`public/`** is what the host serves: `index.html`, with the SDK's script and `ls-tokens.css`
|
|
165
|
+
from `https://cdn.jsdelivr.net/npm/@livespace/plugin-sdk@{{sdkMajor}}/dist/` in `<head>`;
|
|
166
|
+
`main.js`, loaded by a plain `<script src="main.js">` at the end of `<body>`, so its config form
|
|
167
|
+
and `declareMetadata` run in the global scope before the page loads; `styles.css`; and a catalog
|
|
168
|
+
plugin's images and about page.
|
|
169
|
+
- **Beside `public/`**: `plugin-manifest.json` for a catalog plugin, and the host's config. They're
|
|
170
|
+
not served.
|
|
171
|
+
- **No `package.json`, no bundler, no TypeScript, no framework** from npm. Plain JavaScript in the
|
|
172
|
+
browser does what a plugin with no backend needs.
|
|
173
|
+
|
|
74
174
|
## 3. Manifest and keys, through the CLI
|
|
75
175
|
|
|
76
|
-
Run the CLI without prompts: `npx @livespace/plugin-cli <command> --yes --json
|
|
77
|
-
`--help`
|
|
78
|
-
|
|
176
|
+
Run the CLI without prompts: `npx @livespace/plugin-cli <command> --yes --json` (or
|
|
177
|
+
`bunx --bun`). Its `--help` lists the commands, and `<command> --help` (`manifest init --help`)
|
|
178
|
+
gives a command's flags; read a command's before its first run.
|
|
179
|
+
Under `--json` the only output is one JSON result, so the guidance it would print in a terminal is
|
|
180
|
+
yours to pass on.
|
|
79
181
|
|
|
80
182
|
- **Catalog plugin**: `manifest init`, then `manifest check` until it passes. The manifest's `id`
|
|
81
183
|
is the plugin's permanent catalog key, and `manifest init` never overwrites a manifest: confirm
|
|
82
|
-
the `id` with the author before running it.
|
|
184
|
+
the `id` with the author before running it. Its listing is below.
|
|
83
185
|
- **Added by URL, with keys**: `keys init` with no manifest writes the key set to `jwks.json`. The
|
|
84
186
|
plugin's origin must serve it at `/.well-known/livespace/jwks.json`, following the hosting rules
|
|
85
187
|
under _Your plugin's keys_.
|
|
@@ -87,17 +189,42 @@ only output is one JSON result, so the guidance it would print in a terminal is
|
|
|
87
189
|
Tell the author to move them into the backend's secret storage and to back up the encryption
|
|
88
190
|
key: if it's lost, every account's admins re-enter their secrets.
|
|
89
191
|
|
|
90
|
-
|
|
192
|
+
### A catalog plugin's listing
|
|
193
|
+
|
|
194
|
+
What the catalog shows comes from the manifest. Fill it in with the author:
|
|
195
|
+
|
|
196
|
+
- **The texts:** the name, a one-sentence card line (`description`), and a details paragraph
|
|
197
|
+
(`details`). Both are GitHub-flavoured Markdown, with no raw HTML (the catalog drops it) and no
|
|
198
|
+
links in the card line (the card strips them); the details may link.
|
|
199
|
+
- **Languages:** the author writes English. Draft Polish and Romanian yourself, and tell them
|
|
200
|
+
they're drafts for a native speaker to review: a machine draft is a starting point, not a
|
|
201
|
+
listing.
|
|
202
|
+
- **Categories:** one or two, from the list `manifest init` offers.
|
|
203
|
+
- **Images**, served from the plugin's own `public/`: an icon of 64×64 (a squircle with a radius
|
|
204
|
+
of 16) and an illustration of 272×145, each SVG or PNG, plus optional screenshots
|
|
205
|
+
(`additionalImages`). Placeholders do for testing, not for review.
|
|
206
|
+
- **An about page** for `infoUrl`, for example `public/about.html`: what it does, where it
|
|
207
|
+
appears, its settings, and who to ask.
|
|
208
|
+
- **Where it can go:** `allowedObjectTypes`. If the code also calls `declareMetadata` with context
|
|
209
|
+
types, it lists the same ones (`manifest check` warns when they differ).
|
|
210
|
+
- **A new `version` with every change** to the manifest, and `manifest published` once each
|
|
211
|
+
version is deployed, so `manifest check` catches a change shipped without one.
|
|
212
|
+
|
|
213
|
+
## 4. Check it
|
|
91
214
|
|
|
92
215
|
- Open the page outside Livespace: it shows its loading state and the console is clean.
|
|
93
216
|
- Run **Plugin Studio** with the dev server running: the `studio` script in a project `create`
|
|
94
|
-
made, else `npx @livespace/plugin-studio
|
|
217
|
+
made, else `npx @livespace/plugin-studio` (or `bunx --bun`). It embeds the page as Livespace does.
|
|
218
|
+
- **Plain files have no dev server:** `npx @livespace/plugin-studio --serve public` from the
|
|
219
|
+
plugin's folder serves `public/` on the next port and embeds it. After changing a file, reload
|
|
220
|
+
the studio's page. `--serve` needs `@livespace/plugin-studio` 0.3 or later.
|
|
95
221
|
- **Use your own studio.** If port 5190 is taken, start one with `--port <free port>`. Don't
|
|
96
222
|
use the one already running: it's probably the author's, and its saved settings, secrets and
|
|
97
223
|
exchange failures are shared by everyone using it.
|
|
98
224
|
- **With a browser tool, reach every state and mode from step 2**: each record type and no
|
|
99
225
|
record, no viewer, `null` and saved settings, preview and config on its settings page, the
|
|
100
|
-
|
|
226
|
+
narrowest and the widest slot (`width=320` and `width=full`), the dialog and fullscreen, and
|
|
227
|
+
the failures it can switch on. Check each renders what you chose,
|
|
101
228
|
with nothing unexpected in its message log.
|
|
102
229
|
- **Set each state up from the address** rather than by clicking: one URL per state, e.g.
|
|
103
230
|
`http://localhost:5190/#?type=none&viewer=&display=dialog&token=forbidden`, or
|
|
@@ -118,10 +245,53 @@ only output is one JSON result, so the guidance it would print in a terminal is
|
|
|
118
245
|
the plugin's token and reads its secrets.
|
|
119
246
|
- For a catalog plugin, `manifest check` passes.
|
|
120
247
|
|
|
121
|
-
|
|
248
|
+
## 5. Host it
|
|
249
|
+
|
|
250
|
+
A developer deploying their own way needs only what any host must give the plugin (_Hosting your
|
|
251
|
+
plugin_ in `llms.txt`): say it, and leave the how to them. Otherwise deploy to the host from step
|
|
252
|
+
1, as `hosts.md` describes for it, under these rules on any host:
|
|
122
253
|
|
|
123
|
-
- **
|
|
124
|
-
|
|
254
|
+
- **Nothing that could cost money without a yes.** Before creating an account, a project or a
|
|
255
|
+
service, say in a sentence what you'll create and that it's on the free plan, then wait. Never
|
|
256
|
+
enter payment details. If the host asks for a card, stop and explain why.
|
|
257
|
+
- **The address is permanent.** Confirm the plugin's name in it with the author before the first
|
|
258
|
+
deploy: support allows that exact address, and admins add the plugin by it.
|
|
259
|
+
- **Check what you can before the author signs up for anything:** build, and any dry run the host
|
|
260
|
+
offers.
|
|
261
|
+
- **Whose account.** Suggest the company's account at that host, or a shared company email, so
|
|
262
|
+
the plugin outlives whoever made it. A personal account is the author's call, once they've heard
|
|
263
|
+
that risk.
|
|
264
|
+
- **Secrets go in by hand.** The author types each secret into the host's dashboard; name the page
|
|
265
|
+
and the field. Never ask them to paste one into the chat.
|
|
266
|
+
- **The author does what only a person can** (signing up, logging in through the browser): one
|
|
267
|
+
step at a time, saying what they'll see. Run everything else yourself.
|
|
268
|
+
|
|
269
|
+
Then check the deployed page as in step 4, at its new address (start the studio with
|
|
270
|
+
`--url <address>`), and tell the author:
|
|
271
|
+
|
|
272
|
+
- **The address**, and that Livespace support must allow it for their account before it shows.
|
|
273
|
+
- **Who adds it**: an admin of the account, by its address, in Account settings → Plugins, after
|
|
274
|
+
asking support to allow it. If that isn't the author, write them a short note to forward to the
|
|
275
|
+
admin, with the address and those two steps.
|
|
125
276
|
- **What happens to the keys**, if it has any: where the private halves are, what to do with them,
|
|
126
277
|
and where the public ones must be published.
|
|
127
278
|
- **That config is not secret storage**, if the plugin has any settings.
|
|
279
|
+
|
|
280
|
+
### A catalog plugin: listing, testing, review
|
|
281
|
+
|
|
282
|
+
Livespace lists a catalog plugin, not this skill: give whoever lists it the deployed address and
|
|
283
|
+
`plugin-manifest.json`, and say so to the author.
|
|
284
|
+
|
|
285
|
+
- **A new entry is hidden from customers.** An internal Livespace instance lists every entry, and
|
|
286
|
+
that's where it's tested. Walk the tester through this there, and fix, bump `version` and
|
|
287
|
+
redeploy for each failure:
|
|
288
|
+
- the card and details show the right name, texts and images, in English, Polish and Romanian;
|
|
289
|
+
- it can only be placed on the types it declares;
|
|
290
|
+
- on a real record it shows the record's data, and updates without a reload when it's edited;
|
|
291
|
+
- its settings form appears (an empty one if it has none), and its preview renders;
|
|
292
|
+
- the narrowest and the widest slot both read well.
|
|
293
|
+
- **Before review:** real images, and the Polish and Romanian texts reviewed by a native speaker.
|
|
294
|
+
- **Publishing it to every account is a reviewer's decision, made in Livespace.** Prepare a review
|
|
295
|
+
note for the author to hand over: what it does and where it appears, the checklist with its
|
|
296
|
+
results, how it uses the Livespace API, its settings, and open issues. Never say it's published
|
|
297
|
+
when it has only been deployed or listed.
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
# Hosts
|
|
2
|
+
|
|
3
|
+
Where a plugin can live, for step 5 of the skill. _Hosting your plugin_ in `llms.txt` says what
|
|
4
|
+
every host must give a plugin; this file says how to deploy to each host, and which one to suggest.
|
|
5
|
+
|
|
6
|
+
**The default is Cloudflare**: one free account serves static plugins and plugins with a backend.
|
|
7
|
+
Suggest it unless the author already has a host they use. The rules in step 5 hold on every host:
|
|
8
|
+
nothing that could cost money without a yes, never a card, secrets typed in by the author.
|
|
9
|
+
|
|
10
|
+
## Cloudflare
|
|
11
|
+
|
|
12
|
+
Checked against Cloudflare's docs on 2026-11-12; `wrangler` 4.161.0 tried under Bun.
|
|
13
|
+
|
|
14
|
+
### What it is, and what's free
|
|
15
|
+
|
|
16
|
+
A plugin is a **Worker with static assets**: Cloudflare's recommendation for new sites over
|
|
17
|
+
Pages. Its address is `https://<plugin-name>.<account-subdomain>.workers.dev`.
|
|
18
|
+
|
|
19
|
+
On the free plan:
|
|
20
|
+
|
|
21
|
+
- **Static files are free and unlimited.**
|
|
22
|
+
- **A backend** gets 100,000 requests a day and 10 ms of CPU per request. Over that, it returns
|
|
23
|
+
errors until midnight UTC; nothing is charged.
|
|
24
|
+
- **Up to 100 Workers per account.**
|
|
25
|
+
- **Avoid anything that asks for a card:** R2, Workers Paid, Zero Trust. A plugin needs none of
|
|
26
|
+
them.
|
|
27
|
+
|
|
28
|
+
### What only the author can do
|
|
29
|
+
|
|
30
|
+
First ask whether the company already has a Cloudflare account, and who runs it: then it's that
|
|
31
|
+
person's to set up, or to invite the author. Otherwise walk the author through each, one at a time:
|
|
32
|
+
|
|
33
|
+
1. **Sign up** at https://dash.cloudflare.com/sign-up, with the company's email if they can (step
|
|
34
|
+
5, "Whose account"). If Cloudflare emails them a link to confirm the address, they click it.
|
|
35
|
+
2. **Pick the account's name in addresses** (Cloudflare calls it the subdomain: the part before
|
|
36
|
+
`.workers.dev`), in the dashboard under **Workers & Pages**, where it asks for one on a new
|
|
37
|
+
account. It's in every plugin's address, so the company's name is a good choice. Have them do
|
|
38
|
+
this before the first deploy: otherwise `wrangler` asks for it in a prompt your shell can't
|
|
39
|
+
answer.
|
|
40
|
+
3. **Let you upload to their account:** when you run `wrangler login`, a Cloudflare page opens in
|
|
41
|
+
their browser asking them to allow "Wrangler", with a list of what it may do. Tell them first,
|
|
42
|
+
in plain words: Wrangler is Cloudflare's own tool, which you use to upload the plugin; the list
|
|
43
|
+
is what that tool can do in their account; they click **Allow**.
|
|
44
|
+
4. **Type in each secret**, if the plugin has a backend (below).
|
|
45
|
+
|
|
46
|
+
In plain language, call the Worker "your plugin on Cloudflare", and the subdomain "the name in your
|
|
47
|
+
plugin's address".
|
|
48
|
+
|
|
49
|
+
### Deploying
|
|
50
|
+
|
|
51
|
+
Add Wrangler to the project, so its version is pinned in the lockfile: `bun add -d wrangler`, or
|
|
52
|
+
`npm install -D wrangler`. Run it with `bunx --bun wrangler …`, or `npx wrangler …` under Node. Add
|
|
53
|
+
`.wrangler/`, its local state, to `.gitignore`.
|
|
54
|
+
|
|
55
|
+
**Plain files** (no `package.json`): don't add one for Wrangler. Pin it in the command instead,
|
|
56
|
+
`bunx --bun wrangler@4.161.0 …` or `npx wrangler@4.161.0 …`, the same version every time.
|
|
57
|
+
|
|
58
|
+
1. Add `wrangler.jsonc` to the project, with the plugin's name confirmed with the author (step 5):
|
|
59
|
+
|
|
60
|
+
```jsonc
|
|
61
|
+
{
|
|
62
|
+
"name": "my-plugin", // the first part of the address
|
|
63
|
+
"compatibility_date": "2026-11-01",
|
|
64
|
+
"assets": { "directory": "./dist" }
|
|
65
|
+
}
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
For plain files, `"directory": "./public"`, and there's nothing to build.
|
|
69
|
+
|
|
70
|
+
2. Build, then `wrangler deploy --dry-run`: it needs no account, so do it before the author signs
|
|
71
|
+
up.
|
|
72
|
+
3. `wrangler login` (step 3 above). It waits until they click **Allow**, so give the command time
|
|
73
|
+
(a few minutes). If no browser opens, or they're on another machine, run
|
|
74
|
+
`wrangler login --browser=false` and give them the link it prints. Then `wrangler whoami` to
|
|
75
|
+
confirm.
|
|
76
|
+
4. `wrangler deploy`. The first deploy creates the Worker, which the author's yes to the account
|
|
77
|
+
covers; later ones update it. Wrangler prints the address.
|
|
78
|
+
|
|
79
|
+
**Don't use `wrangler dev` under Bun:** it answers every request with 503 (a Bun bug that Wrangler
|
|
80
|
+
names). Preview with the project's dev server and Plugin Studio, as step 4 says.
|
|
81
|
+
|
|
82
|
+
### The key set's headers
|
|
83
|
+
|
|
84
|
+
For a plugin added by URL with secret fields, put `_headers` in `public/`, which the build copies
|
|
85
|
+
into `dist/`:
|
|
86
|
+
|
|
87
|
+
```
|
|
88
|
+
/.well-known/livespace/jwks.json
|
|
89
|
+
Access-Control-Allow-Origin: *
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
Cloudflare serves `.well-known/`, and `jwks.json` as `application/json`. `_headers` itself isn't
|
|
93
|
+
served.
|
|
94
|
+
|
|
95
|
+
### A backend
|
|
96
|
+
|
|
97
|
+
A Worker's backend is one `fetch` handler; the static files are served without running it.
|
|
98
|
+
|
|
99
|
+
```jsonc
|
|
100
|
+
{
|
|
101
|
+
"name": "my-plugin",
|
|
102
|
+
"main": "src/worker.ts",
|
|
103
|
+
"compatibility_date": "2026-11-01",
|
|
104
|
+
"assets": { "directory": "./dist", "binding": "ASSETS", "run_worker_first": ["/api/*"] }
|
|
105
|
+
}
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
```ts
|
|
109
|
+
export default {
|
|
110
|
+
async fetch(request: Request, env: { ASSETS: Fetcher; API_KEY: string }) {
|
|
111
|
+
const url = new URL(request.url)
|
|
112
|
+
if (url.pathname.startsWith("/api/")) {
|
|
113
|
+
// Verify the plugin's token first: _Your backend_ in llms.txt.
|
|
114
|
+
// env.API_KEY is the secret the author typed in.
|
|
115
|
+
}
|
|
116
|
+
return env.ASSETS.fetch(request)
|
|
117
|
+
},
|
|
118
|
+
}
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
`_headers` doesn't apply to what the handler returns: set those headers in code.
|
|
122
|
+
|
|
123
|
+
**Secrets:** the author adds each one in the dashboard: **Workers & Pages** → the plugin's
|
|
124
|
+
Worker → **Settings** → **Variables and Secrets** → **Add**, type **Secret**, the name you give
|
|
125
|
+
them (for example `API_KEY`), the value, then **Deploy**. The handler reads it as
|
|
126
|
+
`env.API_KEY`.
|
|
127
|
+
Deploy the Worker once before this, so it exists.
|
|
128
|
+
|
|
129
|
+
### Not covered
|
|
130
|
+
|
|
131
|
+
No EU-only location for a Worker or its files: requests run wherever is nearest the visitor.
|
|
132
|
+
|
|
133
|
+
## Other hosts
|
|
134
|
+
|
|
135
|
+
Authors may already use another: Netlify, Vercel, GitHub Pages, or, for a backend, Fly.io or
|
|
136
|
+
Render. Nothing here has been checked for them. Use the host's own docs for each command, and hold
|
|
137
|
+
it to the same rules: what _Hosting your plugin_ requires, and step 5's.
|