dialog-relations-website/.roo/rules/rules.md

TYPO3 Project Rules for LLM Assistance

Project Overview

This project is a TYPO3 installation with a custom site-package extension located in packages/base, providing layout, templates, and modular ContentBlocks for pages. The LLM should dynamically determine the TYPO3 version and related dependencies by examining project files.

Technology Stack

• PHP (version defined in composer.json)
• TYPO3 (version defined in composer.json)
• Composer (composer.json)
• Deployer (build/deploy.php, build/servers.yaml)
• Webpack (webpack.config.js)
• PostCSS (postcss.config.js) with Tailwind CSS (version defined in package.json) and Autoprefixer
• SCSS (packages/base/Resources/Public/Scss/)
• JavaScript bundling (packages/base/Resources/Public/JavaScript/)
• PHPStan, Rector (phpstan.neon, rector.php)
• YAML and TypoScript for configuration

Project Structure

• config/: Global TYPO3 config and environment overrides
• data/: Database dumps and test fixtures
• packages/base/: Site-package extension with design assets, Fluid templates, TypoScript, ContentBlocks
• public/: Document root
• Build files: webpack.config.js, postcss.config.js
• Dependency manifests: package.json, composer.json

Development Guidelines

• Use DDEV for local environment management: ddev start, ddev restart, ddev stop, etc.
• Check versions in composer.json and package.json before referencing dependencies; the LLM should examine these files to determine actual versions
• Manage PHP dependencies via Composer within DDEV: ddev exec composer install, ddev exec composer update
• Manage JS/CSS via npm within DDEV: ddev exec npm install, ddev exec npm run dev / ddev exec npm run build
• Follow TYPO3 extension conventions in packages/base: ext_localconf.php, ext_tables.php, ext_emconf.php
• Organize TypoScript under packages/base/Configuration/Sets/SitePackage/TypoScript/
• Enforce static analysis and automated refactoring with PHPStan and Rector

Default Workflow

When handling any task, LLMs should follow this structured approach:

1. Information Gathering

   • Read the necessary code from the project using available tools
   • Examine composer.json and package.json to understand current dependencies and versions
   • Use MCP servers to read documentation about libraries that are used and should be used
   • Review relevant project files to understand the current implementation
   • Gather context about the specific area of the codebase that will be affected

2. Planning

   • Analyze the gathered information to understand the task requirements
   • Plan how the task should be implemented within the existing project structure
   • Consider potential impacts on other parts of the codebase
   • Identify which files need to be created, modified, or reviewed
   • Determine the best approach that follows project conventions and best practices

3. Implementation

   • Execute the planned task using appropriate tools
   • Follow the project's coding standards and conventions
   • Test the implementation where possible
   • Ensure all changes work within the existing project structure

4. Documentation Updates

   • Update project documentation (README files) if the task affects user-facing functionality
   • Update these rules (.roo/rules/rules.md) if the task introduces new patterns, conventions, or important information that future LLMs should know
   • Ensure any new features or changes are properly documented for future reference

This workflow ensures thorough understanding, proper planning, clean implementation, and maintained documentation for all project changes.

ContentBlocks Usage

• Defined under packages/base/ContentBlocks/ContentElements/
• Element folder contains:
  • config.yaml (block definition)
  • templates/frontend.html (frontend rendering)
  • templates/backend-preview.html (backend preview)
  • language/labels.xlf (translations)
• To add a new block:
  1. Create a folder under ContentElements/
  2. Define config.yaml and labels
  3. Add Fluid templates in templates/
  4. Clear caches and verify in TYPO3 backend (ddev exec vendor/bin/typo3cms cache:flush)
• Content element restrictions:
  • ContentBlocks are automatically registered via their YAML config files
  • Availability is controlled through PageTSconfig using TCEFORM.tt_content.CType.keepItems
  • The keepItems list in packages/base/Configuration/Sets/SitePackage/page.tsconfig determines which content elements editors can use
  • To enable a new ContentBlock, add its CType to the keepItems list
• Clear caches after changes

Styling Guidelines

• All design work lives in the packages/base extension
• SCSS structure in Resources/Public/Scss/:
  • abstracts/ (variables, mixins, functions)
  • base/ (resets, global styles)
  • components/ (UI modules: buttons, cards, nav, etc.)
  • layouts/ (page-specific styles)
• Include Tailwind directives in main.scss:

  @tailwind base;
  @tailwind components;
  @tailwind utilities;
  

• Customize Tailwind in tailwind.config.js

Build Process

1. Compile SCSS → PostCSS (Tailwind + Autoprefixer) → CSS in Resources/Public/Css/ (within DDEV: ddev exec npm run build:css)
2. Bundle JS via Webpack → Resources/Public/JavaScript/ (within DDEV: ddev exec npm run build:js)
3. Run dev mode: ddev exec npm run dev
4. Run production build: ddev exec npm run build
5. Deploy via Deployer: ddev exec vendor/bin/dep deploy

File Editing Guidelines

• TypoScript: packages/base/Configuration/Sets/SitePackage/TypoScript/
• YAML: packages/base/Configuration/**/*.yaml
• Fluid templates: packages/base/Resources/Private/**/*.html
• SCSS: packages/base/Resources/Public/Scss/**/*.scss
• JavaScript: packages/base/Resources/Public/JavaScript/**/*.js
• Never read or commit the environment file: .env

MCP Server Usage

• Use brave_web_search for general web searches via use_mcp_tool
• Use resolve-library-id + get-library-docs for official API docs:
  • /typo3/docs for TYPO3 reference
  • /tailwindcss for Tailwind CSS docs
• For NixOS/Home Manager queries: use nixos_search, home_manager_search

Version Management

• Always inspect composer.json for PHP dependencies and TYPO3 version
• Always inspect package.json for frontend dependencies
• Use MCP servers (e.g., resolve-library-id, get-library-docs) to fetch documentation matching the exact versions found
• Never assume specific dependency versions in code examples; dynamically reference versions as discovered

Common Tasks

1. Initial Setup

   ddev start
   ddev composer install
   ddev npm install
   

2. Development Build

   ddev npm run dev
   

3. Production Build

   ddev npm run build
   

4. Clear TYPO3 Cache

   ddev typo3cms cache:flush
   

5. Add a ContentBlock
   • Create folder, config, templates, translations
   • Add the new ContentBlock's CType to the keepItems list in packages/base/Configuration/Sets/SitePackage/page.tsconfig
   • Clear caches and verify in backend
6. DDEV Environment Management
   • Restart environment: ddev restart
   • Stop environment: ddev stop
7. Deploy

   ddev exec vendor/bin/dep deploy production
   

Troubleshooting

• Blank CSS/JS: confirm build pipeline ran; check webpack.config.js
• YAML Syntax Errors: validate config.yaml with a linter
• Fluid Rendering Issues: clear caches; verify template paths
• TypoScript Not Loading: ensure correct path under Configuration/Sets
• Cache Problems: always flush caches after changes