t3bootstrap-skills/.agents/skills/t3bootstrap-site-package/SKILL.md

---
name: t3bootstrap-site-package
description: 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:**
> - [`t3bootstrap-overrides`](../t3bootstrap-overrides/SKILL.md) once setup is done and customer styling/templating begins.
> - [`t3bootstrap-content-elements`](../t3bootstrap-content-elements/SKILL.md) for which CE to use where.

## 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).

```json
{
  "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:

```json
{
  "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`

```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

```text
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`:

```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

```text
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.