Skip to content

The SDK

The StudioCMS SDK is a powerful tool that allows you to interact with StudioCMS programmatically. It provides a set of functions and utilities that allow you to manage and serve your content using Astro DB. It also provides the backbone for the StudioCMS Dashboard, and is built with Effect^.

The StudioCMS SDK is available as a virtual module in your Astro project. You can import and utilize it using the following syntax:

example.ts
import {
const SDKCore: Effect.Effect<SDKCore, never, never>

The new Effect-TS based SDK implementation that replaces the deprecated SDK. This unified SDK merges the normal and cached SDK functionalities.

@example

import { Effect } from 'studiocms/effect';
import { SDKCore } from 'studiocms:sdk';
const db = Effect.gen(function* () {
const sdk = yield* SDKCore;
return sdk.db;
}).pipe(Effect.provide(SDKCore.Default));

SDKCore
,
const SDKCoreJs: {
db: Database;
dbService: AstroDB;
getFullPath: (tree: FolderNode[], path: string[]) => Effect.Effect<string[], SDKCoreError, never>;
... 32 more ...;
PLUGINS: SDKCore_PLUGINS;
}

VanillaJS Version of the SDKCore. Most internal functions will still contain Effects, you can use runSDK from the 'studiocms:sdk' to run these as normal async functions

@example

import { SDKCoreJs, runSDK } from 'studiocms:sdk';
const pages = await runSDK(SDKCoreJs.GET.pages());

SDKCoreJs
,
const runSDK: <A, E>(effect: Effect.Effect<A, E, never>) => Promise<A>

Utility function for running components of the SDKCoreJs

@example

import { SDKCoreJs, runSDK } from 'studiocms:sdk';
const pages = await runSDK(SDKCoreJs.GET.pages());

runSDK
} from 'studiocms:sdk';
import {
import Effect

@since2.0.0

@since2.0.0

@since2.0.0

Effect
} from 'studiocms/effect';
// Create the Usable Effect
const
const pagesEffect: Effect.Effect<PageDataCacheObject[], SDKCoreError, never>
pagesEffect
=
import Effect

@since2.0.0

@since2.0.0

@since2.0.0

Effect
.
const gen: <YieldWrap<Effect.Effect<SDKCore, never, never>> | YieldWrap<Effect.Effect<PageDataCacheObject[], SDKCoreError, never>>, PageDataCacheObject[]>(f: (resume: Effect.Adapter) => Generator<...>) => Effect.Effect<...> (+1 overload)

Provides a way to write effectful code using generator functions, simplifying control flow and error handling.

When to Use

Effect.gen allows you to write code that looks and behaves like synchronous code, but it can handle asynchronous tasks, errors, and complex control flow (like loops and conditions). It helps make asynchronous code more readable and easier to manage.

The generator functions work similarly to async/await but with more explicit control over the execution of effects. You can yield* values from effects and return the final result at the end.

Example

import { Effect } from "effect"
const addServiceCharge = (amount: number) => amount + 1
const applyDiscount = (
total: number,
discountRate: number
): Effect.Effect<number, Error> =>
discountRate === 0
? Effect.fail(new Error("Discount rate cannot be zero"))
: Effect.succeed(total - (total * discountRate) / 100)
const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))
const fetchDiscountRate = Effect.promise(() => Promise.resolve(5))
export const program = Effect.gen(function* () {
const transactionAmount = yield* fetchTransactionAmount
const discountRate = yield* fetchDiscountRate
const discountedAmount = yield* applyDiscount(
transactionAmount,
discountRate
)
const finalAmount = addServiceCharge(discountedAmount)
return `Final amount to charge: ${finalAmount}`
})

@since2.0.0

gen
(function* () {
const
const sdk: SDKCore
sdk
= yield*
const SDKCore: Effect.Effect<SDKCore, never, never>

The new Effect-TS based SDK implementation that replaces the deprecated SDK. This unified SDK merges the normal and cached SDK functionalities.

@example

import { Effect } from 'studiocms/effect';
import { SDKCore } from 'studiocms:sdk';
const db = Effect.gen(function* () {
const sdk = yield* SDKCore;
return sdk.db;
}).pipe(Effect.provide(SDKCore.Default));

SDKCore
;
// then do something with the SDK
return yield*
const sdk: SDKCore
sdk
.
type GET: SDKCore_GET
GET
.
pages: (includeDrafts?: boolean, hideDefaultIndex?: boolean, metaOnly?: false, paginate?: PaginateInput) => Effect.Effect<PageDataCacheObject[], SDKCoreError, never> (+1 overload)
pages
()
});
// Convert the Effect into a JS/TS "program"
const
const pagesResult1: PageDataCacheObject[]
pagesResult1
= await
runSDK<PageDataCacheObject[], SDKCoreError>(effect: Effect.Effect<PageDataCacheObject[], SDKCoreError, never>): Promise<...>

Alias for runEffect, used to run SDK effects and convert them to plain JavaScript objects.

@parameffect - The Effect to be converted.

@returnsA promise that resolves to the plain JavaScript object representation of the effect's result.

runSDK
(
const pagesEffect: Effect.Effect<PageDataCacheObject[], SDKCoreError, never>
pagesEffect
);
// Just run the SDKCoreJS with the runSDK wrapper!
const
const pagesResult2: PageDataCacheObject[]
pagesResult2
= await
runSDK<PageDataCacheObject[], SDKCoreError>(effect: Effect.Effect<PageDataCacheObject[], SDKCoreError, never>): Promise<...>

Alias for runEffect, used to run SDK effects and convert them to plain JavaScript objects.

@parameffect - The Effect to be converted.

@returnsA promise that resolves to the plain JavaScript object representation of the effect's result.

runSDK
(
const SDKCoreJs: {
db: Database;
dbService: AstroDB;
getFullPath: (tree: FolderNode[], path: string[]) => Effect.Effect<string[], SDKCoreError, never>;
... 32 more ...;
PLUGINS: SDKCore_PLUGINS;
}

VanillaJS Version of the SDKCore. Most internal functions will still contain Effects, you can use runSDK from the 'studiocms:sdk' to run these as normal async functions

@example

import { SDKCoreJs, runSDK } from 'studiocms:sdk';
const pages = await runSDK(SDKCoreJs.GET.pages());

SDKCoreJs
.
type GET: SDKCore_GET
GET
.
pages: (includeDrafts?: boolean, hideDefaultIndex?: boolean, metaOnly?: false, paginate?: PaginateInput) => Effect.Effect<PageDataCacheObject[], SDKCoreError, never> (+1 overload)
pages
());

The following is a list of the Primary utils provided by the StudioCMS SDK for interacting with the database.

utils.ts
import {
const SDKCoreJs: {
db: Database;
dbService: AstroDB;
getFullPath: (tree: FolderNode[], path: string[]) => Effect<string[], SDKCoreError, never>;
... 32 more ...;
PLUGINS: SDKCore_PLUGINS;
}

VanillaJS Version of the SDKCore. Most internal functions will still contain Effects, you can use runSDK from the 'studiocms:sdk' to run these as normal async functions

@example

import { SDKCoreJs, runSDK } from 'studiocms:sdk';
const pages = await runSDK(SDKCoreJs.GET.pages());

SDKCoreJs
} from 'studiocms:sdk';
const {
const db: Database
db
,
const dbService: AstroDB
dbService
,
const CLEAR: SDKCore_CLEAR
CLEAR
,
const DELETE: SDKCore_DELETE
DELETE
,
const INIT: SDKCore_INIT
INIT
,
const AUTH: SDKCore_AUTH
AUTH
,
const REST_API: SDKCore_REST_API
REST_API
,
const GET: SDKCore_GET
GET
,
const POST: SDKCore_POST
POST
,
const UPDATE: SDKCore_UPDATE
UPDATE
,
const PLUGINS: SDKCore_PLUGINS
PLUGINS
,
const MIDDLEWARES: SDKCore_MIDDLEWARES
MIDDLEWARES
,
} =
const SDKCoreJs: {
db: Database;
dbService: AstroDB;
getFullPath: (tree: FolderNode[], path: string[]) => Effect<string[], SDKCoreError, never>;
... 32 more ...;
PLUGINS: SDKCore_PLUGINS;
}

VanillaJS Version of the SDKCore. Most internal functions will still contain Effects, you can use runSDK from the 'studiocms:sdk' to run these as normal async functions

@example

import { SDKCoreJs, runSDK } from 'studiocms:sdk';
const pages = await runSDK(SDKCoreJs.GET.pages());

SDKCoreJs
;