Import Design from Archive

import CreativeEngine from '@cesdk/node';
import { config } from 'dotenv';
import { mkdirSync, readFileSync, writeFileSync } from 'fs';

// Load environment variables
config();

/**
 * CE.SDK Server Guide: Import Design from Archive
 *
 * Demonstrates different methods to import archive files in headless mode:
 * - Loading archives from URLs
 * - Loading archives from the filesystem
 * - Loading archives from blobs/buffers
 * - Understanding archive portability
 */

// Initialize CE.SDK engine in headless mode
const engine = await CreativeEngine.init({
  // license: process.env.CESDK_LICENSE, // Optional (trial mode available)
});

try {
  // Create output directory for results
  mkdirSync('output', { recursive: true });

  // ========================================
  // Demonstration: Create Demo Archive
  // ========================================

  // First, create a demo archive to work with for the examples below
  // In production, you would load existing archives from storage

  // Start by creating a scene from an image (no preexisting scene needed)
  const imageUrl = 'https://img.ly/static/ubq_samples/sample_1.jpg';
  await engine.scene.createFromImage(imageUrl);

  // Save this scene as an archive
  const demoArchiveBlob = await engine.scene.saveToArchive();

  // Save the archive to filesystem for demonstration
  const archiveBuffer = Buffer.from(await demoArchiveBlob.arrayBuffer());
  writeFileSync('output/demo-archive.zip', archiveBuffer);

  console.log('✓ Created demo archive: output/demo-archive.zip');

  // ========================================
  // Demonstration 1: Load Archive from Filesystem
  // ========================================

  // In Node.js environments, you often load archives from the filesystem
  // This is common for batch processing or server-side workflows

  // Read the archive file from disk
  const archiveData = readFileSync('output/demo-archive.zip');

  // Convert to Blob for loading
  const archiveBlob = new Blob([archiveData], { type: 'application/zip' });

  // Load the archive
  await engine.scene.loadFromArchive(archiveBlob);

  console.log('✓ Archive loaded from filesystem successfully');

  // ========================================
  // Demonstration 2: Load Archive from Blob
  // ========================================

  // When you have an archive as a Blob (from fetch, API, or database),
  // you can load it directly

  const loadArchiveFromBlob = async (blob: Blob): Promise<void> => {
    try {
      await engine.scene.loadFromArchive(blob);
      console.log('✓ Archive loaded from blob successfully');
    } catch (error) {
      console.error('Failed to load archive from blob:', error);
      throw error;
    }
  };

  // Demonstrate loading from the archive blob we created earlier
  await loadArchiveFromBlob(demoArchiveBlob);

  // ========================================
  // Demonstration 3: Verify Archive Contents
  // ========================================

  // After loading an archive, verify the scene and its contents

  // Find all blocks in the loaded scene
  const pages = engine.block.findByType('page');
  const graphics = engine.block.findByType('graphic');
  const texts = engine.block.findByType('text');

  console.log('\nArchive contents:');
  console.log(`  Pages: ${pages.length}`);
  console.log(`  Graphics: ${graphics.length}`);
  console.log(`  Text blocks: ${texts.length}`);

  // All assets are bundled, so no external URLs are needed
  // This makes archives ideal for portability

  // ========================================
  // Demonstration 4: Modify and Re-export
  // ========================================

  // Modify the loaded scene and export it
  const page = pages[0];
  if (page) {
    // Example: Adjust properties of text blocks
    texts.forEach((textBlock) => {
      // Make all text slightly larger
      const currentSize = engine.block.getFloat(textBlock, 'text/fontSize');
      engine.block.setFloat(textBlock, 'text/fontSize', currentSize * 1.1);
    });

    // Export the modified scene
    const exportBlob = await engine.block.export(page, {
      mimeType: 'image/png',
      targetWidth: 800,
      targetHeight: 600
    });
    const exportBuffer = Buffer.from(await exportBlob.arrayBuffer());
    writeFileSync('output/modified-archive-result.png', exportBuffer);

    console.log(
      '✓ Modified scene exported to: output/modified-archive-result.png'
    );
  }

  // ========================================
  // Demonstration 5: Create New Archive
  // ========================================

  // Save the modified scene as a new archive
  const newArchiveBlob = await engine.scene.saveToArchive();
  const newArchiveBuffer = Buffer.from(await newArchiveBlob.arrayBuffer());
  writeFileSync('output/modified-archive.zip', newArchiveBuffer);

  console.log('✓ New archive saved to: output/modified-archive.zip');

  // Archives are perfect for:
  // - Sharing designs between systems
  // - Offline editing workflows
  // - Backup and versioning
  // - Ensuring all assets are available

  console.log('\n✓ Import from Archive guide completed successfully!');
} finally {
  // Always dispose the engine
  engine.dispose();
  console.log('\n🧹 Engine disposed successfully');
}

