Cosmic is a headless CMS (content management system) that provides a web dashboard to create content and an API toolkit to deliver content to any website or application. Nearly any type of content can be built using the dashboard and delivered using this SDK.
Install the Cosmic JavaScript SDK. We recommend using the bun package manager.
bun add @cosmicjs/sdk
# OR
yarn add @cosmicjs/sdk
# OR
npm install @cosmicjs/sdk
Import Cosmic into your app using the createBucketClient
method.
import { createBucketClient } from '@cosmicjs/sdk';
In the Cosmic admin dashboard go to Bucket > Settings > API Access and get your Bucket slug and read key then set the variables in your app to connect to your Bucket.
const cosmic = createBucketClient({
bucketSlug: 'BUCKET_SLUG',
readKey: 'BUCKET_READ_KEY',
});
Objects are the basic building blocks of content in Cosmic.
Use the objects.find()
method to fetch Objects.
const posts = await cosmic.objects
.find({
type: 'posts',
})
.props(['title', 'slug', 'metadata'])
.limit(10);
The above example fetches Objects in the posts
Object type returning the title
, slug
, and metadata
properties, limiting the response to 10
Objects.
Use the objects.findOne()
method with type
and slug
to fetch a single Object.
const post = await cosmic.objects
.findOne({
type: 'pages',
slug: 'home',
})
.props(['title', 'slug', 'metadata']);
To write to the Cosmic API, you will need to set the Bucket write key found in Bucket > Settings > API Access. (NOTE: never expose your write key in any client-side code)
const cosmic = createBucketClient({
bucketSlug: 'BUCKET_SLUG',
readKey: 'BUCKET_READ_KEY',
writeKey: 'BUCKET_WRITE_KEY',
});
Use the objects.insertOne()
method to create an Object.
await cosmic.objects.insertOne({
title: 'Blog Post Title',
type: 'posts',
metadata: {
content: 'Here is the blog post content... still learning',
seo_description: 'This is the blog post SEO description.',
featured_post: true,
tags: ['javascript', 'cms'],
},
});
Use the objects.updateOne()
method to update an Object by specifying the Object id
and include properties that you want to update.
await cosmic.objects.updateOne('5ff75368c2dfa81a91695cec', {
metadata: {
content: 'This is the updated blog post content... I got it now!',
featured_post: false,
},
});
Use the objects.deleteOne()
method to delete an Object by specifying the Object id
.
await cosmic.objects.deleteOne('5ff75368c2dfa81a91695cec');
Go to the Cosmic docs to learn more capabilities.
For additional help, you can use one of these channels to ask a question:
This project uses changeset to manage releases. Follow the following steps to add a changeset:
npm run changeset
command and select type of release with description of changes.main
branch, Github will create a new PR with correct version change and changelog edits.codeowner
merges the generated PR, it will publish the package and create a Github release.This project is published under the MIT license.