Zum Inhalt springen

TYPO3 „headless“ bei einem TYPO3 Hoster einrichten

Last updated on 27. Mai 2024

In diesem Fall beim Hoster Mittwald

Vielen Dank für die aktive Unterstützung des Mittwald-Supports!


Index


1. TYPO3 anlegen – (hier nur in Kurzform erklärt)

Bei Mittwald kann man eine TYPO3-Composer-Version mit einem Knopfdruck anlegen. Sie landet normalerweise dann innerhalb des /html-Verzeichnisses im Verzeichnis „typo3-composer“.

Alternativ geht es auch händisch, wobei „typo3-composer“ für einen beliebigen Ordnernamen steht.

//SSH-Terminal innerhalb von html

composer create-project "typo3/cms-base-distribution:^12.4" typo3-composer

Danach stellt man die Domain auf den Ordner

/html/typo3-composer/public/

ein.

In diesem Fall ist es eine Sub-Domain: „https://api.my-domain.de“

Jetzt in dem Verzeichnis public die Datei „FIRST_INSTALL“ anlegen und über den TYPO3-Install-Vorgang alles installieren.

Die TYPO3-headless-extension installieren:

// SSH-Terminal innerhalb von typo3-composer

composer req friendsoftypo3/headless

Nach ein paar weiteren Einstellungen (siehe Dokumentation der headless extension) bekommt man unter der api: „https://api.my-domain.de/“ dann den kompletten Inhalt der Sartseite. Unter „https://api.my-domain.de/another-page/“ den Inhalt einer anderen Seite als JSON-Output.

Um ein Menü zu rendern braucht Nuxt aber auch einen Überblick über alle vorhandenen Seiten diesen bekommt man ebenfalls als JSON unter:

https://api.my-domain.de/?type=834

Beide Ausgaben kann man sich wunderbar mit dem Browser Firefox in verschiedenen Darstellungen ansehen.

Mehr dazu hier:

Extension headless: https://extensions.typo3.org/extension/headless

Extension Dokumentation: https://docs.typo3.org/p/friendsoftypo3/headless/main/en-us/

Hier in diesem Blog:

https://blog.zazu.berlin/internet-programmierung/typo3-headless-the-typo3-headless-api-extension-and-the-nuxt-typo3-module-a-detective-attempt-to-understand-the-structures.html


2. Die Node.js- und Nuxt-Umgebung bei Mittwald einrichten

Achtung vorher buchen: Node.js muss bei Mittwald mittels einer zusätzlichen Monatsgebühr freigeschaltet werden.

Ausgangslage

Wir haben momentan folgende Umgebung innerhalb des Ordners /html:

//Ordnersturktur innerhalb von /html

.
..
cgi-bin
index.html
stats
typo3-composer

Ziel ist es, dass

typo3-composer/public

die

https://api.my-domain.de

liefert und Node.js/Nuxt dann die eigentliche Webseite unter

https://my-domain.de

Ab hier folgen wir den Angaben vom Mittwald Support:

Wir wechseln via SSH in das Verzeichnis /html

// innerhalb von /html

npm i nuxi

Nuxi ist ein Command-Line-Tool von Nuxt um Nuxt-Applications zusammenzubauen. Mit „i“ wird es installiert im allgemeinen Ordner /html

Danach haben wir folgende Struktur (ob es auch in einem weiteren Unterordner z. Bsp. „Nuxt“ funktioniert ist nicht klar):

//Ordnersturktur innerhalb von /html

.
..
cgi-bin
index.html
node_modules
  .bin
  .package-lock.json
  nuxi
package-lock.json
package.json
stats
typo3-composer

Installation der TYPO3-Nuxt-headless Umgebung

Achtung es gibt zwei Anleitungen, eine bezieht sich auf eine ältere Version des typo3-nuxt-Modules die aktuelle für Nuxt3-typo3-headless-module ist hier:

https://t3headless.macopedia.io/nuxt-typo3/introduction

T3H
//ssh innerhalb von /html

npx nuxi@latest init -t gh:TYPO3-Headless/nuxt-typo3-starter <your-project>

Danach kommen ein paar Fragen:

  • npm
  • Initialize git: yes

Danach gibt es einen Hinweis, dass man den Hauptbranch von git noch von „master“ auf „main“ umstellen kann, das als der neue Standard gilt. Dafür muss man erstmal mit cd in den neuen Projektordner:

// ssh innerhalb von /html

cd your-project
git branch -m main

Nun muss man noch die entsprechenden Abhängigkeien des node.js-nuxt-TYPO3-Modules installieren:

// ssh innerhalb von /html/your-project

npx nuxi@latest module add typo3

Man bekommt die Rückmeldung, dass @t3headless/nuxt-typo3 schon in den Modulen ist und dass nuxt.config.ts upgedated wurde.

Die neue Ordnerstruktur sieht jetzt so aus:

//Ordnersturktur innerhalb von /html

.
..
cgi-bin
index.html
your-project
node_modules
package-lock.json
package.json
stats
typo3-composer

Innerhalb des Projektordners „your-project“ ist nun die komplette Nuxt-App installiert. Mit dem speziellen Modul „@t3headless/nuxt-typo3“ im Ordner /html/your-project/node_modules/@t3headless

Hier die Ordnersturktur innerhalb von „your-project“:

// innerhalb von /html/your-project
.
..
app.vue
.git
.gitignore
node_modules
.nuxt
nuxt.config.ts
package.json
package-lock.json
public
README.md
tscofig.json

Die nuxt.config.ts muss angepaßt werden um Nuxt mitzuteilen wo die api-Daten abzuholen sind.

