Photoshop Importer for the CE.SDK

Overview

The Photoshop Importer for the CE.SDK allows you to seamlessly integrate Photoshop files into the editor while retaining essential design attributes.

Here’s an overview of the main features:

• File Format Translation: The importer converts PSD files from Adobe Photoshop into the CE.SDK scene file format. The resulting scene archive includes all required assets for immediate use.
• Bulk Importing: The codebase is adaptable for bulk importing, streamlining large-scale projects.

The following Photoshop design elements will be preserved by the import:

• Element grouping: grouped elements will be preserved if possible and enabled.
• Positioning and Rotation: Elements’ positioning and rotation are accurately transferred.
• Image Elements: Images are supported, while image cropping is not yet available.
• Text Elements: Font family continuity is maintained, with options to supply font URIs or use Google fonts. Only bold and italic styles are currently supported.
• Shapes: Rect, Oval, Polygon, and Line shapes are supported, along with custom shapes that might experience minor distortion.
• Colors and Strokes: Solid colors, stroke weight, color, and alignment are faithfully reproduced. Gradient fills are not yet supported.
• Transparency: Transparency is preserved for seamless integration.

This Photoshop Importer bridges the gap between Photoshop files and CE.SDK scenes, enabling efficient transitions while retaining crucial design details. Your input is invaluable as we continue to refine and improve the importer’s capabilities.

Installation

You can install @imgly/psd-importer via npm or yarn. Use the following commands to install the package:

npm install @imgly/psd-importer
yarn add @imgly/psd-importer

Browser Quick-Start Example

import CreativeEngine from '@cesdk/engine';
import {
  PSDParser,
  addGfontsAssetLibrary,
  createWebEncodeBufferToPNG
} from '@imgly/psd-importer';

const blob = await fetch(
  'https://img.ly/showcases/cesdk/cases/photoshop-template-import/socialmedia.psd'
).then((res) => res.blob());
const buffer = await blob.arrayBuffer();
const engine = await CreativeEngine.init({
  license: 'YOUR_LICENSE'
});
// Register the IMG.LY-hosted Google Fonts asset sources used by the
// default font resolver. See "Font Loading" below for details.
await addGfontsAssetLibrary(engine);
const parser = await PSDParser.fromFile(
  engine,
  buffer,
  createWebEncodeBufferToPNG()
);

await parser.parse();

const image = await engine.block.export(
  engine.block.findByType('//ly.img.ubq/page')[0],
  'image/png'
);
const sceneExportUrl = window.URL.createObjectURL(image);
console.log('The imported PSD file looks like:', sceneExportUrl);
// You can now e.g export the scene as archive with engine.scene.saveToArchive()

Saving Scenes with Stable URLs

By default, the PSD importer creates internal buffer:// URLs for imported images. These are transient resources that work well when saving to an archive (engine.scene.saveToArchive()), which bundles all assets together.

However, if you want to save scenes as JSON strings (engine.scene.saveToString()) with stable, permanent URLs (e.g., for storing in a database or referencing CDN-hosted assets), you need to relocate the transient resources first.

Why Relocate?

• Scene Archives (saveToArchive): Include all assets in a single ZIP file. Transient buffer:// URLs work fine.
• Scene Strings (saveToString): Only contain references to assets. Transient URLs won't work when reloading the scene later. You need permanent URLs (e.g., https://).

How to Relocate Transient Resources

After parsing the PSD file, use CE.SDK's native APIs to find and relocate all transient resources:

// 1. Parse the PSD file
const parser = await PSDParser.fromFile(
  engine,
  buffer,
  createWebEncodeBufferToPNG()
);
await parser.parse();

// 2. Find all transient resources (images from the PSD)
const transientResources = engine.editor.findAllTransientResources();

// 3. Upload each resource and relocate to permanent URL
for (const resource of transientResources) {
  const { URL: bufferUri, size } = resource;

  // Extract binary data from the buffer
  const data = engine.editor.getBufferData(bufferUri, 0, size);

  // Upload to your backend/CDN (implement your own upload logic)
  const permanentUrl = await uploadToBackend(data);

  // Relocate the resource to the permanent URL
  engine.editor.relocateResource(bufferUri, permanentUrl);
}

// 4. Now save to string - all URLs will be permanent
const sceneString = await engine.scene.saveToString();

Note on Font URLs

When using the default font resolver with Google Fonts, the resulting scene string will contain IMG.LY CDN URLs (cdn.img.ly) for fonts. If you need fonts hosted on your own infrastructure, configure a custom font resolver instead of using the default Google Fonts integration.

Font Loading

The default font resolver loads Google Fonts from the IMG.LY CDN and substitutes common proprietary fonts (Helvetica, Arial, Times New Roman, etc.) with visually-similar Google Fonts equivalents. The font catalog and fallback aliases are served as two CE.SDK asset sources from the IMG.LY CDN:

| Asset source | Contents | Size (gzipped) | | ------------------------- | -------------------------------------------------------------- | -------------- | | ly.img.gfonts | 1,980 Google Fonts typefaces, one static TTF per weight and style | ~182 KB | | ly.img.gfonts-fallbacks | 16 proprietary-font aliases (Helvetica→Roboto, Arial→Arimo, …) | ~3 KB |

addGfontsAssetLibrary(engine) registers both sources via engine.asset.addLocalAssetSourceFromJSONURI(...). The files are fetched from https://cdn.img.ly/packages/imgly/gfonts/<version>/dist/ttf/ at registration time and CE.SDK caches the font files once resolved.

No extra npm install is required. The sources are internal to IMG.LY and loaded from the CDN; you do not install an additional package.

Customizing font resolution

If you want to resolve fonts from your own asset sources instead (for example, self-hosted fonts or an enterprise catalog), provide a custom fontResolver to the parser — the extension point is unchanged:

import { PSDParser } from '@imgly/psd-importer';

const myResolver = async ({ family, weight, style }, engine) => {
  // Return { typeface, font } from your own asset source, or null.
};

const parser = await PSDParser.fromFile(engine, buffer, encoder, {
  fontResolver: myResolver
});

You can also skip addGfontsAssetLibrary entirely and provide your own resolver if you do not want to depend on the IMG.LY-hosted catalog.

NodeJS Quick-Start Example

Here is a sample code for using the psd-importer in NodeJS.

// index.mjs
// We currently only support ES Modules in NodeJS
import CreativeEngine from '@cesdk/node';
import { promises as fs } from 'fs';
import { PNG } from 'pngjs';
import {
  PSDParser,
  addGfontsAssetLibrary,
  createPNGJSEncodeBufferToPNG
} from '@imgly/psd-importer';

async function main() {
  const engine = await CreativeEngine.init({
    license: 'YOUR_LICENSE'
  });

  // Register the IMG.LY-hosted Google Fonts asset sources used by the
  // default font resolver. See "Font Loading" below for details.
  await addGfontsAssetLibrary(engine);

  const psdSampleUrl =
    'https://img.ly/showcases/cesdk/cases/photoshop-template-import/socialmedia.psd';
  const psdSample = await fetch(psdSampleUrl).then((res) => res.blob());
  const psdSampleBuffer = await psdSample.arrayBuffer();
  const parser = await PSDParser.fromFile(
    engine,
    psdSampleBuffer,
    createPNGJSEncodeBufferToPNG(PNG)
  );
  await parser.parse();

  const image = await engine.block.export(
    engine.block.findByType('//ly.img.ubq/page')[0],
    'image/png'
  );
  const imageBuffer = await image.arrayBuffer();
  await fs.writeFile('./example.png', Buffer.from(imageBuffer));

  engine.dispose();
}
main();

Preserving PSD metadata and spot colors

importPsdWithMetadata(engine, bytes, pngEncoder, options?) imports the scene and stores unsupported PSD attributes for a later export. Pass { metadata: false } to omit the sidecar. The wrapper also restores spot-color names carried by @imgly/psd-exporter.

The metadata-preserving import records optional scene and page provenance so exports cannot associate fresh artwork with deleted original layers or pages. Empty and hidden-only original documents retain their document metadata.

The sidecar also retains the original XMP packet, including author and copyright metadata. On export, the spot-color carrier is updated without replacing other XMP properties. If that update cannot be merged safely, the exporter keeps the original packet and reports METADATA_UNRESTORABLE. Preserved group effects are restored only when an exported native group matches the original imported leaves; flattened or ambiguous groups produce a diagnostic instead of rebuilding the hierarchy.

An editable spot fill is restored only if its layer's pixels match the exported fingerprint and the layer has no new mask. Recoloring or erasing pixels in Photoshop retains those edited pixels. Legacy files without a fingerprint retain their raster appearance and still register the spot-color definition. Skipped fill restoration emits METADATA_UNRESTORABLE.

When using PSDParser directly, verify the original PSD bytes before applying the carrier to the freshly imported scene, using the logger returned by await parser.parse():

import {
  applySpotColors,
  readSpotColorsFromPsd,
  verifySpotColorRasters
} from '@imgly/psd-importer';

const entries = readSpotColorsFromPsd(psdBytes);
const verified = await verifySpotColorRasters(psdBytes, entries);
applySpotColors(engine, entries, logger, verified);

Pass the same entries array to verification and restoration. Without a verified set, applySpotColors registers the definitions and preserves the imported image fills.

Current Limitations

The following features are either not supported by our engine yet or have limited support:

Limitations

Descriptions of specific limitations in areas such as group handling and text formatting:

