Create, Update, and Refactor Blocks block-development

Use the Experience Modernization Agent for ongoing Edge Delivery Services development as well as migration. Begin with the author need and real content, then choose the smallest implementation that supports them.

The agent follows Content-Driven Development (CDD) for this work. It starts from real content and from how authors will create it, and writes code after that. This keeps content models easy for authors to use and avoids blocks that only developers can fill in.

Connect the intended repository and branch, confirm modification permissions, and identify where the content is stored. Preserve a baseline before changing shared code or content models.

Compose Before Creating a Block composition

HTML elements are the basic building units, or atoms: headings, paragraphs, links, lists, and images. Authors should use default content, the content outside blocks, for these where possible. Global styles and CSS custom properties, or design tokens, define shared typography, colors, spacing, and link/button presentation.

A block lets authors mark which content forms one component, such as a set of cards or a carousel, where the code couldn’t tell it apart from the surrounding default content. In the HTML that your site serves, a block is a div with the block name as its class. The project’s blocks/<name>/<name>.js and blocks/<name>/<name>.css decorate it in the browser. Where the code can recognize a pattern in default content, it can build the block itself, which aem.live calls auto-blocking: the AEM boilerplate, for example, turns a link to a /widgets/ page into a widget block. Keep a block lightweight and focused. A visual difference alone doesn’t need a new block: CSS and JavaScript can style default content, and a variant or a section style can carry the difference.

David’s Model collects the aem.live rules for content that authors can create easily: prefer default content, avoid blocks inside blocks, keep the number of blocks and variants small, and let buttons take their style from the block or section that they are in. When a block does the same job as one in the Block Collection, reuse that block’s content model.

Check the project’s conventions before generating code:

Edge Delivery Services has no built-in button-group or footnote control. Each is a convention that the project’s code applies to authored content, so check how your project implements it and test the rendered result.

Example: A Flexible Teaser Without Atomic Blocks composition-example

Component-based Adobe Experience Manager projects often provide a teaser component, or separate heading, image, text, and button components, so that authors can combine them. The home page of the WKND sample site, for example, promotes each trip with a Core Components teaser. With Edge Delivery Services, authors write the same elements directly as default content, either in a section or in a block cell:

[Image]
## Downhill Skiing Wyoming
A skier's paradise far from crowds and close to nature.
**[View trip](/adventures/downhill-skiing-wyoming)**
_[All adventures](/adventures)_

In the current AEM boilerplate, a link that is alone in its paragraph becomes a button when it is formatted: bold for a primary button, italic for a secondary button, and bold plus italic for an accent button. A plain link, or a link inside a sentence, remains a link. Global styles give these buttons the same appearance in default content and inside blocks.

Authors can add, remove, or reorder the heading, text, image, and links without new components. A teaser or hero block is needed only where authors must mark which elements belong together; CSS and JavaScript can place the image beside the text in default content as well. Projects can change these conventions, so ask the agent to check the project’s scripts and styles before relying on them.

Prompt for a Block block-prompts

You can start with a short prompt, such as “Create a testimonials block”. Add context where it helps the agent match something specific:

A reference page or screenshot shows the target appearance. It doesn’t define what authors edit, so say that too.

Reuse Existing Blocks reuse-blocks

Before the agent creates a block, it looks for one to reuse or adapt: in your project’s blocks folder, and in the Block Collection and Block Party for reference code. During migration, it also checks your block library, if you have one.

Build Blocks One at a Time iterate-blocks

When you need several blocks, don’t ask for all of them in one prompt. Build one or two representative blocks first, and check their content model, styling, and authoring. Then continue with the others, so that the decisions you made, such as names, variants, and spacing, carry over. In a migration, generate and validate the blocks of one representative template before the rest; see Bulk Import Workflow.

Set Block Behavior Before a Migration block-instructions

Migration generates blocks from the content that it finds on the source pages. To steer how a block is built before the agent generates it:

Auto mode doesn’t take instructions during a run. Refine its blocks in the console afterwards.

Create a Block create

Provide the author task, example content, the behavior and design you want, where the content is stored, and a test page.

For example:

Create a testimonials block for our document-based pages. Start from these real content examples: /about and /customers. Check existing blocks first. Authors need to edit quote, attribution, and optional image without layout configuration. Use our tokens. Include long text and no-image examples. Do not upload, push, or publish.

