The Local API
Read and write content with locals.cms, including where, sort, depth, drafts and every method.
This page documents the Local API: the methods on locals.cms, the options they take and how errors surface.
locals.cms acts as the request's user. On public routes that is an anonymous visitor, so a read returns only what a signed-out visitor may see. It is typed from your config, so collection slugs, field names and results are checked.
import { error } from '@sveltejs/kit';
import type { PageServerLoad } from './$types';
export const load: PageServerLoad = async ({ locals, params }) => {
const post = await locals.cms.findOne('posts', {
where: { slug: { equals: params.slug } },
depth: 1,
});
if (!post) error(404, 'Not found');
return { post };
};Reads
| Method | Returns |
|---|---|
find(collection, args?) |
{ docs, totalDocs, limit, page, totalPages, hasNextPage, hasPrevPage } |
findOne(collection, args?) |
The first match, or null. |
findByID(collection, id, options?) |
The document, or null if it does not exist or the caller may not read it. |
count(collection, args?) |
A number. |
findGlobal(global, options?) |
The global. Never null: an unsaved global returns its defaults. |
find arguments
| Argument | What it does |
|---|---|
where |
A filter. See below. |
sort |
A field name, with - for descending: 'title', '-createdAt'. One field. Default: the collection's defaultSort, else '-createdAt'. Ties break on id. |
limit |
Page size. Default 10, maximum 1000. |
page |
1-based. Default 1. |
depth |
How many levels of relationships to load: 0, 1 or 2. Default 0. |
pagination |
false skips the total count, so totalDocs and totalPages are missing. Saves a query. |
draft |
Include drafts. See below. |
overrideAccess |
Skip access rules. Trusted code only. |
const { docs, totalDocs } = await locals.cms.find('posts', {
where: { publishedAt: { less_than_equal: new Date().toISOString() } },
sort: '-publishedAt',
limit: 12,
page: 2,
depth: 1,
});findOne takes the same arguments except limit, page and pagination.
where
A where object is a conjunction: every field and every and or or entry must hold. {} matches everything.
where: {
status: { equals: 'published' },
or: [{ title: { like: 'kit' } }, { tags: { contains: tagId } }],
}| Operator | On | Meaning |
|---|---|---|
equals, not_equals |
Any value | Equal, or not equal. equals: null matches missing values. |
in, not_in |
Any value | In, or not in, a list. |
exists |
Any value | true is not null, false is null. |
greater_than, greater_than_equal, less_than, less_than_equal |
Numbers and dates | Range. |
like |
Strings | Case-insensitive substring match. %, _ and \ are escaped, so it is not a pattern language. |
contains |
hasMany relationships |
The list includes this ID. in and not_in work too. |
- Several operators on one field are ANDed.
or: []matches nothing.and: []matches everything.- Dates accept an ISO string, a
Dateor epoch milliseconds. - You can filter on
id,createdAt,updatedAt, top-level column fields and top-levelhasManyrelationships. Fields stored as JSON (group, array, blocks, json, richText) cannot be filtered. An unknown or non-filterable field throws aQueryError. - An access rule's filter is added as a separate AND group, so your
wherecan never widen it. See Access rules.
Relationships and depth
At depth: 0, a relationship is an ID. At depth: 1 it is the document, and at depth: 2 the documents inside those. The maximum is 2.
const post = await locals.cms.findByID('posts', id, { depth: 1 });
post?.cover; // a media document; or a string ID if it is missing or not readableA target that is missing or that the caller may not read stays an ID, so its type is the document or string. Population runs as one batched D1 query per level, not one per document.
Drafts
For collections and globals with drafts, reads return published documents only. Pass draft: true to see the latest draft. It needs a signed-in user or overrideAccess.
const preview = await locals.cms.findByID('pages', id, { draft: true });Writes
| Method | What it does |
|---|---|
create(collection, data, options?) |
Creates a document. Returns it. |
update(collection, id, data, options?) |
Partial update. Returns the document. |
delete(collection, id, options?) |
Deletes and returns the document. |
updateGlobal(global, data, options?) |
Partial update of a global. Creates it on the first save. |
move(collection, id, { before } or { after }) |
Reorders a document in an orderable collection. |
unpublish(collection, id) |
Takes a published document offline. |
findVersions, findVersionByID, restoreVersion |
Version history. Globals have findGlobalVersions and restoreGlobalVersion. |
Write options: depth (depth of the returned document), draft (save as a draft), autosave (with draft), overrideAccess, req and context.
const post = await locals.cms.create('posts', { title: 'Hello' });
await locals.cms.update('posts', post.id, { title: 'Hello, world' });
await locals.cms.delete('posts', post.id);Writes run through your access rules as the caller. On a public route locals.cms is anonymous, so the default rules deny writes there. Make content changes in the admin, or in trusted server code with overrideAccess: true. Never pass overrideAccess based on request input.
Errors
Operations throw errors that extend KitcmsError, each with a code and an HTTP status:
| Error | When | Status |
|---|---|---|
ValidationError |
Invalid data. Has errors, a list of { path, message }. |
400 |
ForbiddenError |
An access rule denied the operation. | 403 |
UnauthorizedError |
The caller must sign in. | 401 |
NotFoundError |
The document does not exist (update, move, delete). |
404 |
Referenced (code REFERENCED) |
You deleted a document that others still reference. | 409 |
Query (code QUERY) |
A bad where, sort or option. |
400 |
@kitcms/core exports KitcmsError, ValidationError, ForbiddenError, UnauthorizedError, NotFoundError and isKitcmsError. Check the others by code.
import { isKitcmsError, ValidationError } from '@kitcms/core';
try {
await locals.cms.create('posts', input);
} catch (err) {
if (err instanceof ValidationError) return Response.json({ errors: err.errors }, { status: 400 });
if (isKitcmsError(err)) return Response.json({ code: err.code }, { status: err.status });
throw err;
}Performance
A depth-1 populated read takes two sequential D1 round trips. A write takes two (a create takes one). To make anonymous reads faster still, turn on the edge cache.