// Inhalt der nuxt.config.ts

// https://nuxt.com/docs/api/configuration/nuxt-config
export default defineNuxtConfig({
  devtools: { enabled: true },
  modules: [
    '@t3headless/nuxt-typo3'
  ],
  typo3: {
    api: {
      baseUrl: process.env.API_BASE || 'https://api.my-domain.de'
    }
  }
})

„nuxt-socket-io“ braucht man bei Nuxt3 nicht mehr

In einer früheren Mail teilte Mittwald mit, dass node.js bei Mittwald nicht über einen Port sondern über ein Socket läuft und deshalb die Nuxt-App noch die Erweiterung „nuxt-socket-io“ braucht. Dies gilt aber nur für Nuxt2 bei TYPO3 verwenden wir Nuxt3 und brauchen die „nuxt-socket-io“ nicht mehr. Alle notwendigen Angaben sind in der „.mwservice.yaml“.

Jetzt läuft Nuxt, aber noch nicht der node.js Server bei Mittwald

.mwservice.yaml im Projektordner /html/your-project/.mwservice.yaml

Mittwalds Node.js-Installation braucht eine Datei mit dem Namen „.mwservice.yaml“ im Ordner „your-project“ diese hat den Inhalt:

//Inhalt von /html/your-project/.mwservice.yaml, ohne diesen Kommentar

enabled: true
command: node
args: [ ".output/server/index.mjs" ]
env:
  NITRO_UNIX_SOCKET: ${PORT}
  NODE_ENV: production

Erklärungen finden Sie hier: https://www.mittwald.de/faq/tipps-und-tricks/node-js/node-js-app-einrichtung

„enabled“, sagt, dass die App immer gestartet wird, „node“ ist das Kommando für alle Befehle und „args“ ist das Ziel zu den Outputfiles und der „index.mjs“ (was vergleichbar bei TYPO3 die index.php ist).
NITRO_UNIX_SOCKET, sagt dem Server wo er ein Web-Socket einrichtet, also im Ordner in dem das Nuxt-Projekt läuft (das bedeutet die ${PORT} Variable).
„args“: sagt, dann wo, von dort aus die Ausgabe zu erhalten ist.

GUT ZU WISSEN

„mwservicectl“ ist das passende Kommando zur .mwservice.yaml.

Man kann nachdem man mit cd in den /html-Ordner gewechselt hat den Node-Serviceprozess anzeigen lassen:

mwservicectl status

oder stoppen

mwservicectl disable

oder starten

mwservicectl enable

oder neu starten

mwservicectl restart

Mittwald

@nuxt/kit auf der /html-Ebene

Danach braucht es noch das @nuxt/kit direkt im Ordner „/html“

// ssh in /html

yarn add --dev @nuxt/kit

Nuxt Kit wird für die Interaktion mit Hooks und Schnittstellen von Nuxt genutzt, damit diese vereinfacht werden. Die Installation muss in der höheren Ebene über dem Projekt geschehen, also direkt im Ordner „/html“.

Im Projektordner in der package.json „resolutions“ ergänzen

Zurück in den Projektordner „your-project“, hier muss in der package.json noch der Block „resolutions“ ergänzt werden:

// ssh in /html/your-project/package.json (ohne diesen Kommentar)

{
  "name": "nuxt-typo3-app",
  "private": true,
  "type": "module",
  "scripts": {
    "build": "nuxt build",
    "dev": "nuxt dev",
    "generate": "nuxt generate",
    "preview": "nuxt preview",
    "postinstall": "nuxt prepare"
  },
  "devDependencies": {
    "@t3headless/nuxt-typo3": "^2.0.2",
    "nuxt": "^3.8.1",
    "typescript": "^5.2.2",
    "vue": "^3.3.8",
    "vue-router": "^4.2.5"
  },
  "resolutions": { 
    "rollup": "npm:@rollup/wasm-node"
  }
}

ACHTUNG

Nach einer Änderung der package.json braucht es immer ein yarn install damit die Änderungen wirksam werden.

Also jetzt:

// ssh in /html/your-project/

yarn install

Ort von „resolutions“ ist der Projektordner und dort die „package.json“.

Nuxt Ausgabedateien generieren

Jetzt sind wir bereit mit Nuxt die Ausgabe zu generieren.

Wenn man noch nichts programmiert hat ist das die Standardvorgabe die von der nuxt-typo3 Node-Application produziert wird. In der Datei app.vue sollte das Statement <NuxtPage /> automatisch die Inhalte von TYPO3 darstellen und die „useT3Api“ sollte automatisch die Navigation laden.

Generieren der Nuxt-Ausgabe:

// ssh in /html/your-project

yarn nuxt build

Jetzt generiert die Nuxt-App die Outputfiles im Ordner „.output“ innerhalb der Nuxt-App also dem „your-project“ Ordner. Dieser hat nun folgende Struktur:

// ssh in /html/your-project

app.vue
.git
node_modules
.nuxt
nuxt.config.ts
.output
package.json
package-lock.json
public
README.md
tsconfig.json
yarn.lock

Der Ordner „.output“ hat folgende Struktur

// ssh in /html/your-project/.output

nitro.json
public
server

Der Ordner „server“ innerhalb von „.output“ ist das Ziel für unsere Frontend-Domain. Dies muss man im Mittwald-Kundencenter einstellen.

Am Ziel!

Jetzt müssten wir unter https://my-domain.de das sehen was wir bei TYPO3 an Standardelementen eingegeben haben (zum Testen z. B. reiner Text oder Text mit Bild etc.)

    Schreibe einen Kommentar

    Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert