friendsoftypo3 / headless

v5.0.0-rc2 2026-09-02 12:07 UTC

Requires

• php: >= 8.2
• ext-json: *
• typo3/cms-core: ^14.0
• typo3/cms-install: ^14.0

Requires (Dev)

• ergebnis/composer-normalize: ^2.43
• friendsofphp/php-cs-fixer: ^v3
• helmich/typo3-typoscript-lint: ^v3
• justinrainbow/json-schema: ^5
• phpstan/extension-installer: ^1.1
• phpstan/phpstan: ^2
• phpunit/phpcov: ^8 || ^9 || ^10
• seld/jsonlint: ^1.11
• symfony/yaml: ^6.1 || ^7.1
• typo3/cms-felogin: ^14.3
• typo3/cms-form: ^14.0
• typo3/cms-redirects: ^14.3
• typo3/cms-seo: ^14.3
• typo3/cms-workspaces: ^14.3
• typo3/coding-standards: ^0.8
• typo3/testing-framework: ^9.0

Conflicts

• typo3/cms-core: <14.0

GPL-2.0-or-later

• Tymoteusz Motylewski
• Łukasz Uznański
• TYPO3 PWA Initiative

• json
• headless
• typo3
• pwa

Published on Packagist.org on 2026-09-02 14:23 UTC

README

Headless allows you to render JSON from TYPO3 content. You can customize output by changing types, names and nesting of fields.

This extension provides backend part (JSON API) for TYPO3 PWA solution. Second part is a JavaScript application nuxt-typo3 which consumes JSON API and renders the content using Vue.js and Nuxt. See frontend documentation here: https://t3headless.macopedia.io/nuxt-typo3

If you have any questions just drop a line in #initiative-headless-pwa Slack channel.

	URL
Repository:	https://github.com/TYPO3-Headless/headless
Read online:	https://docs.typo3.org/p/friendsoftypo3/headless/main/en-us/
TER:	https://extensions.typo3.org/extension/headless/
Slack:	https://typo3.slack.com/channels/initiative-headless-pwa

Features

• JSON API for content elements
• JSON API for page and meta data
• JSON API for navigation, layouts
• taking into account all language and translation configuration (e.g. fallback)
• easily extendable with custom fields or custom content elements
• custom data processors directly for headless usage
• support for EXT:form
• support for EXT:felogin
• support for EXT:redirects
• support for EXT:seo

Additional extensions and integrations

• headless support for EXT:news headless_news
• headless support for EXT:solr headless_solr
• headless support for EXT:powermail headless_powermail
• headless support for EXT:gridelements headless_gridelements
• small tools/tweaks for local headless development headless_dev_tools
• headless support for EXT:container headless-container-support and headless_container

Requirements and compatibility

EXT:headless version	TYPO3 support	PHP support	Status
>= 5.0	14	>= 8.2	Active development & support
>= 4.0	12, 13	>= 8.2	Bug & security fixes
>= 3.0	11	>= 7.4, <= 8.2	End of life
>= 2.0	9, 10	>= 7.2, <=7.4	End of life

Quickstart / Demo

If you want to take a look at working demo including frontend, backend and demo data, use our DDEV based demo project here: https://github.com/TYPO3-Headless/pwa-demo

Installation

Install extension using composer

composer require friendsoftypo3/headless

Documentation

Extension documentation

How to start with TYPO3 Headless video tutorial

Whether you are a developer, content manager, or a tech enthusiast, this tutorial is tailored to provide a comprehensive introduction to TYPO3 Headless, helping you to get started on your journey with confidence.

Configuration

Each site decides how it responds via two keys in its config/sites/<identifier>/config.yaml:

dependencies:
  - friendsoftypo3/headless
headless: 1

Site set (dependencies) — pick one:

• friendsoftypo3/headless — trimmed default response (new projects)
• friendsoftypo3/headless-legacy — full 4.x-compatible response (upgrades)
• friendsoftypo3/headless-mixed — full 4.x-compatible response, served as JSON only for requests whose Accept header is exactly application/json

Do not add a root sys_template record to a site using sets — its "Clear" flags would wipe the set TypoScript. Sites not using sets can include the equivalent statics in a root sys_template record instead: Headless, Headless Legacy (4.x) or Headless - Mixed mode JSON response.

Run mode (headless) — set in the yaml file or via the Site's management backend:

• 0 = headless mode is deactivated for the site within the TYPO3 instance. Default value!
• 1 = headless mode is fully activated for the site within the TYPO3 instance.
• 2 = mixed mode headless is activated (both fluid & json API are accessible within a single site in the TYPO3 instance) — pair it with the mixed set.

In mixed mode, TYPO3 responds with JSON only when the first Accept header value is exactly application/json. A list like Accept: application/json, text/plain, */* (the axios/fetch default) or application/json; charset=utf-8 gets the standard HTML response.

The legacy boolean values (true|false) are still recognized (the flag is cast to integer), but the integer notation is recommended. Full details, feature flags and multi-domain URL handling live in the Configuration chapter.

JSON Content Object

In headless extension we implemented new JSON Content Object, which allows you to specify what fields you want to output, and how they will look. First, let's take a look at simple example

lib.page = JSON
lib.page {
  fields {
    header = TEXT
    header {
      field = header
    }
  }
}

Output

{
    "header" : "headerFieldValue"
}

in addition, keyword fields allow you to nest multiple times fields in json, e.g.

lib.page = JSON
lib.page {
  fields {
    data {
      fields {
        foo = TEXT
        foo {
          field = bar
        }

        foo1 = TEXT
        foo1 {
          field = bar1
        }
      }
    }
  }
}

Output

{
    "data": [
        {
            "foo": "bar",
            "foo1": "bar1"
        }
    ]
}

INT, FLOAT & BOOL Content Objects for use in JSON Content Object

We introduce new simple content objects to improve JSON API response for frontend developers. We can set correct property types, so frontend does not have to deal with string values for fields with numeric values or field that should be true/false.

lib.page = JSON
lib.page {
  fields {
    data {
      fields {
        foo = INT
        foo {
          # db value of foo_field = 1
          field = foo_field
        }
        bar = BOOL
        bar {
          # db value of bar_field = 0
          field = bar_field
        }
      }
    }
  }
}

Output

{
    "data": [
        {
            "foo": 1,
            "bar": false
        }
    ]
}

Customizing

You can override every field in output using typoscript. This extension allows you to use standard typoscript objects such as TEXT, COA, CASE.

Example page response ⬇️

DataProcessing

You can use Data Processors just like in FLUIDTEMPLATE Content Object, e.g.

lib.languages = JSON
lib.languages {
  dataProcessing {
    10 = TYPO3\CMS\Frontend\DataProcessing\LanguageMenuProcessor
    10 {
      languages = auto
      as = languages
    }
  }
}

Built in data processors

We provide multiple data processors for headless rendering purposes.

DatabaseQueryProcessor

Used for fetching records from the database.

FilesProcessor

This processor should be used to process files (standard or media files).

Also, it allows you to process images. See docs chapter: Images for details.

GalleryProcessor

Should be used along with FilesProcessor (chained). Used for processing mutliple media files.

MenuProcessor

Used for navigation. Works just like standard menu processor.

FlexFormProcessor

Used for processing flexforms.

RootSitesProcessor

Render your all headless sites configuration for your frontend application.

Contributing

Development

Development for this extension is happening as part of the TYPO3 PWA initiative, see https://typo3.org/community/teams/typo3-development/initiatives/pwa/ If you have any questions, join the #initiative-headless-pwa Slack channel.

Credits

A special thanks goes to macopedia.com company, which is sponsoring development of this solution.