Archives solve the portability problem inherent in scene files. While scene files reference assets by URL, archives package everything together in a single .zip file. If asset URLs become unavailable, scene files fail to load properly. Archives avoid this issue by bundling all fonts, images, videos, and other resources directly within the archive, making them self-contained and reliable across different environments.

This guide covers how to load archived scenes from the filesystem, work with blobs, and process archive content in Node.js workflows.

Understanding CE.SDK Archives#

CE.SDK archives are .zip files created with engine.scene.saveToArchive() that contain both the scene structure and all referenced assets. The scene file uses relative paths to reference bundled assets, eliminating the need for external URLs to remain accessible.

Archives contain a predictable directory structure:

• scene.json - Scene structure, layout, and element properties
• images/ - Image assets referenced in the scene
• fonts/ - Font files used by text blocks
• videos/ - Video content referenced in the scene
• audio/ - Audio tracks and sound effects

The scene file references these assets with relative URIs like ./images/photo-abc123.jpg, ensuring they’re always accessible from within the archive.

Load Archive from Filesystem#

In Node.js environments, you often load archives from the filesystem. This is common for batch processing, server-side workflows, and automation tasks.

// In Node.js environments, you often load archives from the filesystem
// This is common for batch processing or server-side workflows

// Read the archive file from disk
const archiveData = readFileSync('output/demo-archive.zip');

// Convert to Blob for loading
const archiveBlob = new Blob([archiveData], { type: 'application/zip' });

// Load the archive
await engine.scene.loadFromArchive(archiveBlob);

console.log('✓ Archive loaded from filesystem successfully');

Read the archive file into a buffer, convert it to a Blob, and load it using engine.scene.loadFromArchive(). The loaded scene replaces the current scene in the engine and becomes immediately available for processing.

Load Archive from Blob#

When you have an archive as a Blob from API responses, fetch operations, or database storage, you can load it directly. The example shows a reusable function that handles blob loading with proper error handling.

// When you have an archive as a Blob (from fetch, API, or database),
// you can load it directly

const loadArchiveFromBlob = async (blob: Blob): Promise<void> => {
  try {
    await engine.scene.loadFromArchive(blob);
    console.log('✓ Archive loaded from blob successfully');
  } catch (error) {
    console.error('Failed to load archive from blob:', error);
    throw error;
  }
};

// Demonstrate loading from the archive blob we created earlier
await loadArchiveFromBlob(demoArchiveBlob);

This pattern is useful for:

• API integration - Download archives from external services
• Database storage - Retrieve archives from blob storage systems
• Stream processing - Handle archives from data streams
• Data conversion - Process archives from various sources (base64, ArrayBuffer, etc.)

Verify Archive Contents#

After loading an archive, verify the scene and its contents to ensure all expected elements are present.

// After loading an archive, verify the scene and its contents

// Find all blocks in the loaded scene
const pages = engine.block.findByType('page');
const graphics = engine.block.findByType('graphic');
const texts = engine.block.findByType('text');

console.log('\nArchive contents:');
console.log(`  Pages: ${pages.length}`);
console.log(`  Graphics: ${graphics.length}`);
console.log(`  Text blocks: ${texts.length}`);

// All assets are bundled, so no external URLs are needed
// This makes archives ideal for portability

All blocks and assets from the archive are restored and accessible through the standard block API. Use engine.block.findByType() to locate specific block types and verify the scene structure.

Modify and Re-export#

Modify loaded archive scenes and export them for further processing or storage.

// Modify the loaded scene and export it
const page = pages[0];
if (page) {
  // Example: Adjust properties of text blocks
  texts.forEach((textBlock) => {
    // Make all text slightly larger
    const currentSize = engine.block.getFloat(textBlock, 'text/fontSize');
    engine.block.setFloat(textBlock, 'text/fontSize', currentSize * 1.1);
  });

  // Export the modified scene
  const exportBlob = await engine.block.export(page, {
    mimeType: 'image/png',
    targetWidth: 800,
    targetHeight: 600
  });
  const exportBuffer = Buffer.from(await exportBlob.arrayBuffer());
  writeFileSync('output/modified-archive-result.png', exportBuffer);

  console.log(
    '✓ Modified scene exported to: output/modified-archive-result.png'
  );
}

The loaded scene is fully editable. Apply transformations, modify properties, add or remove blocks, and export the results in any supported format (PNG, JPEG, PDF, video).

Create New Archives#

Save modified scenes as new archives to preserve all changes and bundled assets.

// Save the modified scene as a new archive
const newArchiveBlob = await engine.scene.saveToArchive();
const newArchiveBuffer = Buffer.from(await newArchiveBlob.arrayBuffer());
writeFileSync('output/modified-archive.zip', newArchiveBuffer);

console.log('✓ New archive saved to: output/modified-archive.zip');

// Archives are perfect for:
// - Sharing designs between systems
// - Offline editing workflows
// - Backup and versioning
// - Ensuring all assets are available

Archives are perfect for:

• Sharing designs between systems - Move designs across environments without URL dependencies
• Offline workflows - Process designs without network connectivity
• Backup and versioning - Store complete design snapshots
• Ensuring asset availability - Guarantee all resources are available

Archive Contents and Structure#

Archives use standard ZIP compression with a specific internal structure that makes them self-contained. The scene file references assets using relative paths instead of absolute URLs.

This self-contained structure provides several benefits:

• No external dependencies - All assets are bundled, so external URLs don’t need to remain accessible
• Portable across environments - Archives work identically whether loaded in development, staging, or production
• Offline support - Archives can be loaded without network connectivity
• Version control friendly - Entire designs can be versioned as single files
• Simplified sharing - Send one file instead of coordinating multiple asset URLs

The relative URI pattern (./images/photo-123.jpg) ensures assets are resolved from within the archive regardless of where the archive is hosted or stored.

Archives vs Scene Files#

CE.SDK provides two save formats that handle assets differently:

Scene Files (.scene) are lightweight JSON-based files that store design structure, layout, and properties. When you save a scene, it stores the design structure, all block properties, and URL references to images, fonts, and other resources. Assets are referenced by their original URLs.

Use scene files when:

• Assets remain accessible at their original URLs
• You want minimal file sizes for faster transfers
• Assets are managed separately (CDN, asset management system)
• You’re working in a stable environment with reliable asset URLs

Archives (.zip) bundle the scene file with all referenced assets into a single package. When you create an archive, CE.SDK packages the scene structure along with all images, fonts, videos, and other resources. Assets in archived scenes use relative paths (like ./images/photo-123.jpg) instead of external URLs, making them portable across different environments.

Use archives when:

• You need to share designs across systems without URL dependencies
• Assets might become unavailable at their original locations
• You’re moving designs between environments (development → production)
• You need offline support or long-term storage
• Portability and self-containment are priorities

For more details on creating archives, see the Save a Scene guide.

Asset Availability and Portability#

Archives solve the fundamental asset availability problem that affects scene files. When you load a scene file, all referenced assets must remain accessible at their original URLs. If an image was located at https://example.com/image.jpg when the scene was saved, it must still be accessible there when loaded later.

This creates several challenges:

• URL changes - Moving assets to different servers or CDNs breaks scene file references
• Access control - Changing authentication or permissions makes assets unavailable
• Resource deletion - Removing assets from storage breaks scene loading
• Cross-environment issues - Development URLs don’t work in production and vice versa

Archives eliminate these issues by bundling all assets within the archive itself. The scene uses relative paths (./images/photo.jpg) that always resolve to the bundled assets, regardless of where the archive is stored or loaded.

Performance Considerations#

File Size and Transfer#

Archives bundle all assets, making them significantly larger than scene files:

• Scene files: 10-100KB (structure only, no assets)
• Archives: 1MB-100MB+ (depends on bundled assets)

Large archives require more time to:

• Read from disk or download from storage
• Extract and decompress
• Load into memory

Memory Usage#

Archives extract their contents into memory during loading. Large archives with high-resolution images or videos consume significant memory. Consider:

• Processing archives sequentially in batch workflows to manage memory
• Limiting concurrent archive loads
• Monitoring memory usage during processing

Storage and Backup#

Archives are ideal for long-term storage and backup:

• Single-file archives are easier to manage than multi-file scene + assets
• Archives can be versioned as complete snapshots
• Compressed ZIP format reduces storage costs compared to uncompressed assets

Troubleshooting#

Archive fails to load

When archive loading fails, common causes include:

• Corrupted ZIP file - Verify the archive is a valid ZIP file
• Incompatible format - Ensure the archive was created by CE.SDK, not manually assembled
• Missing scene file - Archives must contain a valid scene.json file
• Unsupported assets - Some asset formats might not be supported

Archive loads but assets are missing

If the scene loads but displays missing assets:

• Verify all asset files are present in the archive ZIP
• Check that asset paths in scene.json match bundled file locations
• Ensure the archive structure follows CE.SDK conventions

Memory errors during loading

When loading very large archives causes memory errors:

• Reduce archive size by compressing or downscaling bundled assets
• Increase available memory for the Node.js process
• Process archives sequentially rather than concurrently

API Reference#