Zum Hauptinhalt springen
t3headless
DEVELOPER DOCUMENTATION HUB TYPO3 v13 / v14

T3Headless Dokumentation & Kurzanleitung.

Die wichtigsten Schritte aus unserem offiziellen Benutzerhandbuch: TYPO3-Installation per Composer, YAML API-Konfiguration, Next.js Frontend-Setup und React-Template-Konventionen.

01 / TYPO3 INSTALLATION

Extension-Installation & Basiskonfiguration

Installieren Sie EXT:t3headless über Composer (zwingend ab TYPO3 v14; TER-Installation wird bis TYPO3 v13 unterstützt) und richten Sie die grundlegenden TYPO3-Optionen und TypoScript-Reihenfolge ein.

  • Admin Tools > Settings > Configure Installation-Wide Options: [FE][pageNotFoundOnCHashError] auf false setzen.
  • Composer installiert die benötigte Abhängigkeit Container Content Elements automatisch.
  • TypoScript unter Site Management > TypoScript (Advanced Options) in dieser Reihenfolge einbinden: fluid_styled_content, form, seo, news, t3headless.
# 1. Install EXT:t3headless via Composer (mandatory for TYPO3 v14+, recommended for v13)
composer require t3element/t3headless

# 2. Setup extensions & flush caches
vendor/bin/typo3 extension:setup
vendor/bin/typo3 cache:flush

# Note: TER download (Admin Tools > Extensions > Get Extension -> "t3headless")
# is supported up to TYPO3 v13 only.
02 / API & ACTIVATION

YAML API-Import & Lizenzaktivierung

Importieren Sie die Headless-API-Definition in die Site-Konfiguration (config.yaml) Ihrer TYPO3-Website und aktivieren Sie EXT:t3headless direkt im Backend unter Web > t3headless.

  • Fügen Sie den YAML-Import in config/sites/<site>/config.yaml hinzu.
  • Gehen Sie im Backend auf Web > t3headless > Get Started.
  • Wählen Sie "Activate License" (gekaufter Schlüssel) oder registrieren Sie sich direkt für einen kostenlosen Lizenzschlüssel per E-Mail.
# config/sites/<your-site>/config.yaml
imports:
  - resource: 'EXT:t3headless/Configuration/Yaml/default.yaml'

# Verify JSON API endpoint once configured:
# curl -i https://api.example.com/?type=834
03 / NEXT.JS FRONTEND

Next.js Frontend-Paket (t3headless-frontend)

Richten Sie das produktionsreife Next.js-Frontend ein, verbinden Sie es über API_KEY und API_LICENSE_KEY in config.js und verwalten Sie Logo, Favicon, CSS/JS und Header-Seiten zentral unter Theme Options > Header.

  • Voraussetzungen: Next.js-fähiger Server mit Node.js 18.17+ (empfohlen v20.11.0) sowie npm oder yarn.
  • API_LICENSE_KEY und API_KEY aus der Aktivierungs-E-Mail in config.js eintragen.
  • Einmaliges Setup (yarn setup) ausführen, danach Theme/Elemente mit yarn themebuild generieren.
# 1. Clone the Next.js frontend package
git clone https://github.com/milancrayon/t3headless-frontend
cd t3headless-frontend

# 2. Add API_LICENSE_KEY and API_KEY in config.js

# 3. Run initial setup (required once)
yarn setup          # or: npm run setup

# 4. Build theme configuration & generated UI elements
yarn themebuild     # or: npm run themebuild

# 5. Build and launch production server (default port 3000)
yarn build && yarn start
04 / VISUAL ELEMENTS

Container- & Custom-Elemente visuell erstellen

Erstellen Sie mehrspaltige Container-Elemente sowie eigene Content-Blöcke (z.B. Slider, Teaser, CTA) über den geführten 3-Schritte-Workflow (Info, Fields, Template) direkt im TYPO3-Backend.

  • Container Elements (t3headless > Elements > Container Elements): Über "+ Add Column" beliebig viele Spalten anlegen und Vorlage direkt anpassen.
  • Custom Elements (t3headless > Elements > Custom Elements): Felder per Drag-and-Drop hinzufügen, inklusive "Repeating"-Element für Slider und Akkordeons.
  • Theme Options > Header: Logo (inkl. eigener Breite/Höhe), Favicon, Fonts, CSS/JS und globale Header-Seiten ohne Code-Deployment pflegen.
# Guided 3-Tab Builder Workflow in TYPO3 Backend:
#
# Container Elements: t3headless > Elements > Container Elements > New Container Element
# Custom Elements:    t3headless > Elements > Custom Elements    > + Create New Element
#
#   Tab 1: Info      -> Title, Short Title, Description
#   Tab 2: Fields    -> Add Columns / Drag-and-Drop Fields / Repeating Items
#   Tab 3: Template  -> Edit React/Next.js JSX template directly
05 / REACT & NEXT.JS NOTES

Wichtige Hinweise für React / Next.js Templates

Beachten Sie beim Bearbeiten von T3Headless-Templates die speziellen JSX-Regeln sowie die automatisch bereitgestellten Komponenten (Link, Nimage und All.*).

  • className statt HTML-class Attribut verwenden.
  • Next.js <Link> statt <a> verwenden (im T3Headless-Template automatisch verfügbar, kein Import nötig).
  • <Nimage> statt <img> verwenden (überschreibt Next.js Image; Pflicht-Props: key, immg, data; kein Import nötig).
  • React-Bootstrap & Swiper-Komponenten über das Präfix "All." nutzen: <All.Accordion>, <All.Slider> und <All.SliderItem>.
{/* 1. Next.js Link & className (no import needed) */}
<Link href="/contact" className="btn-primary">Get Started</Link>

{/* 2. T3Headless Nimage component (no import needed) */}
{_data?.images?.map((immg: any, index: number) => (
  <Nimage
    key={_data?.uid + immg?.url + index}
    immg={immg}
    data={data}
    width={500}
    height={500}
    className="w-100 h-auto"
    alt="Preview"
  />
))}

{/* 3. React-Bootstrap & Swiper via All.* prefix */}
<All.Accordion defaultActiveKey="0">...</All.Accordion>
<All.Slider slidesPerView={1} navigation={true}>
  <All.SliderItem>...</All.SliderItem>
</All.Slider>
INTERACTIVE JSON SCHEMA SANDBOX

JSON-Antworten testen

Interactive Headless TYPO3 → Component Inspector
GET https://api.example.com/?type=834 200 OK • JSON
{
  "id": 1,
  "slug": "/",
  "title": "Example Headless TYPO3 Site",
  "meta": {
    "title": "Example Brand | Headless TYPO3",
    "canonical": "https://www.example.com/",
    "robots": { "index": true, "follow": true }
  },
  "content": {
    "colPos0": [
      {
        "id": 104,
        "type": "t3element_hero_banner",
        "colPos": 0,
        "appearance": { "layout": "split-grid-2col" },
        "content": {
          "eyebrow": "HEADLESS CONTENT BLOCK",
          "headline": "Structured content delivered directly from TYPO3 JSON.",
          "ctaPrimary": { "label": "Get Started", "href": "/get-started" },
          "metrics": { "apiSpeedMs": 18, "uptime": "99.99%" }
        }
      }
    ]
  }
}
Hydrated UI Component <HeroBanner />
LIVE PREVIEW

Hero Banner Content Block

Renders the 2-column hero section and structured CTA fields directly from colPos0 JSON.

T3Element Runtime Guarantees

TTFB: 14msZero Fluid OverheadAuto-Typed Props
OFFIZIELLE DOKUMENTATION & BENUTZERHANDBUCH

Vollständige Schritt-für-Schritt-Anleitungen mit Screenshots ansehen.

Alle Detailartikel zu TYPO3-Installation, Abhängigkeiten, Theme-Optionen, Container-/Custom-Elementen und React-Template-Beispielen finden Sie in unserem Dokumentationsportal.