Webiny SDK

Overview

The Webiny SDK (@webiny/sdk) is a TypeScript library providing a programmatic interface to interact with your Webiny instance from external JavaScript or TypeScript applications like Next.js, Vue, SvelteKit, or Node.js scripts.

When to Use the SDK

The SDK is for external applications that need to read or write content from Webiny. This is different from:

• Admin extensions - Building within the Webiny Admin UI
• API extensions - Adding backend logic via Lambda extensions

Use the SDK when your frontend or backend application lives outside Webiny and needs to interact with Webiny’s content.

Installation

Install the package:

Initialize once with your API credentials:

What the SDK Provides

The SDK provides access to Webiny applications through namespaced modules:

Authentication

The SDK authenticates using an API key token generated in the Webiny Admin application (Settings → API Keys). Without a valid token, all SDK calls are rejected.

API Keys in Webiny Admin

(click to enlarge)

API keys have configurable permissions for each Webiny application (Headless CMS, File Manager, etc.).

Core Concepts

Result Pattern

Every SDK method returns a Result object instead of throwing errors. Check success with isOk():

This makes error handling explicit—you can’t accidentally forget to handle failures.

Fields Parameter

The fields parameter specifies which fields to return, keeping responses lean:

When omitted, the SDK returns all fields. The depth parameter (default: 1) controls how deeply reference fields are resolved.

TypeScript Generics

SDK methods accept generic type parameters for fully typed returns:

SDK Modules

CMS Module

Access Headless CMS content:

Error Handling

All SDK methods return Result objects. Always check for errors:

Best Practices

Environment Variables

Store credentials in environment variables:

Singleton Instance

Create one SDK instance and reuse it:

Import this instance throughout your application.

Type Safety

Define interfaces for your content models:

Use generics with SDK calls:

Field Selection

Only request fields you need:

GraphQL Alternative

The SDK is a convenience layer over GraphQL. You can use GraphQL directly if preferred:

The SDK handles query construction, authentication headers, and error parsing automatically.