window.Praisma reference

Praisma injects window.Praisma into every HTML file of a project that declares access. It has four members:

Praisma.capabilities: the capabilities the manifest declares.

Praisma.request(operation, input): calls an operation and returns a promise.

Praisma.media.upload(file, options): uploads a file.

Praisma.auth: visitor sign-in, seeVisitor sign-in.

CMS

// read (cms: { "articles": ["read"] }) const { data, meta } = await Praisma.request("cms.entries.list", { type: "articles", limit: 12, page: 1, sort_by: "published_at", dir: "desc", q: "", locale: "en" }); const { data: entry } = await Praisma.request("cms.entry.read", { type: "articles", id: "ENTRY_ID" }); // only the signed-in visitor's own entries const mine = await Praisma.request("cms.entries.list", { type: "scenes", mine: true }); // write (cms: { "scenes": ["create", "update", "delete"] }) const created = await Praisma.request("cms.entries.create", { type: "scenes", fields: { title: "My scene", notes: "<p>Hi</p>" }, status: "published" }); await Praisma.request("cms.entries.update", { type: "scenes", id: "ENTRY_ID", fields: { title: "Renamed" } }); await Praisma.request("cms.entries.delete", { type: "scenes", id: "ENTRY_ID" });

Lists return published entries;limitis the page size (1 to 50, default 12). Each entry carriesis_minewhen a visitor is signed in.

Writable fields: text, number, date, choice, JSON, rich text (send HTML) and media. Relations and components cannot be written. Every value is validated against the collection's field settings, and every change is versioned.

Writes are drafts.status: "published"is honoured only when the collection hasAllow publishing through the public APIturned on.

Media fields accept only files uploaded by this app. Delete only reaches entries this app created.

Media

const file = new File([blob], "voice.mp3"); const { media_id, url, thumbnail_url } = await Praisma.media.upload(file, { title: "Voice note", alt_text: "", tags: ["app"] }); await Praisma.request("cms.entries.update", { type: "scenes", id, fields: { audio: [media_id] } });

The file name needs a real extension of an approved kind, and the content is checked against it.

Commerce

await Praisma.request("commerce.products.list", { limit: 12, collection: "featured" }); await Praisma.request("commerce.product.read", { slug: "blue-mug" }); await Praisma.request("commerce.cart.read"); await Praisma.request("commerce.cart.add", { product_id: "PRODUCT_ID", quantity: 1 }); await Praisma.request("commerce.cart.update", { item_id: "ITEM_ID", quantity: 2 }); await Praisma.request("commerce.cart.remove", { item_id: "ITEM_ID" }); await Praisma.request("commerce.checkout.navigate"); // goes to the site's checkout

Errors and limits

A failed call rejects with an Error that has a code and a message, for example capability_denied (the published app is not approved for this), capability_not_declared (preview: add it to praisma.json), validation_failed, rate_limited, too_large (requests over 1 MB) or timeout. On the published site, writes are rate limited per visitor and per app; handle loading, empty, success and error states in your UI.

try { await Praisma.request("cms.entries.create", { type: "scenes", fields }); } catch (err) { if (err.code === "rate_limited") showToast("Too many changes, try again later."); else showToast(err.message); }