| name | Using the Block Collection and Block Party |
| description | The Block Collection and Block Party are repositories for existing AEM blocks, build tools, code snippets, integration patterns, plugins, and more. Use this skill anytime you are developing something and want to find a reference to use as a starting point. |
Using the Block Collection and Block Party
Overview
This skill helps you find reference implementations, code examples, and patterns from two key AEM Edge Delivery resources:
- Block Collection: Adobe-maintained reference blocks following best practices
- Block Party: Community-driven repository of blocks, plugins, tools, and integrations
Use the provided search scripts to discover relevant examples, then review the code to inform your implementation approach.
When to Use This Skill
Use this skill when:
- Building a new block and want to see if similar implementations exist
- Looking for code patterns or snippets to solve a specific problem
- Searching for integration examples (e.g., third-party services, build tools)
- Need reference implementations for sidekick or Document Authoring plugins
- Want to understand best practices through working examples
Do NOT use this skill when:
- You need official documentation (use
docs-search instead)
- You're making minor CSS tweaks to existing code (just edit directly)
- You already know exactly which block/example you need (use it directly)
Related Skills
- building-blocks: This skill is called from building-blocks during development
- docs-search: Use for official aem.live documentation
- content-driven-development: Use when creating content models for blocks
Key Concepts
Block Collection vs Block Party
Block Collection (Prefer this when available)
Block Party (Use for specialized needs)
When to prefer which:
- Start with Block Collection for standard blocks (carousels, accordions, cards, etc.)
- Use Block Party when Block Collection doesn't have what you need
- Block Party is the only source for sidekick plugins, build tools, and integrations
- Sometimes Block Party has innovative approaches worth considering even if Block Collection has a similar block
How to Use This Skill
Step 1: Identify Search Terms
Determine what you're looking for and identify relevant search terms. Think about similar or alternative names for the functionality.
Examples:
- Looking for FAQ block → search for "faq" AND "accordion" (Block Collection has accordion)
- Looking for image gallery → search for "gallery", "carousel", "slideshow"
- Looking for navigation → search for "navigation", "menu", "header"
- Looking for build tooling → search for "webpack", "vite", "sass", "typescript"
Good search terms:
- Specific functionality names: "carousel", "tabs", "modal"
- Tool names: "sass", "webpack", "target"
- Component types: "navigation", "footer", "hero"
Poor search terms:
- Too generic: "content", "page", "website"
- Too specific: "my-custom-carousel-with-auto-play"
Step 2: Search Block Collection
Execute the Block Collection search script from the project root:
node .claude/skills/block-collection-and-party/scripts/search-block-collection.js <search-term>
Examples:
node .claude/skills/block-collection-and-party/scripts/search-block-collection.js accordion
node .claude/skills/block-collection-and-party/scripts/search-block-collection.js carousel
node .claude/skills/block-collection-and-party/scripts/search-block-collection.js header
Step 3: Search Block Party
Execute the Block Party search script from the project root:
node .claude/skills/block-collection-and-party/scripts/search-block-party.js [--category <category>] <search-term> [additional-terms...]
Options:
--category <category>: Filter by specific category (Block, Sidekick Plugin, DA Plugin, Code Snippet, Build Tooling, etc.)- Without
--category: Searches all categories
Examples:
node .claude/skills/block-collection-and-party/scripts/search-block-party.js breadcrumb
node .claude/skills/block-collection-and-party/scripts/search-block-party.js sass
node .claude/skills/block-collection-and-party/scripts/search-block-party.js --category "Build Tooling" webpack
node .claude/skills/block-collection-and-party/scripts/search-block-party.js adobe target integration
Step 4: Review Search Results
Block Collection Results (type: "block"):
{
"query": "accordion",
"source": "Adobe AEM Block Collection",
"totalItems": 26,
"matchCount": 1,
"results": [
{
"name": "accordion",
"displayName": "Accordion",
"type": "block",
"liveExampleUrl": "https://main--aem-block-collection--adobe.aem.live/block-collection/accordion",
"jsUrl": "https://github.com/adobe/aem-block-collection/blob/main/blocks/accordion/accordion.js",
"cssUrl": "https://github.com/adobe/aem-block-collection/blob/main/blocks/accordion/accordion.css"
}
]
}
Block Collection Results (type: "default-content"):
{
"query": "breadcrumb",
"source": "Adobe AEM Block Collection",
"totalItems": 26,
"matchCount": 1,
"results": [
{
"name": "breadcrumbs",
"displayName": "Breadcrumbs",
"type": "default-content",
"liveExampleUrl": "https://main--aem-block-collection--adobe.aem.live/block-collection/breadcrumbs",
"note": "This is default content documentation, not a standalone block. Code may be part of other blocks (e.g., breadcrumbs are in the header block). Visit https://www.aem.live/developer/block-collection and the live example URL for implementation guidance.",
"documentationUrl": "https://www.aem.live/developer/block-collection"
}
]
}
Block Party Results:
{
"query": "breadcrumb",
"category": "All categories",
"source": "AEM Block Party (Approved Only)",
"totalEntries": 90,
"approvedEntries": 62,
"matchCount": 1,
"results": [
{
"title": "Breadcrumbs",
"category": "Block",
"description": "A breadcrumb navigation component...",
"githubUrl": "https://github.com/...",
"showcaseUrl": "https://...",
"githubProfile": "https://github.com/..."
}
]
}
Step 5: Examine the Code
Use the provided URLs to review the implementation:
For Block Collection results with type: "block":
- Read the JS file to understand decoration logic
- Read the CSS file to see styling approach
- Visit the live example URL to see the block in action and understand the content model
For Block Collection results with type: "default-content":
- These represent standard HTML elements and patterns (breadcrumbs, buttons, headings, etc.)
- Code exists but may be part of other blocks (e.g., breadcrumbs code is in the header block)
- Visit the
documentationUrl (https://www.aem.live/developer/block-collection) to find implementation details
- Visit the
liveExampleUrl to see examples and understand how to author the content
- Search the Block Collection repository for related blocks that might contain the implementation
For Block Party entries:
- Visit the GitHub URL to see the code
- Visit the showcase URL to see it in action (if available)
- Review the description to understand the purpose and approach
Step 6: Apply Learnings
Use the reference implementations to inform your approach:
- Understand the content model used
- Study decoration patterns and techniques
- Review CSS architecture and responsive approaches
- Adapt (don't copy) the code to fit your specific needs
- Ensure you follow your project's coding standards
Search Behavior Details
Block Collection Search
- Searches block folder names in the GitHub repository
- Returns exact and partial matches (case-insensitive)
- Provides direct links to JS, CSS, and live examples
- Fast and reliable (limited to ~16 blocks)
Block Party Search
- Searches title, description, and category fields
- Supports category filtering
- Returns all matching entries (not limited)
- Shows approval status for each entry
- Includes diverse content types beyond blocks
Examples
Example 1: Building an FAQ Block
User Request: "I need to build an FAQ section with expandable questions"
Good Approach:
- Recognize FAQ often uses accordion pattern
- Search Block Collection:
node .claude/skills/block-collection-and-party/scripts/search-block-collection.js accordion
- Find the accordion block with JS, CSS, and live example URLs
- Review the implementation approach
- Adapt the pattern to your specific FAQ needs
Why this works:
- Used alternative term "accordion" for "FAQ"
- Started with Block Collection (Adobe best practices)
- Found a vetted, accessible, performant implementation
Example 2: Finding Breadcrumb Implementation
User Request: "Add breadcrumb navigation to the site"
Good Approach:
- Search Block Collection first:
node .claude/skills/block-collection-and-party/scripts/search-block-collection.js breadcrumb
- No results in Block Collection
- Search Block Party:
node .claude/skills/block-collection-and-party/scripts/search-block-party.js breadcrumb
- Find breadcrumb block in Block Party
- Review the implementation, noting it's community-contributed
- Evaluate if it meets your needs or needs adaptation
Why this works:
- Checked Block Collection first (best practices)
- Fell back to Block Party when BC didn't have it
- Aware that Block Party code may need more review
Example 3: Integrating Sass
User Request: "Can we use Sass for our styles instead of plain CSS?"
Good Approach:
- Recognize this is a build tooling question (not a block)
- Skip Block Collection (doesn't have build tools)
- Search Block Party:
node .claude/skills/block-collection-and-party/scripts/search-block-party.js --category "Build Tooling" sass
- Find Sass integration examples
- Review the approach and adapt to your project
Why this works:
- Recognized Block Party is the right resource for build tools
- Used category filter to narrow results
- Found community examples of the integration
Example 4: Multiple Implementations Exist
User Request: "Build a carousel for product images"
Scenario: Both Block Collection and Block Party have carousel implementations
Good Approach:
- Search Block Collection:
node .claude/skills/block-collection-and-party/scripts/search-block-collection.js carousel
- Find Block Collection carousel
- Also search Block Party:
node .claude/skills/block-collection-and-party/scripts/search-block-party.js carousel
- Find multiple Block Party carousels
- Prefer Block Collection for best practices
- Review Block Party versions to see if they have innovative features worth considering
- Make informed decision based on requirements
Why this works:
- Searched both resources to see all options
- Defaulted to Block Collection (Adobe vetted)
- Considered Block Party for potential innovations
- Made an informed decision rather than blindly copying
Important Reminders
- Always search for alternative names - "FAQ" = "accordion", "slideshow" = "carousel"
- Prefer Block Collection when available - it's vetted for quality and best practices
- Use Block Party for specialized needs - it has broader variety but needs more evaluation
- Don't copy blindly - understand the code and adapt it to your project
- Review content models carefully - how authors structure content is critical
- Check accessibility and performance - especially for Block Party code
- Search both resources - sometimes both have implementations with different trade-offs
- Category matters for Block Party - use filters when you know what type you need
Common Search Patterns
| Need | Block Collection Search | Block Party Search |
|---|
| FAQ section | accordion | faq, accordion |
| Image gallery | carousel | gallery, carousel, slideshow |
| Tabbed content | tabs | tabs, tabbed |
| Navigation | header | navigation, menu, header |
| Footer | footer | footer |
| Product cards | cards | cards, product |
| Video embed | video, embed | video, embed, youtube |
| Build tools | N/A | Use --category "Build Tooling" |
| Sidekick plugins | N/A | Use --category "Sidekick Plugin" |
| Integrations | N/A | Search for service name (e.g., target, analytics) |
Troubleshooting
No results in Block Collection:
- Try alternative terms
- Fall back to Block Party
- Consider building from scratch with guidance from
building-blocks skill
Too many results in Block Party:
- Use
--category to filter
- Refine search terms to be more specific
- Review descriptions to find best matches
Found code but seems outdated:
- Check Block Collection for newer patterns
- Review official docs with
docs-search skill
- Consider using as inspiration but implementing with modern approaches
Multiple implementations, unsure which to use:
- Prefer Block Collection for standard functionality
- Choose Block Party for specialized or innovative features
- Consider your specific requirements (performance, accessibility, features)
- Review code quality and documentation before deciding
