The Cosmic NPM module is a JavaScript API client for the Cosmic headless CMS, enabling Node.js applications to fetch and manage content from a Cosmic bucket through the legacy API v2.
What is the Cosmic NPM module?
It is the official JavaScript client for Cosmic's API v2, published as an npm package named cosmicjs under the MIT license. It takes a bucket slug and read key as input and returns JSON content from the Cosmic CMS, running in any Node.js environment. It was built by Cosmic and is intended for projects using the old Cosmic dashboard; new projects should use the separate @cosmicjs/sdk package for API v3.
Key Features
This package provides the essentials for reading and writing content from a Node.js backend.
- Install via package managers — Install the module with
pnpm install cosmicjs,yarn add cosmicjs, ornpm install cosmicjs. - Bucket connection — Connect using a bucket slug and read key obtained from the old Cosmic dashboard under API Access settings.
- Flexible queries — The
objects.findmethod retrieves multiple objects by type, with chainable options like.propsto select response properties and.limitto cap the number returned. - Localized content — Queries accept a
localeparameter to return content in a specific language when localization is enabled on objects. - Single object retrieval — Fetch one object by combining a type slug and an object slug in the same
objects.findcall. - Full CRUD operations — The API supports create, read, update, and delete, enabling user-generated content and file uploads from the client.
- Image optimization — Cosmic's infrastructure includes image optimization as a service feature for delivered media.
Who is it for?
This module suits developers who are already invested in the Cosmic ecosystem.
- Node.js developers building applications that need a lightweight client to pull content from a Cosmic bucket.
- Maintainers of legacy Cosmic projects who currently use the old dashboard and API v2 and need to keep their integrations running.
- Teams migrating to API v3 who want to understand the v2 client before upgrading to the
@cosmicjs/sdk.
What can you do with it?
- Fetch content lists: Retrieve multiple objects of a given type, such as
products, with selected properties and a limit. - Load a specific page: Get a single object by slug and optional locale, suitable for dynamic page rendering.
- Accept user submissions: Use the CRUD endpoints to create new objects or upload media from a Node.js backend.
How does it work?
First install the package, then import it in your app. Create an API instance, connect to a bucket using your slug and read key, and call methods such as objects.find to get content. The returned data is plain JSON that you can pass to your frontend.
Pros and cons
- Pros: simple chainable API, supports common content operations, MIT licensed.
- Cons: legacy-only; it connects only to the old Cosmic dashboard and API v2, so it will not work with new API v3 projects and the dashboard at app.cosmicjs.com.
Pricing
Signing up for Cosmic to use this client requires creating a free account; the README links to a free signup at cosmicjs.com but does not list paid tier details.
FAQ
Is the cosmicjs package still supported?
The package works only with projects on the old Cosmic dashboard and API v2. For new projects created on the current dashboard and API v3, Cosmic provides the @cosmicjs/sdk package instead.
How do I install the module?
Use any of the package managers: pnpm install cosmicjs, yarn add cosmicjs, or npm install cosmicjs, and then import it with require("cosmicjs").
Can I use this client to create content?
Yes, the API is fully CRUD capable, so you can add, update, and delete objects, as well as upload media, from your Node.js application.
Where can I get help with this module?
Beyond the official documentation at docs.cosmicjs.com, support channels include the Cosmic Slack community, the GitHub repository for bug reports and contributions, Twitter, and YouTube tutorials.
