Webiny Sdk
Using @webiny/sdk to read and write CMS data from external applications.
Install
npx skills add webiny/webiny-js --skill webiny-sdk -g -a claude-code -y- Repository
- webiny/webiny-js8.1k
- Category
- Writing
- Updated
- 5d ago
- License
- See repository
- Context cost
- Mediumabout 3,000 tokens
- Runs scripts
- No, instructions only
What it does
Using @webiny/sdk to read and write CMS data from external applications. Use this skill when the developer is building a Next.js, Vue, Node.js, or any external app that needs to fetch or write content to Webiny, set up the SDK, use the Result pattern, list/get/create/update/publish entries, filter and sort queries, use TypeScript generics for type safety, work with the File Manager, list languages, trigger or monitor background tasks, or create API keys programmatically. Covers read vs preview mode, the `values` wrapper requirement, correct method names, and the `fields` required parameter, and background task management via `sdk.tasks`. Also covers common SDK errors and troubleshooting, especially "Content model '<modelName>' not found" (which usually means the API key lacks permission, not that the model is missing) and the Website Builder starter pitfall of reusing NEXT_PUBLIC_WEBSITE_BUILDER_API_KEY for Headless CMS reads (that key has no CMS permissions by default and needs either extension or replacement with a CMS-scoped key).
Webiny SDK
TL;DR
The @webiny/sdk package provides a TypeScript interface for external apps (Next.js, Vue, Node.js) to interact with Webiny's Headless CMS and File Manager. Every method returns a Result object (checked with isOk()). Supports listing, getting, creating, updating, publishing, and unpublishing entries with filtering, sorting, pagination, and TypeScript generics for type safety.
Installation & Setup
npm install @webiny/sdk
Initialize once and reuse:
// lib/webiny.ts
import { Webiny } from "@webiny/sdk";
export const webiny = new Webiny({
token: process.env.WEBINY_API_TOKEN!,
endpoint: process.env.WEBINY_API_ENDPOINT!,
tenant: process.env.WEBINY_API_TENANT || "root"
});
token-- API key token generated in Webiny Admin (Settings > API Keys)endpoint-- The base API URL, without a trailing slash. Runyarn webiny infoin your Webiny project to find the API URL. For Website Builder projects useNEXT_PUBLIC_WEBSITE_BUILDER_API_HOST.tenant-- Tenant ID, defaults to"root"
IMPORTANT: Never add a trailing slash to
endpoint. The SDK appends/graphqlto the endpoint internally, sohttps://xxx.cloudfront.net/will break all requests.
The fields Parameter (Required)
Every SDK method requires a fields array that specifies which fields to return. Omitting it will cause a runtime error.
- Use
"values.<fieldId>"for content fields:"values.name","values.price" - Use top-level field names for metadata:
"id","entryId","createdOn","status" - Use dot notation for nested fields:
"values.author.name"
// Minimal fields -- just IDs
fields: ["id", "entryId"];
// Content fields
fields: ["id", "entryId", "values.name", "values.price", "values.description"];
// Nested reference fields
fields: ["id", "values.title", "values.author.name", "values.author.email"];
