Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Contentstack
✓ import Contentstack from 'contentstack';
✗ import { Contentstack } from 'contentstack';
This is the primary default export for the SDK. For CommonJS, `const Contentstack = require('contentstack');` is typically used and correctly returns the default export.
Stack
✓ import Contentstack from 'contentstack'; const Stack = Contentstack.Stack({ ... });
✗ import { Stack } from 'contentstack';
The `Stack` initialization method is accessed as a property of the default `Contentstack` export, not a named export itself.
Region (Enum)
✓ import Contentstack from 'contentstack'; Contentstack.Region.EU;
✗ import { Region } from 'contentstack';
Region enum values (e.g., EU, AU, AZURE_NA, GCP_EU) are properties of the default `Contentstack` export, used for configuring the delivery region during SDK initialization.
This quickstart demonstrates how to initialize the Contentstack SDK and fetch a single entry by its content type UID and entry UID. It includes essential error handling for missing credentials and showcases region configuration.
import Contentstack from 'contentstack';
const API_KEY = process.env.CONTENTSTACK_API_KEY ?? '';
const DELIVERY_TOKEN = process.env.CONTENTSTACK_DELIVERY_TOKEN ?? '';
const ENVIRONMENT = process.env.CONTENTSTACK_ENVIRONMENT ?? '';
const CONTENT_TYPE_UID = 'blog'; // Replace with your content type UID
const ENTRY_UID = 'your_entry_uid'; // Replace with a specific entry UID
if (!API_KEY || !DELIVERY_TOKEN || !ENVIRONMENT) {
console.error('Missing Contentstack credentials. Please set CONTENTSTACK_API_KEY, CONTENTSTACK_DELIVERY_TOKEN, and CONTENTSTACK_ENVIRONMENT environment variables.');
process.exit(1);
}
const Stack = Contentstack.Stack({
api_key: API_KEY,
delivery_token: DELIVERY_TOKEN,
environment: ENVIRONMENT,
// Optional: Set a specific region, e.g., for Europe
// region: Contentstack.Region.EU
});
async function fetchEntry() {
try {
const query = Stack.ContentType(CONTENT_TYPE_UID).Entry(ENTRY_UID);
const entry = await query.toJSON().fetch();
console.log('Fetched Entry Title:', entry.get('title'));
console.log('Entry content:', entry.toJSON());
} catch (error) {
console.error('Error fetching entry:', error);
}
}
fetchEntry();
Debug
Known issues
breakingA security vulnerability (CVE-2025-15284) related to the 'qs' dependency was fixed in `v3.26.4`. Prior versions are affected.fixUpgrade to `contentstack@3.26.4` or higher to mitigate the 'qs' dependency vulnerability.
affects: <3.26.4
gotchaApplications using `contentstack` versions prior to `3.27.0` may experience process crashes due to unhandled socket errors (`UND_ERR_SOCKET`) during network connection drops.fixUpgrade to `contentstack@3.27.0` or higher to ensure robust handling of connection drops and prevent process termination.
affects: <3.27.0
gotchaThe SDK requires Node.js version 10.14.2 or higher. Running on older Node.js environments may lead to unexpected errors, initialization failures, or runtime crashes. The TypeScript Delivery SDK specifically recommends Node.js 22 or later.fixEnsure your Node.js environment meets the minimum requirement of 10.14.2, and ideally use 22 or later for TypeScript projects.
affects: <current
gotchaFailing to correctly specify the region (e.g., `Contentstack.Region.EU`, `Contentstack.Region.AU`, `Contentstack.Region.AZURE_NA`, `Contentstack.Region.GCP_EU`) during SDK initialization can result in content fetching failures or increased latency if the default North American region is not desired.fixInitialize the SDK with the correct `region` parameter, for example: `Contentstack.Stack({... "region": Contentstack.Region.EU });` affects: >=3.0.0
breakingThe underlying Contentstack platform has deprecated Access Tokens for stacks created after December 16, 2020. While older stacks still support them, new stacks require Delivery Tokens for content fetching via the Delivery API.fixFor new Contentstack stacks (created after Dec 16, 2020), always use Delivery Tokens instead of Access Tokens. Update your SDK initialization to use `delivery_token`.
affects: >=3.0.0 (for new stacks)
Errors
Common errors & fixes
TypeError: Contentstack is not a function
Attempting to import `Contentstack` as a named export (`import { Contentstack } from 'contentstack';`) when it's a default export, or trying to directly call `Contentstack()` as a constructor when `Contentstack.Stack()` is the correct method for initialization.
fixUse the correct default import: `import Contentstack from 'contentstack';` and then initialize with `Contentstack.Stack({...});`. Contentstack: api_key, delivery_token or environment is missing
The SDK initialization object is missing one or more of the required `api_key`, `delivery_token`, or `environment` parameters.
fixEnsure all three required parameters (`api_key`, `delivery_token`, and `environment`) are provided in the object passed to `Contentstack.Stack()`.
ReferenceError: Contentstack is not defined
In a browser environment, the Contentstack SDK script tag was not loaded, or the variable is being accessed before the script has executed and defined it globally. In Node.js, the import statement might be missing or incorrect.
fixFor browsers, ensure `<script src="https://cdn.jsdelivr.net/npm/contentstack@latest/dist/web/contentstack.min.js"></script>` is loaded before usage. For Node.js/ESM, ensure `import Contentstack from 'contentstack';` is at the top of your file.
Error: Request failed with status code 401 (Unauthorized)
The provided `api_key` or `delivery_token` is incorrect, expired, or does not have permissions to access the specified environment or content.
fixVerify that your `api_key`, `delivery_token`, and `environment` are correct and have the necessary permissions in your Contentstack account. Ensure you are using a Delivery Token for content fetching.
UND_ERR_SOCKET
Unhandled socket errors occurring during network connection drops, leading to process termination in older SDK versions.
fixUpgrade the `contentstack` SDK to version `3.27.0` or higher to benefit from the fix for connection drop handling.
Audit
Dependencies
qsrequiredVulnerable versions (CVE-2025-15284) were previously used; updated in v3.26.4.