Edge Delivery Services Developer FAQ

Terminology

Basics

What's the difference between Edge Delivery Services, Franklin, and Helix?

Edge Delivery Services (EDS) is the official product name; Franklin and Helix are internal code names used during development that still appear in the codebase and documentation.

Edge Delivery Services (EDS) is Adobe's official product name for this document-based CMS. Helix was an earlier internal code name that referenced DNA's spiral structure and is still used in configuration files (e.g., ".helix" folder) and the developer documentation site (aem.live). Franklin is another internal name used during development, and you'll find it in imports and tool names like "Franklin Import UI." These names are technical details; the official product is Edge Delivery Services, but understanding these alternative names helps when working with the codebase and documentation.

- #terminology #names #basics

Fundamentals

Overview

What is Edge Delivery Services?

Edge Delivery Services is Adobe's document-based CMS focused on speed, scalability, and ease of use that allows content authors to use familiar tools like Microsoft Word and Google Docs.

Edge Delivery Services (EDS) is Adobe's cutting-edge document-based CMS, named in tribute to Rosalind Franklin. It transforms content creation by enabling authors to use tools they're already familiar with, like Google Docs and Microsoft Word. Key features include improved speed through serverless architecture, reduced coding requirements, streamlined content creation, and quicker website updates. This results in enhanced user experience, increased efficiency, and reduced costs.

- #eds #overview #introduction

Fundamentals

Architecture

How does Edge Delivery Services differ from traditional AEM?

Unlike traditional CMS, EDS doesn't require dedicated authoring or publishing environments, instead leveraging platforms like Google Drive or SharePoint to create and manage content published directly to edge servers.

Edge Delivery Services differs from traditional AEM in several key ways: 1) Authors use Google/Word docs to create content directly, 2) Components are pre-built and cached at the edge, eliminating wait times, 3) No bundling of JS/CSS is required, 4) It relies on modern JavaScript and CSS without external libraries like jQuery, 5) Pages are controlled through spreadsheets, redirects, and metadata, 6) Paths in Google Drive/SharePoint control page structure, 7) Developers store code in GitHub with no build to deploy, and 8) Each GitHub branch has a separate live preview with zero pipelines and no publishing delay.

- #architecture #comparison #cms

Development

Getting Started

How do I create a simple "Hello World" block in Edge Delivery Services?

Create a folder named "helloworld" in your blocks directory with helloworld.css and helloworld.js files, then add a one-cell table with "helloworld" in your Google document.

To create a "Hello World" block: 1) Create a new folder named "helloworld" in your blocks directory, 2) Create two files inside: helloworld.css and helloworld.js with your styling and functionality, 3) In your Google document, insert a one-cell table and add the text 'helloworld' in the cell. Edge Delivery Services will look in the blocks folder and cell-name folder for similarly named JS and CSS files, applying them to the DOM.

- #blocks #hello-world #getting-started

Development

Blocks

How do blocks work in Edge Delivery Services?

Blocks are components defined by tables in your document, where the first cell contains the block name. EDS uses this to load and execute corresponding CSS and JavaScript files.

In EDS, blocks are components defined by tables in your document. The first cell contains the block name, which signals EDS to load corresponding CSS and JS files from the blocks directory. For example, a table with "columns" in the first cell tells EDS to load /blocks/columns/columns.css and /blocks/columns/columns.js. The JavaScript can then manipulate the DOM to achieve desired styling and functionality. Blocks follow a pattern where the block name becomes a CSS class, and additional classes like "block" are added during the decoration process.

- #blocks #components #development

Development

Block Variations

How can I create variations of blocks in Edge Delivery Services?

Create variations by adding additional names in brackets after the block name, like "Bio (highlighted, hide-author)", which EDS converts to CSS classes.

To create block variations, add additional names in brackets after the block name in your document table. For example, "Bio (highlighted, hide-author)" will add CSS classes "highlighted" and "hide-author" to the block when rendered. These classes can then be targeted in your CSS for styling variations or in JavaScript to modify functionality based on the presence of these classes. This pattern allows content authors to easily mix and match variations without requiring additional code.

- #blocks #variations #customization

Content

Metadata

