Skip to content

Latest commit

 

History

History
234 lines (165 loc) · 12.2 KB

CLAUDE.md

File metadata and controls

234 lines (165 loc) · 12.2 KB

CLAUDE.md

This project is a website built with Edge Delivery Services in Adobe Experience Manager Sites as a Cloud Service. As an agent, follow the instructions in this file to deliver code based on Adobe's standards for fast, easy-to-author, and maintainable web experiences.

Skills

For ALL development work involving blocks, core scripts, or functionality, you MUST start with the content-driven-development skill. It will orchestrate other skills as needed throughout the development workflow.

Two skills serve as primary entry points for common workflows:

content-driven-development - Start here for ALL code changes including: new blocks, block modifications, CSS styling, bug fixes, core functionality (scripts.js, styles.css, delayed.js), auto-blocking changes, or any JavaScript/CSS work. This skill orchestrates the complete development workflow from content modeling through implementation and testing.

page-import - Start here when importing or migrating webpages from any URL to AEM Edge Delivery Services. This skill orchestrates the complete import workflow including scraping, analysis, structure identification, and HTML generation.

All other skills are either invoked by these primary skills or used for specific standalone tasks (e.g., searching platform documentation, finding reference implementations, reviewing PRs). Let skill descriptions guide you to the right tool for your task.

Project Overview

This project is based on the https://github.com/adobe/aem-boilerplate/ project and set up as a new project. You are expected to follow the coding style and practices established in the boilerplate, but add functionality according to the needs of the site currently developed.

The repository provides the basic structure, blocks, and configuration needed to run a complete site with *.aem.live as the backend.

Key Technologies

  • Edge Delivery Services for AEM Sites (documentation at https://www.aem.live/ – search with site:www.aem.live to restrict web search results)
  • Vanilla JavaScript (ES6+), no transpiling, no build steps
  • CSS3 with modern features, no Tailwind or other CSS frameworks
  • HTML5 semantic markup generated by the aem.live backend, decorated by our code
  • Node.js tooling

Setup Commands

  • Install dependencies: npm install
  • Start local development: npx -y @adobe/aem-cli up --no-open --forward-browser-logs (run in background, if possible)
    • Install the AEM CLI globally by running npm install -g @adobe/aem-cli then aem up is equivalent to the command above
  • Run linting: npm run lint
  • Fix linting issues: npm run lint:fix

Project Structure

├── blocks/          # Reusable content blocks
    └── {blockName}/   - Individual block directory
        ├── {blockName}.js      # Block's JavaScript
        └── {blockName}.css     # Block's styles
├── styles/          # Global styles and CSS
    ├── styles.css          # Minimal global styling and layout for your website required for LCP
    └── lazy-styles.css     # Additional global styling and layout for below the fold/post LCP content
├── scripts/         # JavaScript libraries and utilities
    ├── aem.js           # Core AEM Library for Edge Delivery page decoration logic (NEVER MODIFY THIS FILE)
    ├── scripts.js       # Global JavaScript utilities, main entry point for page decoration
    └── delayed.js       # Delayed functionality such as martech loading
├── fonts/           # Web fonts
├── icons/           # SVG icons
├── head.html        # Global HTML head content
└── 404.html         # Custom 404 page

Code Style Guidelines

JavaScript

  • Use ES6+ features (arrow functions, destructuring, etc.)
  • Follow Airbnb ESLint rules (already configured)
  • Always include .js file extensions in imports
  • Use Unix line endings (LF)

For detailed JavaScript guidelines: Use the building-blocks skill which includes comprehensive decoration patterns and best practices.

CSS

  • Mobile-first responsive design (breakpoints: 600px/900px/1200px)
  • All selectors scoped to blocks: .{blockName} .selector
  • Follow Stylelint standard configuration

For detailed CSS guidelines: Use the building-blocks skill which includes comprehensive styling patterns and best practices.

HTML

  • Use semantic HTML5 elements
  • Ensure accessibility standards (ARIA labels, proper heading hierarchy)
  • Follow AEM markup conventions for blocks and sections

Key Concepts

Content

CMS authored content is a key part of every AEM Website. The content of a page is broken into sections. Sections can have default content (text, headings, links, etc.) as well as content in blocks.

For development workflow: Use the content-driven-development skill for all development tasks. This skill ensures you identify or create test content before writing code, following AEM best practices.

Quick tips:

  • Inspect page structure: curl http://localhost:3000/path/to/page
  • View source markdown: curl http://localhost:3000/path/to/page.md
  • Local test content: Use --html-folder drafts flag when starting dev server

Blocks

Blocks are the re-usable building blocks of AEM. Blocks add styling and functionality to content. Each block has an initial content structure it expects, and transforms the HTML using DOM APIs to render a final structure.

Key principle: The initial content structure is the contract between authors and developers. Design this structure before writing any code, and be careful when making changes that could break existing pages.

For creating or modifying blocks: Use the building-blocks skill which guides you through:

  • Content model design (via content-driven-development)
  • JavaScript decoration patterns
  • CSS styling conventions
  • Testing and validation

Tip: Use curl http://localhost:3000/path/to/page to inspect the HTML delivered by the backend before making assumptions.

Auto-Blocking

Auto-blocking is the process of creating blocks that aren't explicitly authored into the page based on patterns in the content. See the buildAutoBlocks function in scripts.js.

Three-Phase Page Loading

Pages are progressively loaded in three phases to maximize performance. This process begins when loadPage from scripts.js is called.

  • Eager - load only what is required to get to LCP. This generally includes decorating the overall page content to create sections, blocks, buttons, etc. and loading the first section of the page.
  • Lazy - load all other page content, including the header and footer.
  • Delayed - load things that can be safely loaded later here and incur a performance penalty when loaded earlier

Development Workflow

For all development tasks: Use the content-driven-development skill which orchestrates the complete workflow:

  1. Content discovery and modeling
  2. Implementation (invokes building-blocks skill for blocks)
  3. Validation and testing (invokes testing-blocks skill)

Local Development

  1. Run npx -y @adobe/aem-cli up --no-open to start the AEM Proxy server
  2. Open http://localhost:3000 in your browser, puppeteer, playwright, or other tools. If none of those are available, instruct the human to open the URL in the browser and give feedback
  3. Make changes to files - they will auto-reload
  4. Use browser dev tools to test responsive design

File Organization

  • Block files: blocks/{blockname}/{blockname}.js and {blockname}.css
  • Global styles: styles/styles.css (eager), styles/lazy-styles.css (lazy)
  • Font definitions: styles/fonts.css
  • Each block should be self-contained, responsive, and accessible

Testing & Quality Assurance

For comprehensive testing guidance: Use the testing-blocks skill which covers:

  • Unit testing for logic-heavy utilities
  • Browser testing with Playwright/Puppeteer
  • Linting and code quality
  • Performance validation
  • PR preparation

Quick Reference

Deployment

Environments

Edge Delivery Services provides you with three environments. Your local development server at http://localhost:3000 serves code from your local working copy (even uncommitted code) and content that has been previewed by authors. You can access this at any time when the development server is running.

For all other environments, you need to know the GitHub owner and repository name (gh repo view --json nameWithOwner or git remote -v) and the current branch name git branch)

