WapplerSystems/t3bootstrap-skills
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
t3bootstrap-skills/.agents/skills/t3bootstrap-site-package/SKILL.md
T
wappler af9368177b Initial t3bootstrap-skills plugin: three skills for T3Bootstrap on TYPO3 v14 
- t3bootstrap-site-package: composer + site sets + when to add a local extension
- t3bootstrap-overrides: 4-layer override surface (Settings → SCSS → Fluid → DataProcessor)
- t3bootstrap-content-elements: 23 t3bs_* CE catalog + migration matrix (HTML/WP/Joomla/older TYPO3) + Flux-bs5 upgrade wizard

Mirrors the structure of wapplersystems/typo3-skills (.claude-plugin/{plugin.json,marketplace.json}, .agents/skills/<name>/{SKILL.md,agents/openai.yaml}).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-06-15 09:58:33 +02:00

20 KiB
Raw Permalink Blame History

name, description
name description
t3bootstrap-site-package Set up and configure a TYPO3 v14 project on the T3Bootstrap stack — composer repositories and dependencies for `t3bootstrap/*` and `wapplersystems/*` packages, site configuration with the right Site Sets, multi-language setup, when (and when not) to add a local site package, and the standard set of optional add-on packages (news, blog, address, sliders, gallery, hero, card, counter, countdown). Use this skill when bootstrapping a new T3Bootstrap project, adding a t3bootstrap add-on to an existing project, debugging "set not found" or unexpected content-element-missing errors, or deciding whether a customer-specific extension is needed.

T3Bootstrap Site Package

Use this skill when setting up or extending a TYPO3 v14 project that is built on the T3Bootstrap stack — i.e. uses t3bootstrap/template, t3bootstrap/core and the related WapplerSystems extensions instead of (or in addition to) a hand-rolled site package.

Companion skills:

First Checks