How do I add metadata to my pages in Edge Delivery Services?

Add a table with "metadata" in the merged first row, then add key-value pairs in subsequent rows with metadata names and values.

To add metadata to your EDS pages, create a table with the first row merged and labeled "metadata". In subsequent rows, use the left column for metadata keys (e.g., "title", "description", "image") and the right column for values. EDS will use this information to generate appropriate meta tags in the HTML output, including Open Graph and Twitter card metadata. The table is typically placed at the bottom of the document but can be positioned anywhere. Case is ignored in the first column, and the values in the second column are used exactly as provided.

- #metadata #seo #content-authoring

Content

Images

How does Edge Delivery Services handle images?

EDS automatically generates responsive images using the HTML picture element with different resolutions and formats (WebP/JPEG) based on device capabilities.

Edge Delivery Services provides advanced image handling using the HTML picture element. When you add an image to your document, EDS automatically creates responsive versions with different resolutions for various screen sizes. It uses media queries to select the appropriate image size and includes format options (WebP/JPEG) based on browser capabilities. Query string modifiers in the URLs control image width, format, and optimization level. EDS also preserves image metadata like alt text and title, which can be utilized in your blocks through JavaScript.

- #images #responsive #optimization

Content

Fragments

How can I reuse content across multiple pages?

Create fragments in a "fragments" folder in Google Drive, then reference them using a fragment block with the path to the fragment.

To reuse content across pages, create a "fragments" folder in your Google Drive and add documents containing the reusable content. Then, in your pages, add a fragment block with the path to the fragment (e.g., "want-to-know-more"). When the page is rendered, EDS fetches the raw HTML of the fragment and includes it in the page, where it inherits the styling and context of the main page. Auto-fragments like headers and footers can be automatically included by placing them in the root folder with names like "nav" and "footer".

- #fragments #reusable-content #content-authoring

Styling

Theming

What are the different ways to style pages in Edge Delivery Services?

There are three main approaches: use default autoblock style, apply a theme through metadata, or create sections with their own styling.

EDS offers three main styling approaches: 1) Default autoblock style: Use styles.css as is without modifications, 2) Themes: Add a theme name to your metadata table (e.g., "article"), which EDS applies as a class to the body element, allowing theme-specific styling, 3) Sections: Divide your page with "---" and add section metadata tables to create distinct sections with their own styling. EDS uses CSS3 with variables for theming and doesn't require bundling, compiling, or transpilation.

- #styling #theming #css #design

Data

Spreadsheets

How can I use spreadsheets with Edge Delivery Services?

Upload spreadsheets to Google Drive or SharePoint, and EDS will automatically convert them to JSON that can be used in your components or pages.

Spreadsheets in EDS serve multiple purposes: 1) As JSON data sources for websites, where the first row becomes JSON attribute names, 2) For notifications of events from EDS using the query-index sheet, 3) For configuration using sheets like headers, redirects, and config. EDS converts spreadsheets to JSON with a standard format where actual data is in the "data" array and metadata includes total, offset, limit, and type. You can use the fetch API in your blocks to retrieve and use this JSON data.

- #spreadsheets #json #data-sources

Data

Query Index

How does the query-index spreadsheet work?

Create a blank query-index spreadsheet in your folder, and EDS will automatically populate it with metadata about published pages, which can be used to create dynamic content.

The query-index spreadsheet acts as a two-way communication tool between EDS and your content. Create a blank sheet named query-index with columns for path, title, image, description, and lastmodified in your Google Drive folder. When you publish pages, EDS automatically populates this sheet with metadata about those pages and publishes it as JSON. You can then use this JSON in your blocks to create dynamic content like blog lists or navigation elements. The sheet provides a complete index of all published content that can be filtered, sorted, and displayed according to your needs.

- #query-index #indexing #dynamic-content

Data

Redirects

How do I set up URL redirects in Edge Delivery Services?

Create a spreadsheet named "redirects" with Source and Destination columns, and EDS will generate redirects.json to handle URL redirection.