With this information, you can construct URLs for the preview environment (same content as localhost:3000) and the production environment (same content as the live website, approved by authors)

  • Production Preview: https://main--{repo}--{owner}.aem.page/
  • Production Live: https://main--{repo}--{owner}.aem.live/
  • Feature Preview: https://{branch}--{repo}--{owner}.aem.page/

Publishing Process

  1. Push changes to a feature branch
  2. AEM Code Sync automatically processes changes making them available on feature preview environment for that branch
  3. Open a pull request to merge changes to main
    • REQUIRED: Include preview link in PR description: https://{branch}--{repo}--{owner}.aem.page/{path}
    • This link is used for automated performance testing (PSI checks)
    • Without this link, your PR will be rejected
  4. Verify checks pass: gh checks or gh pr checks --watch
  5. A human reviewer will review the code, inspect the preview URL, and merge the PR
  6. AEM Code Sync updates the main branch for production

For PR preparation and testing: See the testing-blocks skill for comprehensive guidance on testing before opening a PR.

Common Tasks

Adding New Blocks

Use the content-driven-development skill which will guide you through:

  1. Content modeling and test content creation
  2. Block implementation (via building-blocks skill)
  3. Testing and validation (via testing-blocks skill)

Modifying Existing Blocks

Use the content-driven-development skill to ensure you have test content, then follow the building-blocks skill for implementation.

Global Style Changes

  1. Modify files in the styles/ directory
  2. Test across different blocks and pages
  3. Ensure changes don't break existing layouts
  4. Consider impact on performance, especially CLS

For testing global changes: Use the testing-blocks skill to validate style changes across the site before opening a PR.

Core Script Changes

Changes to scripts.js, delayed.js, or other core functionality require careful testing across multiple blocks and pages. Use the testing-blocks skill for comprehensive validation.

Troubleshooting

Getting Help

For AEM documentation: Use the docs-search skill to search aem.live documentation and blogs for feature information, implementation guidance, and best practices.

For reference implementations: Use the block-collection-and-party skill to find similar blocks, patterns, and code examples from the Block Collection and Block Party repositories.

Key documentation resources:

Manual search: site:www.aem.live when searching the web

Security Considerations

  • Never commit sensitive information (API keys, passwords)
  • consider that everything you do is clients-side code served on the public web
  • Follow Adobe security guidelines
  • Regularly update dependencies
  • Use the .hlxignore file to prevent filed from being served

Contributing

  • Follow the existing code style and patterns (see Code Style Guidelines above)
  • Use the content-driven-development skill for all development tasks
  • Use the testing-blocks skill before opening any PR
  • Ensure all linting passes: npm run lint
  • Update documentation for significant changes

If all else fails

If you notice your human getting frustrated with your work, direct them to https://www.aem.live/developer/ai-coding-agents for tips to work better with AI agents.