---
title: "Provide frontend TypoScript in a TYPO3 extension"
manual: "TypoScript Explained"
version: "13.4"
permalink: "https://docs.typo3.org/permalink/t3tsref:extdev-add-typoscript@13.4"
source: "UsingSetting/AddTypoScriptWithExtensions.rst"
rendered: "2026-09-30T07:08:12+00:00"
---

# Provide frontend TypoScript in a TYPO3 extension {#extdev-add-typoscript}

<!-- TODO: no Markdown rendering for "versionchanged" -->

TypoScript on a per-site basis can now be included via
sites and sets.

> [!NOTE]
> This part is written for extension developers.

## Provide TypoScript in your extension or site package {#extdev-add-typoscript-extension}

TypoScript files **must** have the ending `.typoscript`.

They are located in `Configuration/Sets/MySet` within your
extension. Read more about how to
[provide the TypoScript as set for TYPO3 v13 and above](https://docs.typo3.org/permalink/t3tsref:extdev-add-typoscript-sets@13.4)
and [how to provide TypoScript for both TYPO3 v13 and v12](https://docs.typo3.org/permalink/t3tsref:extdev-add-typoscript-sets-v12@13.4).

-   `constants.typoscript` contains the frontend TypoScript constants
-   `setup.typoscript` contains the frontend TypoScript

## TypoScript provided as site set (only TYPO3 v13.1 and above) {#extdev-add-typoscript-sets-typoscript}

The file structure of the extension could, for example look like this:

-   Configuration
    -   Sets
        -   MyExtension
            -   [config.yaml](https://docs.typo3.org/permalink/t3tsref:extdev-add-typoscript-sets-main@13.4)
            -   [constants.typoscript](https://docs.typo3.org/permalink/t3tsref:extdev-add-typoscript-sets-typoscript@13.4)
            -   [setup.typoscript](https://docs.typo3.org/permalink/t3tsref:extdev-add-typoscript-sets-typoscript@13.4)
        -   MyExtensionWithACoolFeature
            -   [config.yaml](https://docs.typo3.org/permalink/t3tsref:extdev-add-typoscript-sets-feature@13.4)
            -   [setup.typoscript](https://docs.typo3.org/permalink/t3tsref:extdev-add-typoscript-sets-typoscript@13.4)
-   Resources
    -   ...
-   composer.json
-   ...

With the extension's TypoScript residing in `EXT:my_extension/Configuration/Sets/MyExtension`
and the TypoScript for some optional feature in
`EXT:my_extension/Configuration/Sets/MyExtensionWithACoolFeature`. Let us assume, that the
optional feature depends on the main TypoScript.

The sets can now be defined for TYPO3 v13 as follows:

### The main set of the extension {#extdev-add-typoscript-sets-main}

**EXT:my_extension/Configuration/Sets/MyExtension/config.yaml**

```yaml
name: myvendor/my-extension
label: My Extension, main set

```

### The sub set for an optional feature {#extdev-add-typoscript-sets-feature}

**EXT:my_extension/Configuration/Sets/MyExtensionWithACoolFeature/config.yaml**

```yaml
name: myvendor/my-extension-with-a-cool-feature
label: Set for a cool feature

# This feature depends on the TypoScript and settings of the main set
dependencies:
  - myvendor/my-extension

```

### Overriding the TypoScript {#extdev-add-typoscript-sets-override}

The TypoScript provided in the site set will be loaded exactly once and respect
the dependencies defined in the site set configuration. Therefore if you
have to override the frontend TypoScript of another site set your site set
should depend on the other site set:

**EXT:my_sitepackage/Configuration/Sets/MySitePackage/config.yaml**

```yaml
name: myvendor/my-sitepackage
label: My Set
dependencies:
  - my-vendor/my-other-set
  - some-vendor/some-extension

```

Your extension can then safely override frontend TypoScript of the `some_extension`,
for example:

**EXT:my_sitepackage/Configuration/Sets/MySitePackage/setup.typoscript**

```typoscript
plugin.some_extension_pi1.settings.someSetting = Special setting
```

## Supporting both site sets and TypoScript records {#extdev-add-typoscript-sets-v12}

<!-- TODO: no Markdown rendering for "versionchanged" -->

With TYPO3 13.1
site sets as TypoScript provider
where introduced. Existing extensions should support site sets as well as
TypoScript records for backward compatibility reasons.

> [!WARNING]
> For historic reasons you might still see filenames like `setup.ts` and
> `setup.txt`. These files **cannot** be included with the
> [@import](https://docs.typo3.org/permalink/t3tsref:typoscript-syntax-import@13.4) syntax. All frontend
> TypoScript files **must** end on `.typoscript`.

TYPO3 v12 does not know site sets. To offer the same TypoScript there,
register the set folders as static files, behind a version check so that
v13 does not list them a second time:

**EXT:my_extension/Configuration/TCA/Overrides/sys_template.php**

```php
<?php

use TYPO3\CMS\Core\Information\Typo3Version;
use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;
use TYPO3\CMS\Core\Utility\GeneralUtility;

defined('TYPO3') or die();

call_user_func(function () {
  $extensionKey = 'my_extension';
  $versionInformation = GeneralUtility::makeInstance(Typo3Version::class);
  if ($versionInformation->getMajorVersion() < 13) {
    ExtensionManagementUtility::addStaticFile(
      $extensionKey,
      'Configuration/Sets/MyExtension',
      'My Extension, main TypoScript, always include',
    );
    ExtensionManagementUtility::addStaticFile(
      $extensionKey,
      'Configuration/Sets/MyExtensionWithACoolFeature',
      'My Extension, Cool feature',
    );
  }
});

```

### One TypoScript include set {#extension-configuration-typoscript-set-record-one}

If your extension supported one static file include you should provide the same
files in your main site set as well:

**EXT:my_extension/Configuration/TCA/Overrides/sys_template.php (before and after)**

```php
<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addStaticFile(
  'my_extension',
  'Configuration/TypoScript/',
  'Examples TypoScript',
);

```

In your main site set provide the same files that where provided as includes
by `\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addStaticFile`
until now:

-   packages/my_extension/Configuration/
    -   Sets
        -   MySet
            -   config.yaml
            -   constants.typoscript
            -   setup.typoscript
    -   TypoScript
        -   constants.typoscript
        -   setup.typoscript

**packages/my_extension/Configuration/Sets/MySet/constants.typoscript**

```typoscript
@import 'EXT:my_extension/Configuration/TypoScript/constants.typoscript'
```

**packages/my_extension/Configuration/Sets/MySet/setup.typoscript**

```typoscript
@import 'EXT:my_extension/Configuration/TypoScript/setup.typoscript'
```

### Multiple TypoScript include sets {#extension-configuration-typoscript-set-record-multiple}

If there should be more then one set of TypoScript templates that may be
included, they were usually stored in sub folders of
`Configuration/TypoScript` until now.

When introducing site sets usually one site set per TypoScript record include
set is needed:

-   packages/my_extension/Configuration > -   TypoScript > >     -   SpecialFeature1 > >         -   constants.typoscript >         -   setup.typoscript >     -   SpecialFeature2 > >         -   setup.typoscript >     -   constants.typoscript >     -   setup.typoscript > -   Sets > >     -   MyMainSet > >         -   config.yaml >         -   constants.typoscript >         -   setup.typoscript >     -   MySpecialFeature1Set > >         -   config.yaml >         -   constants.typoscript >         -   setup.typoscript >     -   MySpecialFeature2Set > >         -   config.yaml >         -   setup.typoscript

For backward compability reasons `ExtensionManagementUtility::addStaticFile`
still needs to be called for each folder that should be available in the TypoScript
template record:

**EXT:my_extension/Configuration/TCA/Overrides/sys_template.php**

```php
<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addStaticFile(
  'my_extension',
  'Configuration/TypoScript/',
  'My Extension - Main TypoScript',
);

ExtensionManagementUtility::addStaticFile(
  'my_extension',
  'Configuration/TypoScript/SpecialFeature1/',
  'My Extension - Some special feature 1',
);

ExtensionManagementUtility::addStaticFile(
  'my_extension',
  'Configuration/TypoScript/SpecialFeature2/',
  'My Extension - Some special feature 2',
);

```

Each site set then provides the TypoScript files the according location by
importing it, for example:

**packages/my_extension/Configuration/Sets/MySpecialFeature2Set/setup.typoscript**

```typoscript
@import 'EXT:my_extension/Configuration/TypoScript/SpecialFeature2/setup.typoscript'
```

## Make TypoScript available (always load) {#extdev-always-load}

Use `ExtensionManagementUtility::addTypoScript` if the frontend
TypoScript **must** be available in backend modules without page context,
for example to [register the YAML of the EXT:form system extension
for the backend](https://docs.typo3.org/c/typo3/cms-form/13.4/en-us/I/Concepts/Configuration/Index.html#concepts-configuration-yamlregistration-backend).

**EXT:my_extension/ext_localconf.php**

```php
<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTypoScript(
  'my_extension',
  'setup',
  '
        module.tx_form {
            settings {
                yamlConfigurations {
                    100 = EXT:my_sitepackage/Configuration/Form/CustomFormSetup.yaml
                }
            }
        }
    ',
);

```

> [!WARNING]
> While the content from the files
> [ext_typoscript_setup.typoscript](https://docs.typo3.org/m/typo3/reference-coreapi/13.4/en-us/ExtensionArchitecture/FileStructure/ExtTyposcriptSetupTyposcript.html#ext_typoscript_setup_typoscript)
> and [ext_typoscript_constants.typoscript](https://docs.typo3.org/m/typo3/reference-coreapi/13.4/en-us/ExtensionArchitecture/FileStructure/ExtTyposcriptConstantsTyposcript.html#ext_typoscript_constants_typoscript)
> is loaded by default in sites based on **TypoScript records** it is not
> loaded in sites depending on **site sets as TypoScript providers**.

## More information {#more-information}

-   [TypoScript imports](https://docs.typo3.org/m/typo3/tutorial-sitepackage/13.4/en-us/ContentMapping/TypoScript.html#typoscript-configuration) (in "Sitepackage Tutorial")\`
-   [Site settings: Further configuration options](https://docs.typo3.org/m/typo3/tutorial-sitepackage/13.4/en-us/SiteSets/Index.html#extension-configuration) (in "Sitepackage Tutorial")\`