A utility package to get Contentstack API endpoints based on cloud and region
npm install @timbenniks/contentstack-endpointsGet the correct Contentstack API endpoints for any region and cloud provider. No more hardcoding URLs or guessing which endpoint to use!
``bash`
npm install @timbenniks/contentstack-endpoints
`typescript
import { getContentstackEndpoints } from "@timbenniks/contentstack-endpoints";
const endpoints = getContentstackEndpoints("eu");
console.log(endpoints.contentDelivery); // https://eu-cdn.contentstack.com
console.log(endpoints.contentManagement); // https://eu-api.contentstack.com
console.log(endpoints.graphqlDelivery); // https://eu-graphql.contentstack.com
`
Just pass a region string directly - clean and simple!
`typescript
import { getContentstackEndpoints } from "@timbenniks/contentstack-endpoints";
// Direct string usage
const endpoints = getContentstackEndpoints("eu");
// Perfect for environment variables
const endpoints = getContentstackEndpoints(
process.env.CONTENTSTACK_REGION || "na"
);
`
Benefits:
- 🎯 Simpler - fewer imports, less code
- 🚀 Cleaner - no enum conversions needed
- ✅ Direct - just pass the string you have
Use when you need explicit type safety or enum validation:
`typescript
import {
getContentstackEndpoints,
getRegionForString,
} from "@timbenniks/contentstack-endpoints";
// Convert string to Region enum first
const region = getRegionForString(process.env.CONTENTSTACK_REGION as string);
const endpoints = getContentstackEndpoints(region, true);
`
When to use this:
- 🛡️ You need explicit Region enum types
- 🔍 You want to validate the region string before use
- 📦 Existing codebase already uses this pattern
Both approaches work perfectly - choose what fits your style!
All official Contentstack regions and aliases (case-insensitive):
| Region | Aliases |
| ----------------------- | -------------------------------------- |
| AWS North America | "na", "us", "aws-na", "aws_na" |"eu"
| AWS Europe | , "aws-eu", "aws_eu" |"au"
| AWS Australia | , "aws-au", "aws_au" |"azure-na"
| Azure North America | , "azure_na" |"azure-eu"
| Azure Europe | , "azure_eu" |"gcp-na"
| GCP North America | , "gcp_na" |"gcp-eu"
| GCP Europe | , "gcp_eu" |
`typescript
import Contentstack from "@contentstack/delivery-sdk";
import { getContentstackEndpoints } from "@timbenniks/contentstack-endpoints";
const endpoints = getContentstackEndpoints("eu");
const stack = Contentstack.stack({
apiKey: "your-api-key",
deliveryToken: "your-token",
environment: "production",
region: endpoints.contentDelivery,
});
`
`typescript`
const endpoints = getContentstackEndpoints(
process.env.CONTENTSTACK_REGION || "na"
);
`typescript`
const endpoints = getContentstackEndpoints("eu", true);
console.log(endpoints.contentDelivery); // eu-cdn.contentstack.com
Returns empty object for invalid inputs (no errors thrown):
`typescript`
getContentstackEndpoints("invalid"); // {}
getContentstackEndpoints(null); // {}
Each region returns an object with these endpoint URLs:
| Property | Description |
| ------------------------- | ----------------------------------------------------- |
| contentDelivery | Content Delivery API (CDN) |contentManagement
| | Content Management API |graphqlDelivery
| | GraphQL API |graphqlPreview
| | GraphQL Preview API |images
| | Image Delivery/Transformation API |assets
| | Assets API |preview
| | REST Preview API |auth
| | Authentication API |automate
| | Automate API |launch
| | Launch API |developerHub
| | Developer Hub API |genAI
| | GenAI & Knowledge Vault API |brandKit
| | Brand Kit API |personalize
| | Personalize Management API |personalizeEdge
| | Personalize Edge API |application
| | Contentstack Web App URL |graphql
| Deprecated Properties | v1.x compatibility - still work but use new names |
| | ⚠️ Use graphqlDelivery instead |imageDelivery
| | ⚠️ Use images instead |brandKitGenAI
| | ⚠️ Use genAI instead |personalizeManagement
| | ⚠️ Use personalize instead |
`typescript`
getContentstackEndpoints(region?: string | Region, omitHttps?: boolean): ContentstackEndpoints
Parameters:
- region - Region string (e.g., "eu", "azure-na") or Region enum (default: "na")omitHttps
- - Remove https:// prefix (default: false)
Returns: Object with endpoint URLs
`typescript`
getRegionForString(regionAsString: string): Region | undefined
Converts a region string to a Region enum. Only needed for Approach 2 (legacy).
---
Maintained by: @timbenniks
Data Source: Auto-synced with Contentstack's official regions
MIT
---
For Maintainers
`bash``
npm run generate-endpoints
This fetches the latest regions data from Contentstack and regenerates types and endpoint mappings. A GitHub Action automatically checks for updates weekly.