To set up redirects in EDS, create a spreadsheet named "redirects" in your Google Drive with two columns: Source and Destination. The Source column contains the original path, and the Destination column contains the new path. When published, EDS creates a redirects.json file that handles URL redirection automatically. This is particularly useful when restructuring your site hierarchy or moving content to new locations while preserving bookmarks and links to the original URLs.

- #redirects #urls #site-structure

Configuration

.helix Folder

What is the .helix folder used for?

The .helix folder contains configuration files for Edge Delivery Services, including headers, config, and other settings that aren't publicly accessible.

The .helix folder (named after a previous code name for EDS) is a special directory that contains configuration files for your EDS project. Files in this folder are not publicly accessible, making it suitable for secrets and configuration. It can contain sheets like "headers" for HTTP headers, "config" for CDN and caching settings, and other configuration options. When you preview a file from this folder, you'll see a "Configuration successfully activated" message instead of a preview, as these settings are applied directly to the EDS environment.

- #configuration #helix #settings

Advanced

SPA Development

How can I build a Single Page Application with Edge Delivery Services?

Create a custom block that uses JavaScript to fetch and display content from multiple documents based on query-index.json data.

To build a SPA with EDS, create a custom block that: 1) Fetches data from query-index.json to get a list of pages, 2) Uses the fetchSlideHtml function to retrieve plain HTML from each page when needed, 3) Creates UI elements for navigation and content display, 4) Implements lazy loading for images and content using Intersection Observer, 5) Handles user interactions like clicking on slides to show detailed content. This approach maintains excellent performance while providing a rich, interactive experience by leveraging EDS's built-in features for content delivery and optimization.

- #spa #javascript #advanced

Advanced

React Integration

How do I integrate React with Edge Delivery Services?

Convert your EDS blocks to React components, build a React application, and deploy the build output to your EDS repository.

To integrate React with EDS: 1) Set up a new React project using Create React App, 2) Break down your EDS block into modular React components (e.g., main container, individual items, panels), 3) Convert the JavaScript logic from your blocks to use React hooks like useState and useEffect, 4) Create separate CSS files for each component, 5) Build the React application and copy the build output (static folder and index.html) to the root of your EDS repository. The React application can use the same data sources as your EDS blocks, like query-index.json, but provides more flexibility for complex interactions.

- #react #javascript #integration

Advanced

GitHub Integration

How can I use GitHub with Edge Delivery Services?

GitHub stores your code and provides fallback JSON files, enabling developer-managed defaults that content authors can override as needed.

GitHub serves as the code repository for your EDS project and can provide fallback JSON files for configurations. By creating matching JSON files in your GitHub repository (e.g., headers.json, config.json), you establish developer-managed defaults. Content authors can then override these defaults by creating corresponding spreadsheets in Google Drive when needed. This fallback system allows developers to maintain control over critical configurations while giving content authors flexibility to make changes without requiring code deployments.

- #github #integration #configuration

AI

AI Development

How can I use AI to assist with Edge Delivery Services development?

Use AI tools like Claude and Cursor.ai with custom training on EDS documentation to generate blocks, components, and applications with minimal manual coding.

To use AI for EDS development: 1) Create a comprehensive context file combining AEM.live documentation, developer guides, and existing repositories, 2) Develop clear rules files with project standards and coding guidelines, 3) Craft detailed prompts for specific tasks, 4) Use tools like Claude (for understanding complex concepts) and Cursor.ai (for code assistance), 5) Implement an iterative process where the AI suggests code, you review it, and then refine your prompts. This approach can significantly accelerate development by automating boilerplate code creation while maintaining human oversight for architecture and implementation decisions.

- #ai #development #automation

Project Setup

Initial Setup

How do I set up a new Edge Delivery Services project?

Create a GitHub repository using the AEM Boilerplate template, install the AEM CLI, configure your content source (Google Drive or SharePoint), and set up the AEM Sidekick extension.

To set up a new EDS project: 1) Create a GitHub repository using the AEM Boilerplate template, 2) Install the AEM CLI globally with npm install -g @adobe/aem-cli, 3) Configure your content source by creating a folder in Google Drive or SharePoint and sharing it with helix@adobe.com, 4) Create an fstab.yaml file in your project root to connect your content source, 5) Install the AEM Sidekick extension and configure it with your project URL. This setup provides the foundation for creating and managing content through familiar tools while leveraging EDS for delivery.

