Plugin Structure

A plugin should be predictable: its files, templates, assets, and configuration should move cleanly between local development, staging, and production.

Recommended Directories

Directory	Contents
templates/	Twig templates for pages, blocks, and partial components
assets/	CSS, JavaScript, images, and other public files
translations/	Interface text and translations
config/	Local plugin configuration without secrets
docs/	Short setup and verification notes

Manifest

If a plugin is shipped as a separate package, add a description file:

plugin.json

{
  "name": "shop-custom-block",
  "title": "Shop Custom Block",
  "version": "1.0.0",
  "description": "Additional block for the shop page",
  "requires": {
    "platform": ">=1.0.0"
  }
}

The manifest explains the plugin purpose, version, compatibility, and package contents.

Templates

Split templates by purpose:

• pages;
• reusable cards;
• forms;
• loading states;
• empty states;
• error messages.

Do not place large business logic in Twig. If the same data is needed in several places, prepare it at the API or shared function level.

Assets

CSS and JavaScript should be isolated by class names and should not break the base theme. Use clear prefixes so plugin styles do not conflict with system components.

Versioning

Use MAJOR.MINOR.PATCH:

• MAJOR for incompatible changes;
• MINOR for new functionality without breaking existing templates;
• PATCH for fixes.

Before release, state which files changed and what actions are required after update.