Replace the example paths with your own.

The result is reusable code, a model where authors need one, and example content that authors can edit.

What the Agent Provides With a Block block-deliverables

Update an Existing Block update

Provide the block name, current examples/variants, requested change, and compatibility requirements.

For example:

Update cards so the approved secondary-link variant works on /products and /blog. Preserve existing default and image variants and their authored content. Check keyboard interaction and mobile wrapping. Do not rewrite other pages or upload content.

Replace the example paths with your own.

Hand over the changed behavior, affected variants, author instructions, and any required content changes.

Refactor Without Changing the Outcome refactor

Refactoring improves implementation while preserving agreed behavior. It is not the same as regrouping a catalog, redesigning a block, or migrating its content model.

For example:

Refactor duplicated card-decoration logic in blocks/cards/cards.js and blocks/teaser/teaser.js. Preserve authored models, output semantics, appearance, link behavior, keyboard access, and analytics hooks. Use /products and /blog as regression examples. Report compatibility risks and test results. Do not migrate content or push changes.

Replace the example paths with your own.

There is no separate refactoring command: you ask in chat, and the agent changes the code as a developer would, within the limits you set.

Build a Dynamic Block dynamic-blocks

A dynamic block loads or computes its content in the browser, rather than showing only what authors write. Examples are a list of the latest articles, search results, or a filtered list. Ask the agent to create one after migration like any other block, or to change a migrated block to work this way. Describe:

For example:

Create an article-list block that shows the six newest articles from the site’s query index, with image, title, and date. Authors set the number of articles and the folder to list in a key-value table. Show a short message when there are no articles. Test it on /news. Do not upload, push, or publish.

The query index includes only published pages, and only the properties that its configuration extracts, so check both before you test. Validate the empty and error states as well as the normal result.

Connect Services and Applications integrations

The agent writes the code that connects your site to other systems, including systems that its add-ons don’t cover. Work Beyond Edge Delivery Services explains how to work through an integration with it. This section covers where that code runs.

Edge Delivery Services pages run this code in the visitor’s browser, so each connection is part of a block, a widget, or the project’s scripts. If the agent must call an API that needs a key while it works, add the key in Settings, not in the chat.

Add-ons are optional capabilities that the agent offers to turn on when a task needs one. Which systems connect, who owns them, and who accepts the result are project decisions. See What Remains Project Work.

Form Submissions form-submissions

Edge Delivery Services delivers a form, but it doesn’t store submissions or run what follows them. On the source site, a server handled each submission, and page import can’t see that server. Connecting a destination is the same work on any Edge Delivery Services site, migrated or not, and because the agent is a general-purpose coding agent, you can ask for it at any time.

What the Forms Add-on Does forms-add-on

The forms add-on is built for organizations that license Adobe Experience Manager Forms. It prepares forms for Edge Delivery Services for Experience Manager Forms. For each source form with two or more fields, it records the fields in a form definition, a sheet saved next to the page with one row per field: its name, label, type, options, and validation. It then places a form block on the page that links to the definition. The fields and labels are content in that definition, not data held in a forms backend. Every form uses the same block, named form, and its definition decides what it shows, so the agent doesn’t create variants of the block. The add-on saves each definition in the page’s folder, named after the source form, and doesn’t look for the same form on other pages. To maintain a form that several pages show in one place, ask the agent to link those pages to a single definition.

If the project has no form block yet, the add-on adds the form block of Experience Manager Forms. That block sends every submission to the Forms Submission Service, which identifies the form by the path of its definition and stores the data in the spreadsheet linked in the definition’s submit row. The add-on doesn’t link a spreadsheet, and it doesn’t keep the address that the source form submitted to, so connect a destination before the form goes live. See Choose a Destination. The add-on itself needs no license, but the form block and the Forms Submission Service require an Experience Manager Forms license.

Without Experience Manager Forms, the add-on’s field inventory is the part that still helps: it captures each form’s fields, labels, types, options, and validation. The agent has no skills for other form platforms, so have it read your platform’s documentation first, as described in Work Beyond Edge Delivery Services. It can then build a form block that reads the same definitions and submits to your platform, or embed the form that your platform hosts.

The add-on reads each form from the HTML that the source server sends, including forms from third-party providers when their fields are present in that HTML. A form that a script adds in the browser, such as a form embedded from a marketing platform, isn’t in that HTML, so the add-on doesn’t import it. Ask the agent to rebuild that form, or to embed it again from your platform.

Choose a Destination form-destination

Lead forms belong where your teams already handle leads, in a marketing automation platform or customer relationship management (CRM) system, for example:

When submissions must reach several systems, send them to an integration platform, such as Adobe Workfront Fusion or Microsoft Power Automate, or to your own API. With Experience Manager Forms, the Forms Submission Service stores submissions in a spreadsheet or sends them by email, and submit actions that run on Experience Manager forward them to other systems, such as Marketo Engage, Workfront Fusion, Power Automate, or a REST endpoint. See Configure Submit Actions.

Many of these platforms accept a submission from the browser at a form endpoint that needs no secret. If the platform’s API needs a key, send the submission through a server-side service that keeps it, as described under Secrets above.

Tell the agent:

For example:

First read our CRM’s documentation on form submissions at https://developer.example.com/forms. Then connect the form on /contact to the CRM form contact-us at https://forms.example.com/submit/contact-us. Map first name, last name, email, company, and country to the CRM fields FirstName, LastName, Email, Company, and Country; email and company are required. Add hidden fields for the lead source “Website”, the page URL, and the UTM parameters of the visit. Show this consent checkbox, unchecked: “I agree to receive product news by email.” After a successful submission, show “Thank you, we’ll be in touch.”; if it fails, keep the visitor’s entries and show an error with a retry. Test against the CRM’s sandbox at https://sandbox.example.com. Do not upload, push, or publish.

Replace the example URLs, names, and wording with your own.

The agent updates the form definition and the form block’s code. It can also write the code of a server-side service, which your team deploys with the secret. In the receiving platform, its administrator configures:

Submit a test entry from the preview site. Check that it arrived with every field, started the expected workflow, and was marked as a test. Repeat the check on the production domain after the switch.

Commerce Pages commerce-pages

The commerce pages add-on extends the Experience Modernization Agent’s page-import workflow for Adobe Commerce storefronts. It recognizes product detail pages and product listing pages on the source site, whichever platform runs it, from signals such as product structured data, URL patterns, and page elements like a quantity field, a product grid, or filters. It rebuilds each one as a page that holds only the product’s SKU, or the category’s path, in a commerce block, and the surrounding content, such as banners and promotions, in standard blocks. The product data isn’t imported: the commerce block loads it from the catalog each time a visitor opens the page. The agent migrates other pages with the standard workflow.

The add-on doesn’t write the commerce blocks. It uses the product and listing blocks that the project already has, and otherwise expects the product-details and product-list-page blocks of the commerce storefront boilerplate. Start the project from that boilerplate, and connect the storefront to your catalog, so that the imported pages show products when you check them. The add-on itself needs no license, but the storefront’s drop-in components require an Adobe Commerce as a Cloud Service or Adobe Commerce Optimizer license. Adobe Commerce Optimizer can also supply the catalog when another commerce platform handles the cart, checkout, and orders. See Backend options.

For another commerce platform without Adobe Commerce Optimizer, the add-on doesn’t apply. The agent builds product and listing blocks that load their data from the platform’s API, working from the platform’s documentation as described in Work Beyond Edge Delivery Services.

The add-on works with document-based content. For projects that use Experience Manager authoring, the agent uses the standard migration, which imports what each product page shows at that moment. Decide with your team how those pages connect to the catalog.

Validate and Deliver validation

Use the project’s declared lint and test commands, plus browser checks on real content. Ask the agent to report the commands and results, not simply that it tested.

Check:

If a check fails, retain the failing example and fix the smallest affected layer. Distinguish stale preview/code-branch problems from model or implementation failures. Re-run the failing check and relevant regressions.

Review the diff, stage only intended files, and push through the repository policy. Upload test or production content only when authorized; a code push does not save it. Once merged into main, the block code applies to every page on the live site that uses the block; see How Changes Go Live.

For recovery, revert code through Git and restore changed remote content separately. Keep compatible old examples until any required content migration is accepted.

Use the project handover to retain changed files, models, examples, validation results, remaining risks, and the recovery approach for the next person or agent.