- #setup #project #getting-started

Components

Index Block

How do I create an index navigation for my content?

Add an "index" block to your page, which automatically creates an interactive index of all headers (h1-h6) on the page with clickable links.

The index block is a navigation component that automatically generates a table of contents from your page's heading structure. To implement this component: 1) Create a folder named "index" in your blocks directory with index.css and index.js files, 2) Develop JavaScript that scans the document for all header elements (h1-h6), assigns unique IDs to each header if they don't already have them, and builds a collapsible navigation list, 3) Set up proper indentation based on header levels (h1 headers have no indent, h2 headers are indented once, etc.), 4) Add an expandable/collapsible interface with a clickable arrow, 5) Use event listeners to handle navigation clicks. The index is built using a lazy-loading approach - generating the table of contents only when the user first clicks on the index header - which improves initial page load performance. This component makes longer documents more navigable by providing users with an interactive way to jump directly to specific sections.

- #navigation #index #blocks

Components

Return-to-Top

How can I add a "back to top" button that appears when scrolling?

Implement the "returntotop" block, which creates a button that appears when users scroll down and allows them to smoothly return to the top of the page.

The returntotop block is a navigation aid that adds a button which appears when users scroll beyond 100 pixels from the top of the page and allows them to quickly return to the beginning of the content. To implement this block: 1) Create a "returntotop" folder in your blocks directory with returntotop.css and returntotop.js files, 2) In your Google Doc, add a returntotop block with customizable button text in the second cell, 3) The JavaScript attaches a scroll event listener to show/hide the button and implements smooth scrolling when clicked. This provides a convenient navigation aid for longer pages while remaining hidden when not needed.

- #navigation #usability #blocks

Components

Blog List

How do I create a dynamically generated list of blog posts?

Use the "bloglist" block to fetch and display a filtered, sorted list of posts from your query-index.json data.

The bloglist block creates a responsive grid display of blog posts or articles by dynamically fetching and filtering content from your site's index. To implement this component: 1) Create a folder named "bloglist" in your blocks directory with bloglist.css and bloglist.js files, 2) Develop JavaScript that fetches blog data from query-index.json, 3) Implement filtering logic based on path or other criteria (e.g., only showing posts with "developer-guide" in the path), 4) Add sorting functionality (typically alphabetical by title or chronological by date), 5) Generate HTML with formatted dates, titles, descriptions, and images in a card-based layout. The CSS should use CSS Grid for a responsive layout that adapts to different screen sizes (typically switching to a single column on mobile devices). This block provides an elegant way to showcase related content without manually updating links when new content is published.

- #blogs #dynamic-content #blocks

Components

Code Expander

How can I enhance code examples with copy functionality?

Implement the "code-expander" block to automatically add copy-to-clipboard buttons to all code elements on your page.

The code-expander block is a utility component that automatically enhances all <code> elements on your page with additional functionality. To implement this component: 1) Create a code-expander folder in your blocks directory with code-expander.css and code-expander.js files, 2) Add JavaScript that selects all code elements on the page and wraps them with a container that includes a copy button with a clipboard icon, 3) Implement clipboard functionality using the navigator.clipboard API, 4) Add visual feedback (changing the button text to "Copied!" with a checkmark) when code is successfully copied, 5) Include ARIA attributes for accessibility. Content authors don't need to do anything special - they can continue using the standard <code> element in their content (by applying the Courier font in Google Docs), and the code-expander will automatically enhance these elements without requiring any additional markup. This greatly improves the user experience when sharing code examples or configuration snippets.

- #code #usability #blocks

Development

JavaScript Patterns

What are the recommended JavaScript patterns for EDS blocks?

Use configuration constants at the top of files, implement proper error handling for async functions, and follow clean event handling patterns to prevent memory leaks.

