Wrapper around contentful-export library for full Contentful space exports with progress tracking
npm install @bernierllc/contentful-export-adapterWrapper around contentful-export library for full Contentful space exports with progress tracking, filtering, and structured output.
``bash`
npm install @bernierllc/contentful-export-adapter
- Full Space Export: Export all content types, entries, assets, and locales
- Filtered Exports: Export specific content types or date ranges
- Progress Tracking: Monitor export progress via callbacks
- Asset Download: Optionally download asset files alongside metadata
- Flexible Output: Export to file or return in memory
- Batch Operations: Export multiple content types in one operation
- Type Safety: Full TypeScript support with comprehensive types
`typescript
import { ContentfulExportAdapter } from '@bernierllc/contentful-export-adapter';
const adapter = new ContentfulExportAdapter();
const result = await adapter.exportSpace({
spaceId: 'your-space-id',
managementToken: 'CFPAT-your-token',
});
console.log(Exported ${result.entries?.length} entries);`
`typescript`
await adapter.exportSpace({
spaceId: 'your-space-id',
managementToken: 'CFPAT-your-token',
outputFile: './exports/my-space-export.json',
});
`typescript`
const blogPosts = await adapter.exportSpace({
spaceId: 'your-space-id',
managementToken: 'CFPAT-your-token',
contentType: 'blogPost',
});
`typescriptProgress: ${progress.done}/${progress.total} - ${progress.operation}
const result = await adapter.exportSpaceWithProgress(
{
spaceId: 'your-space-id',
managementToken: 'CFPAT-your-token',
},
(progress) => {
console.log();`
}
);
`typescript`
await adapter.exportSpace({
spaceId: 'your-space-id',
managementToken: 'CFPAT-your-token',
downloadAssets: true,
exportDir: './exports/assets',
});
`typescript
// Export multiple content types separately
const results = await adapter.exportBatch(
{
spaceId: 'your-space-id',
managementToken: 'CFPAT-your-token',
},
{
contentTypes: ['blogPost', 'author', 'category'],
merge: false,
}
);
// Or merge into a single result
const merged = await adapter.exportBatch(
{
spaceId: 'your-space-id',
managementToken: 'CFPAT-your-token',
},
{
contentTypes: ['blogPost', 'author'],
merge: true,
}
);
`
`typescript`
await adapter.exportSpace({
spaceId: 'your-space-id',
environmentId: 'staging',
managementToken: 'CFPAT-your-token',
});
`typescript`
await adapter.exportSpace({
spaceId: 'your-space-id',
managementToken: 'CFPAT-your-token',
includeArchived: true,
includeDrafts: true,
});
`typescript`
try {
adapter.validateConfig({
spaceId: 'my-space',
managementToken: 'CFPAT-token',
maxAllowedLimit: 500,
});
console.log('Configuration is valid');
} catch (error) {
console.error('Invalid configuration:', error.message);
}
Main adapter class for Contentful exports.
#### Methods
##### exportSpace(config: ContentfulExportConfig): Promise
Export a full Contentful space or filtered subset.
Parameters:
- config.spaceId (string, required): Contentful space IDconfig.managementToken
- (string, required): Contentful Management API tokenconfig.environmentId
- (string, optional): Environment ID (defaults to 'master')config.outputFile
- (string, optional): File path to write export JSONconfig.downloadAssets
- (boolean, optional): Download asset files (default: false)config.contentType
- (string, optional): Filter by content type IDconfig.skipContentModel
- (boolean, optional): Skip content types and editor interfacesconfig.skipRoles
- (boolean, optional): Skip roles (default: true)config.skipWebhooks
- (boolean, optional): Skip webhooks (default: true)config.maxAllowedLimit
- (number, optional): Max items per request (default: 1000, max: 1000)config.exportDir
- (string, optional): Directory for asset downloadsconfig.includeArchived
- (boolean, optional): Include archived entriesconfig.includeDrafts
- (boolean, optional): Include draft entries
Returns: Export result containing content types, entries, assets, locales, etc.
##### exportSpaceWithProgress(config: ContentfulExportConfig, onProgress: (progress: ExportProgress) => void): Promise
Export space with progress tracking via callback.
Parameters:
- config: Export configuration (same as exportSpace)onProgress
- : Callback invoked with progress updates
Returns: Export result
##### exportBatch(config: Omit
Export multiple content types in batch.
Parameters:
- config: Base export configuration (without contentType)options.contentTypes
- : Array of content type IDs to exportoptions.merge
- : Whether to merge results into single export (default: false)
Returns: Array of results (if merge=false) or merged result (if merge=true)
##### validateConfig(config: ContentfulExportConfig): boolean
Validate export configuration before running.
Parameters:
- config: Configuration to validate
Returns: true if valid, throws error if invalid
#### ContentfulExportConfig
Configuration for export operations.
`typescript`
interface ContentfulExportConfig {
spaceId: string;
environmentId?: string;
managementToken: string;
outputFile?: string;
downloadAssets?: boolean;
contentType?: string;
skipContentModel?: boolean;
skipRoles?: boolean;
skipWebhooks?: boolean;
maxAllowedLimit?: number;
exportDir?: string;
includeArchived?: boolean;
includeDrafts?: boolean;
}
#### ContentfulExportResult
Result of an export operation.
`typescript`
interface ContentfulExportResult {
contentTypes?: Array
entries?: Array
assets?: Array
locales?: Array
webhooks?: Array
roles?: Array
editorInterfaces?: Array
tags?: Array
}
#### ExportProgress
Progress information during export.
`typescript`
interface ExportProgress {
done: number;
total: number;
operation?: string;
}
#### BatchExportOptions
Options for batch export operations.
`typescript`
interface BatchExportOptions {
contentTypes: string[];
merge?: boolean;
}
Sync API)
- ❌ Import operations (use contentful-import separately)
- ❌ Database storage (use @bernierllc/contentful-sync-service)Dependencies
-
@bernierllc/contentful-types: TypeScript types for Contentful data
- @bernierllc/logger: Structured logging
- @bernierllc/file-handler: File operations
- contentful-export: Official Contentful export libraryRelated Packages
- @bernierllc/contentful-cda-client: Content Delivery API client with Sync API
- @bernierllc/contentful-sync-service: Continuous synchronization service
- @bernierllc/contentful-types: Shared TypeScript types
Integration Points
$3
All operations are logged with structured context:
`typescript
// Automatic logging included
const adapter = new ContentfulExportAdapter();
// Logs: "Starting Contentful export", "Export completed successfully", etc.
`$3
Not applicable - this is a core utility package focused on export operations.
Error Handling
The adapter throws descriptive errors for common issues:
`typescript
try {
await adapter.exportSpace(config);
} catch (error) {
// Error: "Contentful export failed: Invalid token"
// Error: "Contentful export failed: Space not found"
console.error(error.message);
}
`Common errors:
- Invalid management token
- Space not found
- Insufficient permissions
- Rate limiting
- Network errors
Performance Considerations
- Rate Limits: Contentful enforces API rate limits (7 requests/sec)
- Large Exports: Use
maxAllowedLimit to control batch size
- Asset Downloads: Can significantly increase export time
- Progress Tracking: Minimal overhead for progress callbacksBest Practices
1. Use Content Type Filters: Export specific content types to reduce payload size
2. Skip Unnecessary Data: Use
skipRoles, skipWebhooks for faster exports
3. Progress Tracking: Monitor long-running exports with progress callbacks
4. File Output: Write large exports to disk to avoid memory issues
5. Batch Operations: Use exportBatch to organize related content typesTesting
Run tests with coverage:
`bash
npm test
npm run test:coverage
``Coverage Target: 90%+ (core package requirement)
Copyright (c) 2025 Bernier LLC
This file is licensed to the client under a limited-use license.
The client may use and modify this code only within the scope of the project it was delivered for.
Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
For issues or questions, contact Bernier LLC or file an issue in the repository.