Before adding anything, read what already exists:

  1. Is the project Composer mode? (composer.json at root, vendor/ directory present.)
  2. Which t3bootstrap/* and wapplersystems/* packages are already required? — composer show | grep -E "t3bootstrap|wapplersystems"
  3. Where is the site config? — config/sites/<site-id>/config.yaml. Which sets does its dependencies: list?
  4. Is there a local site package? Look for packages/<vendor>/, local_packages/, or any in-repo TYPO3 extension. On a vanilla T3Bootstrap project there usually is NO local site package — the stack is sufficient out of the box and customization happens via Site Settings + Fluid overrides (see t3bootstrap-overrides).
  5. Is DDEV configured? — .ddev/config.yaml present. Confirm PHP version and the DB engine before suggesting commands.

The Core Stack

A T3Bootstrap project always uses these three foundation extensions:

Package Role
t3bootstrap/core Base ext: ViewHelpers, DataProcessors, BackendLayouts, extended tt_content fields (spacing, background, classes, breakpoint grid), RegisterUtility (TSFE-replacement registry on v14).
t3bootstrap/template Site template: page layouts, navigation, footer, search box, language menu, SCSS theme. Pulls Bootstrap 5 and the icon sets.
t3bootstrap/container-bs5-templates The 23 Bootstrap 5 content elements (Card, Accordion, Tabs, Carousel, Timeline, Grid Row/Col, Megamenu, Buttons, …). Replaces the legacy Flux-based flux_bs5_templates.

These three are mandatory. Everything else is an add-on.

Add-on Packages

All add-ons are optional; pull only what the project needs. Each ships its own Site Set that has to be included in the site config to take effect.

T3Bootstrap-vendored add-ons

Package Adds
t3bootstrap/hero-item Hero content element (full-width banner with title, subtitle, CTA, background image/video).
t3bootstrap/t3bootstrap-news georgringer/news integration with T3Bootstrap-styled list/detail templates.
t3bootstrap/t3bootstrap-blog t3g/blog integration with T3Bootstrap-styled templates.
t3bootstrap/t3bootstrap-address Address record CE styled for the template.
t3bootstrap/t3bootstrap-form EXT:form templates and finishers wired into the template.
t3bootstrap/t3bootstrap-filecollection_gallery File-collection-driven gallery CE.
t3bootstrap/t3bootstrap-wsslider Slider integration for ws_slider.
t3bootstrap/template-fontawesomeicons Font Awesome icon set Site Set.
t3bootstrap/template-bootstrapicons Bootstrap Icons Site Set.
t3bootstrap/template-aos Animate-on-scroll Site Set.
t3bootstrap/template-imagedesigns Image design presets (rounded, framed, shadowed, …).

WapplerSystems shared extensions

Package Adds
wapplersystems/ws-scss SCSS-to-CSS compilation pipeline used by t3bootstrap/template.
wapplersystems/ws-components Modular SCSS/JS component system (<scssComponents:require> / <jsComponents:require>).
wapplersystems/ws-slider Generic slider framework (front-end-library-agnostic).
wapplersystems/font-downloader Self-host Google Fonts.
wapplersystems/teaser Teaser CE.
wapplersystems/videos Video CE.
wapplersystems/testimonials Testimonials CE.
wapplersystems/address Address plugin (news-variant).
wapplersystems/newslayouts Additional news layouts (3-col, 4-col, vertical list, top-image detail, …).
wapplersystems/tag Tagging system.

composer.json — The Repository Block

All T3Bootstrap packages are hosted on the Gitea instance at git.wappler.systems, WapplerSystems packages on GitHub. Both need explicit repositories entries in composer.json (Packagist does not mirror them).

{
  "repositories": [
    { "type": "git", "url": "gitea@git.wappler.systems:T3Bootstrap/core.git" },
    { "type": "git", "url": "gitea@git.wappler.systems:T3Bootstrap/template.git" },
    { "type": "git", "url": "gitea@git.wappler.systems:T3Bootstrap/container-bs5-templates.git" },
    { "type": "git", "url": "gitea@git.wappler.systems:T3Bootstrap/t3bootstrap-news.git" },
    { "type": "git", "url": "gitea@git.wappler.systems:T3Bootstrap/t3bootstrap-blog.git" },
    { "type": "git", "url": "gitea@git.wappler.systems:T3Bootstrap/t3bootstrap-address.git" },
    { "type": "git", "url": "gitea@git.wappler.systems:T3Bootstrap/t3bootstrap-form.git" },
    { "type": "git", "url": "gitea@git.wappler.systems:T3Bootstrap/t3bootstrap-heroitem.git" },
    { "type": "git", "url": "gitea@git.wappler.systems:T3Bootstrap/t3bootstrap-filecollection_gallery.git" },
    { "type": "git", "url": "gitea@git.wappler.systems:T3Bootstrap/t3bootstrap-wsslider.git" },
    { "type": "git", "url": "git@github.com:WapplerSystems/ws_scss.git" },
    { "type": "git", "url": "git@github.com:WapplerSystems/ws-components.git" },
    { "type": "git", "url": "git@github.com:WapplerSystems/teaser.git" },
    { "type": "git", "url": "git@github.com:WapplerSystems/videos.git" },
    { "type": "git", "url": "git@github.com:WapplerSystems/testimonials.git" }
  ]
}

SSH access

The Gitea SSH URL requires the developer machine to be authorized at git.wappler.systems. Inside DDEV containers, run ddev auth ssh on the host beforehand so the agent forwards. HTTPS fallback URL pattern: https://git.wappler.systems/T3Bootstrap/<repo>.git.

Require Block — Version Aliasing

The packages are typically tracked on the release/v14 branch. Use as-aliases so Composer's solver treats the dev branch as a satisfiable version range:

{
  "require": {
    "typo3/cms-core": "^14.0",
    "t3bootstrap/core": "dev-release/v14 as 14.0.0",
    "t3bootstrap/template": "dev-release/v14 as 14.0.0",
    "t3bootstrap/container-bs5-templates": "dev-release/v14 as 14.0.0",
    "t3bootstrap/t3bootstrap-news": "dev-release/v14 as 14.0.0",
    "wapplersystems/ws-scss": "dev-master as 14.0.0",
    "wapplersystems/ws-components": "dev-master as 14.0.0"
  }
}

Stability: add "minimum-stability": "dev" and "prefer-stable": true at the top level — otherwise Composer refuses dev branches.

Site Sets — The Real Configuration Surface

T3Bootstrap configures itself via TYPO3 v14 Site Sets, not by patching TypoScript into the root template. Every t3bootstrap and wapplersystems extension ships one or more sets under Configuration/Sets/<SetName>/config.yaml.

Set Catalog (foundation)

Set Provided by Pulls in
t3bootstrap/core t3bootstrap/core TypoScript constants & setup for the core registry, ViewHelpers, DataProcessors.
t3bootstrap/template t3bootstrap/template Page rendering, layouts, navigation, footer; depends on t3bootstrap/core, t3bootstrap/gridlayouts, typo3/indexed-search.
t3bootstrap/container-bs5-templates t3bootstrap/container-bs5-templates All 23 t3bs_* CTypes; depends on t3bootstrap/core.
t3bootstrap/gridlayouts t3bootstrap/core Grid layouts for text/media elements (CE-internal column splits).

Set Catalog (icons / theming)

Set Provided by Pulls in
t3bootstrap/template-fontawesomeicons t3bootstrap/template Font Awesome assets and link to the icon picker.
t3bootstrap/template-bootstrapicons t3bootstrap/template Bootstrap Icons assets.
t3bootstrap/template-aos t3bootstrap/template animate-on-scroll JS + CSS.
t3bootstrap/template-imagedesigns t3bootstrap/template Image design presets.
t3bootstrap/icons t3bootstrap/core Generic icon registry hooks.

Set Catalog (CE add-ons)

Set Provided by
t3bootstrap/card-element t3bootstrap/core
t3bootstrap/compareslider-element t3bootstrap/core
t3bootstrap/countdown-element t3bootstrap/core
t3bootstrap/counterbar-element t3bootstrap/core
t3bootstrap/hero-item t3bootstrap/hero-item

Set Catalog (news / blog / address / form / gallery)

Set Provided by
t3bootstrap/news t3bootstrap/t3bootstrap-news
t3bootstrap/news-timeline-cards-straight t3bootstrap/t3bootstrap-news
t3bootstrap/news-timeline-cards-alternately t3bootstrap/t3bootstrap-news
t3bootstrap/news-newsblock t3bootstrap/t3bootstrap-news
t3bootstrap/news-background-image-latest t3bootstrap/t3bootstrap-news
t3bootstrap/news-right-image-latest t3bootstrap/t3bootstrap-news
wapplersystems/newslayouts wapplersystems/newslayouts
wapplersystems/newslayouts-detail-topimage wapplersystems/newslayouts
wapplersystems/newslayouts-list-3columns wapplersystems/newslayouts
wapplersystems/newslayouts-list-4columns wapplersystems/newslayouts
wapplersystems/newslayouts-list-vertical wapplersystems/newslayouts
t3bootstrap/blog t3bootstrap/t3bootstrap-blog
t3bootstrap/address t3bootstrap/t3bootstrap-address
wapplersystems/address-googlemaps wapplersystems/address
wapplersystems/address-openstreetmap wapplersystems/address
t3bootstrap/form t3bootstrap/t3bootstrap-form
wapplersystems/filecollection-gallery t3bootstrap/t3bootstrap-filecollection_gallery
wapplersystems/teaser wapplersystems/teaser
wapplersystems/testimonials wapplersystems/testimonials

Set Catalog (sliders)

Set Provided by
wapplersystems/ws-slider wapplersystems/ws-slider
wapplersystems/ws-slider-flexslider wapplersystems/ws-slider
wapplersystems/ws-slider-tinyslider wapplersystems/ws-slider
wapplersystems/ws-slider-swiper wapplersystems/ws-slider
wapplersystems/ws-slider-bootstrap wapplersystems/ws-slider
wapplersystems/ws-slider-slick wapplersystems/ws-slider
t3bootstrap/ws-slider t3bootstrap/t3bootstrap-wsslider (T3Bootstrap-styled wrapper)

A package's PHP code is loaded once Composer pulls it in. Its TypoScript and settings, however, only take effect when the matching Site Set is listed in config/sites/<site-id>/config.yaml — adding the composer dependency without the set means nothing renders.

Site Config — Typical config.yaml

base: 'https://my-project.example.com/'
rootPageId: 1
websiteTitle: 'My Project'

dependencies:
  # foundation — order matters: core → template → CE library
  - t3bootstrap/template            # depends on t3bootstrap/core + gridlayouts
  - t3bootstrap/container-bs5-templates

  # icons & theme add-ons
  - t3bootstrap/template-fontawesomeicons
  - t3bootstrap/template-bootstrapicons
  - t3bootstrap/template-aos
  - t3bootstrap/template-imagedesigns

  # CE add-ons (only what the project needs)
  - t3bootstrap/card-element
  - t3bootstrap/counterbar-element
  - t3bootstrap/countdown-element
  - t3bootstrap/compareslider-element
  - t3bootstrap/hero-item

  # content domains (only what the project needs)
  - t3bootstrap/news
  - t3bootstrap/blog
  - t3bootstrap/address
  - t3bootstrap/form

  # optional vendor add-ons
  - wapplersystems/teaser
  - wapplersystems/testimonials
  - wapplersystems/newslayouts
  - wapplersystems/ws-slider-swiper
  - wapplersystems/filecollection-gallery

  # TYPO3 core sets
  - typo3/felogin
  - typo3/seo-sitemap

languages:
  - title: Deutsch
    enabled: true
    languageId: 0
    base: /de/
    locale: de_DE.utf8
    iso-639-1: de
    hreflang: de
    flag: de
  - title: English
    enabled: true
    languageId: 1
    base: /en/
    locale: en_US.utf8
    iso-639-1: en
    hreflang: en
    fallbackType: strict
    flag: en-us-gb

errorHandling:
  - errorCode: 404
    errorHandler: Page
    errorContentSource: 't3://page?uid=<404-page-uid>'
  - errorCode: 403
    errorHandler: Page
    errorContentSource: 't3://page?uid=<403-page-uid>'
  - errorCode: 500
    errorHandler: Page
    errorContentSource: 't3://page?uid=<500-page-uid>'

routes:
  - route: robots.txt
    type: staticText
    content: |
      User-agent: *
      Disallow: /typo3/
      Disallow: /typo3_src/
      Allow: /typo3/sysext/frontend/Resources/Public/*

Set Dependency Resolution

A set's dependencies: are resolved transitively — listing t3bootstrap/template automatically pulls in t3bootstrap/core and t3bootstrap/gridlayouts. You only need to list the highest-level set you want active.

But: explicit beats transitive for clarity. Listing the foundation sets explicitly makes the config self-documenting and avoids surprises when sets change their deps.

Do You Need a Local Site Package?

The honest answer for most projects: no. The T3Bootstrap stack already provides everything a site package usually wraps:

Site-package responsibility Where it lives in the T3Bootstrap stack
Page rendering / Fluid layouts t3bootstrap/template → override via templateRootPaths.10 (see t3bootstrap-overrides)
Content element templates t3bootstrap/container-bs5-templates + t3bootstrap/core → override via root-paths
Color theme _variables.scss !default overrides (see t3bootstrap-overrides)
Backend layouts shipped by t3bootstrap/template, customer extends via PageTSconfig
Routing site config routeEnhancers
Settings site config settings: + site sets

When you DO need a local extension

Add a customer-specific extension only if any of these is true:

  • Custom PHP — DataProcessors, Middlewares, EventListeners, ViewHelpers, RegisterUtility extensions, Scheduler tasks. PHP must live in a registered extension.
  • Custom Fluid templates that go beyond drop-in overrides — e.g. you want to ship reusable Partials for the customer's brand. (Even drop-in overrides work without an extension if you load them from fileadmin/, but that mixes content storage with code — not recommended.)
  • Custom TCA — fields on tt_content or other tables beyond what t3bootstrap/core already adds.
  • Customer-specific Site Set — settings, additional TypoScript, a backend layout shipped per project. Sets must live in Configuration/Sets/<name>/config.yaml of an extension.

Skeleton for a customer extension

local_packages/<customer>/site_<customer>/
├── composer.json
├── ext_emconf.php
├── Classes/
│   ├── DataProcessing/
│   └── ViewHelpers/
├── Configuration/
│   ├── Sets/
│   │   └── Site<Customer>/
│   │       ├── config.yaml
│   │       ├── settings.yaml
│   │       └── setup.typoscript
│   └── TCA/Overrides/
├── Resources/
│   ├── Private/
│   │   ├── Templates/      # site-package overrides (see t3bootstrap-overrides skill)
│   │   ├── Partials/
│   │   ├── Layouts/
│   │   └── Language/
│   └── Public/
│       └── Scss/_overrides.scss   # !default overrides
└── ext_localconf.php

Register the extension as a path repository in the root composer.json:

{
  "repositories": [
    { "type": "path", "url": "local_packages/<customer>/site_<customer>" }
  ],
  "require": {
    "<customer>/site-<customer>": "@dev"
  }
}

Then add <customer>/site-<customer> to the site config dependencies:.

Common Pitfalls

Symptom Cause Fix
Backend shows no t3bs_* CEs t3bootstrap/container-bs5-templates is required but its Site Set is not listed in config/sites/<id>/config.yaml. Add t3bootstrap/container-bs5-templates to dependencies:.
Frontend renders without styling t3bootstrap/template set missing from dependencies:, or DDEV is serving stale CSS. Verify set is listed, then ddev exec vendor/bin/typo3 cache:flush + recompile SCSS via wapplersystems/ws-scss.
Class "T3Bootstrap\Core\…" not found composer didn't pick up the package — usually missing repositories entry or no dev-release/v14 as alias. Re-check composer.json, run composer require t3bootstrap/core:dev-release/v14.
Set "t3bootstrap/news" not found the matching composer package (t3bootstrap/t3bootstrap-news) is not installed. composer require t3bootstrap/t3bootstrap-news.
News-extension styled wrong wapplersystems/newslayouts listed before t3bootstrap/news so the t3bootstrap templates override the wapplersystems ones. Order matters: T3Bootstrap-news set FIRST, then wapplersystems newslayouts add-ons.
Permission prompt on Gitea SSH inside DDEV DDEV agent isn't forwarded. ddev auth ssh on host before ddev composer install.

Standard Setup Workflow

  1. Scaffold with TYPO3 v14 distribution or a clean Composer install.
  2. Add claude-diagnostics (per global instructions) so the rest is faster to debug.
  3. Add repositories block to composer.json for the Gitea + GitHub URLs of t3bootstrap and wapplersystems packages.
  4. Set stability: minimum-stability: dev, prefer-stable: true.
  5. Require the foundation: t3bootstrap/template, t3bootstrap/container-bs5-templates — t3bootstrap/core comes transitively but list it explicitly if you want pinning.
  6. Require add-ons matching the project brief (news/blog/form/gallery/sliders).
  7. Site config — list the sets matching the requires; add languages, error handling, route enhancers.
  8. Site Setting Module in the TYPO3 backend → verify all sets resolved, no "set not found" errors.
  9. Flush caches, log in, place a "Card" content element to verify t3bs_* CTypes appear.
  10. Decide on overrides — switch to the t3bootstrap-overrides skill once the customer wants color/layout adjustments.

Where to Find Things in the Vendor Tree

vendor/t3bootstrap/core/Configuration/Sets/                # Core sets (gridlayouts, icons, T3BCore)
vendor/t3bootstrap/template/Configuration/Sets/Template/   # Main site template set
vendor/t3bootstrap/template/Configuration/TypoScript/      # TypoScript constants + setup
vendor/t3bootstrap/container-bs5-templates/Configuration/Sets/ContainerBs5Templates/
vendor/t3bootstrap/container-bs5-templates/Classes/Updates/MigrateFluxBs5ToContainerBs5.php

For the override surfaces (templateRootPaths.10, SCSS variables, …) see the t3bootstrap-overrides skill.

For the CE catalog and content-migration mapping see the t3bootstrap-content-elements skill.

Reference in New Issue View Git Blame Copy Permalink