Edge Delivery Services blocks should follow several JavaScript best practices to ensure maintainability and performance. Key recommended patterns include: 1) Configuration Constants: Place all configurable values at the top of your file (e.g., const CONFIG = { ANIMATION_DURATION: 300 }) to improve readability and prevent "magic numbers" scattered throughout the code, 2) ESLint Integration: When debugging with console statements, use // eslint-disable-next-line no-console to avoid linting errors while maintaining good practices, 3) Asynchronous Data Fetching: Implement clean, error-handled async/await functions with try/catch blocks for fetching data, 4) Event Handling: Define handler functions separately for better readability and maintain references for cleanup to prevent memory leaks, 5) DOM Manipulation: Use consistent patterns for updating the UI after data is received. Following these patterns ensures your blocks remain maintainable as your project grows.

- #javascript #patterns #best-practices

Development

CSS Patterns

What are the recommended CSS patterns for EDS blocks?

Use CSS variables for theming, follow standard breakpoints for responsive design, and implement consistent patterns for block variations.

Edge Delivery Services components should follow established CSS best practices to ensure consistent styling and maintainability. Recommended CSS patterns include: 1) CSS Variables for Theming: Define design tokens through CSS variables (e.g., --heading-color: #202020;) at the root level to create consistent, flexible theming that can be easily updated site-wide, 2) Standard Breakpoints: Use consistent min-width media queries (600px, 900px, 1200px) and follow a mobile-first approach, adding complexity for larger screens rather than removing features for smaller ones, 3) Block Variation Pattern: Structure CSS to support variations defined by content authors in document tables (e.g., .blockname.variation1 selectors). This approach ensures visual consistency across the site, simplifies maintenance, and allows content authors to easily mix and match variations without requiring custom code for each combination.

- #css #patterns #responsive

Development

Debugging

How do I debug Edge Delivery Services applications?

Use browser developer tools to inspect DOM changes, monitor network requests, and check console errors; add temporary debug logging with ESLint comments.

Debugging Edge Delivery Services applications requires understanding how EDS transforms documents. Effective debugging techniques include: 1) Compare Raw vs. Processed HTML: Use "View Page Source" to see the raw HTML sent from the server, then compare it with the decorated DOM (using "Inspect Element") after JavaScript processing to understand what changes EDS makes, 2) Network Inspection: Examine network requests to verify CSS and JS files are loading correctly from the blocks directory, 3) Console Debugging: Add temporary console.log statements in your block JavaScript (prefixed with // eslint-disable-next-line no-console to avoid linting errors), 4) DOM Breakpoints: Set DOM change breakpoints in browser developer tools to pause execution when EDS modifies the document structure, 5) CSS Inspection: Use the browser's style inspector to see which CSS rules are being applied and check for any unexpected cascade issues. Understanding the transformation from raw document to decorated DOM is key to effective debugging in EDS.

- #debugging #troubleshooting #development

Performance

Optimization

What are the best practices for optimizing Edge Delivery Services performance?

Implement lazy loading for images, use the E-L-D loading pattern (Eager-Lazy-Delayed), optimize CSS delivery, and minimize JavaScript execution time.

To optimize EDS performance: 1) Implement lazy loading for images using Intersection Observer, 2) Follow the E-L-D loading pattern (Eager for critical content, Lazy for content loaded as users scroll, Delayed for non-essential scripts), 3) Optimize CSS delivery by separating critical CSS (styles.css) from non-critical CSS (lazy-styles.css), 4) Minimize JavaScript execution time by using efficient DOM manipulation and debouncing event listeners, 5) Test performance using Lighthouse in Chrome DevTools to maintain high scores across all metrics (Performance, Accessibility, Best Practices, SEO). These practices help maintain the excellent out-of-the-box performance that EDS provides.

- #performance #optimization #best-practices

Deployment

Publishing

What is the process for deploying and publishing in Edge Delivery Services?

Commit and push changes to GitHub for automatic deployment to the preview environment, then use the AEM Sidekick to publish content changes.

The EDS deployment process is straightforward: 1) Commit and push your code changes to GitHub, 2) EDS automatically builds and deploys your changes to the preview environment, 3) Use the AEM Sidekick to preview and publish content changes from Google Drive or SharePoint, 4) For production deployment, configure your CDN to point to your EDS live environment. This workflow separates code deployment (handled through GitHub) from content publishing (managed through the Sidekick), allowing developers and content authors to work independently.

- #deployment #publishing #workflow