• Support for Groups is limited, especially for groups with single members.
• Multiple font sizes within different parts of a text layer are not supported.
• Using multiple font families within a single text layer is not supported.
• Text justification is not supported.
• Authored leading preserves its absolute baseline spacing with either engine font line-gap setting, including the legacy SDK 1.72 layout.
• Character fill flags retain visible paint per UTF-16 range. Mixed enabled and disabled fills use transparent colors for disabled ranges while keeping the text block fill enabled; their text stroke remains independent.
• Photoshop small caps are not supported. The importer retains the original text case and emits TEXT_SMALL_CAPS_UNSUPPORTED; it does not interpret small caps as lowercase.
• Tracking and numeric kerning retain their combined spacing per text range on engines with setTextKerning. Older supported engine versions use the weighted block average and emit TEXT_SPACING_AVERAGED when range values differ; uniform spacing remains exact.
• Automatic font kerning retains its enabled or disabled state when the engine exposes text/useKerning. Mixed range flags, or kerning disabled on older engines such as SDK 1.72, import the cached PSD bitmap with TEXT_KERNING_RASTERIZED instead of changing the visible text spacing. A separate visible solid layer-effect stroke is not applied to that bitmap: it would outline the image frame rather than the glyphs and could repaint a stroke already baked into the cache. This limitation emits LAYER_EFFECT_STROKE_ON_RASTERIZED_TEXT_UNSUPPORTED; the cached pixels remain, but a stroke absent from those pixels is missing from the import.
• Warped and sheared text retains its exact cached PSD bitmap plus a hidden, approximate editable alternative with supported fonts and character styles. Hide the appearance layer and reveal its alternative to edit; the versions are independent and do not synchronize. The warning describes the geometry that the alternative cannot retain. Separate layer effects absent from the cached bitmap remain unsupported.
• Editable alternatives marked by the PSD exporter's namespaced XMP and unique layer IDs import even with the default hidden-layer settings. Their role remains distinct from the original layer's metadata identity; unrelated and unmarked hidden layers still follow the normal hidden-layer setting. Without font catalogs, an optional alternative uses the native default and reports the unresolved font; importing its cached appearance still succeeds.

Unsupported Style Sheet Features:

Details on the unsupported advanced text styling and formatting features:

• Diacritic Positioning: Adjusting the position of diacritical marks.
• Kashida Length: Customizing the length of Kashida in Arabic scripts.
• Hindi Numerals: Enabling or disabling the use of Hindi numerals.
• Character Direction: Setting the text direction (e.g., left-to-right, right-to-left).
• Underline Positioning: Adjusting the vertical position of the underline.
• Fill and Stroke Order: Determining whether the fill is applied before the stroke.
• No-Break Text: Preventing line breaks within the text.
• Character Spacing Adjustment (Tsume): Adjusting spacing between characters.
• Baseline Direction: Setting the direction of the text baseline (horizontal or vertical).
• Discretionary Ligatures: Enabling or disabling discretionary ligatures.
• Standard Ligatures: Enabling or disabling standard ligatures.
• Strikethrough: Applying a strikethrough to the text.
• Underline: Applying an underline to the text.
• Font Baseline Positioning: Adjusting the baseline position of the font.
• Baseline Shift: Vertically shifting the text baseline.
• Automatic Leading: Enabling or disabling automatic line spacing.

Unsupported Paragraph Features:

An outline of the unsupported paragraph-level formatting and alignment options:

• Every Line Composer: Optimizes line breaks across the entire paragraph for better text flow.
• Kinsoku Shori Order: Customizes character handling for Japanese text at line ends.
• Hanging Punctuation: Allows punctuation to hang outside text margins for improved alignment.
• Auto Leading: Automatically adjusts line spacing based on font size.
• Glyph Spacing: Adjusts spacing between individual glyphs.
• Word Spacing: Adjusts spacing between words.
• Paragraph Zone: Controls alignment and indentation relative to the text frame.
• Consecutive Hyphens Limit: Sets the maximum number of consecutive hyphens allowed.
• Hyphenation Control: Specifies the minimum number of characters before and after a hyphen in hyphenated words.
• Minimum Hyphenated Word Size: Defines the minimum length of a word that can be hyphenated.
• Automatic Hyphenation: Enables or disables automatic hyphenation.
• Space Adjustment: Adds space before and after paragraphs.
• Paragraph Indentation: Customizes indentation for the start, end, and first line of paragraphs.

Unsupported Blend Modes:

List of blend modes not currently supported by the engine:

• PassThrough
• Dissolve
• LinearBurn
• DarkerColor
• LinearDodge
• LighterColor
• VividLight
• LinearLight
• PinLight
• HardMix
• Subtract
• Divide

Changelog

See CHANGELOG.md for release notes.

License

The software is free for use under the AGPL License.