Follow the steps below to get started with Cosmic to power content for your Next.js application.
Install a new Next.js app
npx create-next-app@latest cosmic-next
Answer the prompts with the following answers:
- Would you like to use TypeScript? Yes
- Would you like to use ESLint? Yes
- Would you like to use Tailwind CSS? Yes
- Would you like to use
src/directory? No - Would you like to use App Router? (recommended) Yes
- Would you like to customize the default import alias (@/*)? No
Go into the project folder.
cd cosmic-next
Install the Cosmic JavaScript SDK
Install the Cosmic JavaScript SDK in the location of the codebase.
npm i @cosmicjs/sdk
Add an Object type in the Cosmic dashboard
Log in to the Cosmic dashboard and create a new Blog Posts Object type in a new or existing Project with the following metafields:
- Image: Image type with key
image - Content: Rich text with key
content
Add content
Add a few blog posts to get some content ready to be delivered.
Add the following code to your app/page.tsx file
// app/page.tsx
import { createBucketClient } from '@cosmicjs/sdk';
const cosmic = createBucketClient({
bucketSlug: process.env.BUCKET_SLUG || '',
readKey: process.env.BUCKET_READ_KEY || '',
});
export default async function Home() {
const { objects: posts } = await cosmic.objects
.find({
type: 'blog-posts',
})
.props('title,metadata.image,metadata.content');
return (
<>
{posts?.map(
(post: {
title: string,
metadata: { image: { imgix_url: string }, content: string },
}) => {
return (
<div key={post.title}>
<div>{post.title}</div>
<div>
<img
src={`${post.metadata.image.imgix_url}?w=500&auto=format,compression`}
alt={post.title}
/>
</div>
<div
dangerouslySetInnerHTML={{ __html: post.metadata.content }}
/>
</div>
);
}
)}
</>
);
}
Add your Cosmic API keys
In a new file titled .env.local add the following environment variables and make sure to switch out the values with your Cosmic API keys found in Project / API keys.
# .env.local
BUCKET_SLUG=add_your_bucket_slug_here
BUCKET_READ_KEY=add_your_bucket_read_key_here
Start the app
Start your app with the following command, go to http://localhost:3000, and see your blog posts.
npm run dev
FAQ
Does this work with the App Router?
Yes. The sample is an async server component in app/page.tsx. Fetch there so the read key stays on the server.
Where do the keys go?
.env.local as BUCKET_SLUG and BUCKET_READ_KEY. Do not prefix the write key with NEXT_PUBLIC_.
How do I preview drafts?
Pass previewToken to createBucketClient and call .status('any'). The short version is https://www.cosmicjs.com/docs/how-to/preview-nextjs.md.
How much does Cosmic cost?
Project plans are Free ($0), Builder ($99/mo), Team ($299/mo), Business ($499/mo), Enterprise (custom pricing). Yearly billing saves 10%. Workspace plans are Small Workspace ($999/mo) and Large Workspace ($2,999/mo), and they start with a 30-day free trial. Allowances, add-on rates, and the rest of the pricing FAQ are plain text at https://www.cosmicjs.com/pricing.md.
Are API keys required, and is content private?
Each Bucket has a read key and a write key in Bucket Settings > API Access. GET requests use the read key. POST, PATCH, and DELETE use the write key as Authorization: Bearer. Do not put the write key in a browser bundle, a mobile app, or a NEXT_PUBLIC_ variable. SAML single sign-on is on Large Workspace and Enterprise. The audit log is append-only. Text versions: https://www.cosmicjs.com/security.md and https://www.cosmicjs.com/docs/dashboard/audit-log.md.
Can an agent create a Cosmic project without an existing account?
Yes. POST https://dapi.cosmicjs.com/v3/agents/sign-up provisions a free-tier project and bucket tied to a human email, with no existing Cosmic account. The human claims it with the emailed one-time code. The playbook is https://www.cosmicjs.com/docs/ai-onboarding.md.