--- title: "Includes" manual: "TYPO3 Explained" version: "11.5" permalink: "https://docs.typo3.org/permalink/t3coreapi:typoscript-syntax-includes@11.5" source: "Configuration/TypoScriptSyntax/Syntax/Includes.rst" rendered: "2026-10-21T15:30:00+00:00" --- > [!WARNING] > **Attention** > > TYPO3 v11 has reached end-of-life as of October 31th 2024 and > is no longer being maintained. Use the version switcher on the top > left of this page to select documentation for a supported version of TYPO3. > > Need more time before upgrading? > You can purchase Extended Long Term Support (ELTS) for TYPO3 v11 here: > [TYPO3 ELTS](https://typo3.com/services/extended-support-elts). # Includes {#typoscript-syntax-includes} You can also add include-instructions in TypoScript code. Availability depends on the context, but it works with TypoScript templates, page TSconfig and user TSconfig. The syntax for importing external TypoScript files acts as a preprocessor before the actual parsing (condition evaluation) takes place. > [!WARNING] > Includes of either syntax within multi-line comments are still executed due > to a bug. Always use single line comments if you need to comment out an import: > > **EXT:some_extension/Configuration/TypoScript/setup.typoscript** > > ```typoscript > # @import 'EXT:myproject/Configuration/TypoScript/randomfile.typoscript' > ``` Its main purpose is ease the use of TypoScript includes and making it easier for integrators and frontend developers to work with distributed TypoScript files. The syntax is inspired by SASS imports and works as follows: ```typoscript # Import a single file @import 'EXT:myproject/Configuration/TypoScript/randomfile.typoscript' # Import multiple files in a single directory, sorted by file name @import 'EXT:myproject/Configuration/TypoScript/*.typoscript' # It's possible to omit the file ending, then "*.typoscript" is appended automatically @import 'EXT:myproject/Configuration/TypoScript/' ``` The main benefits of `@import` compared to `` are: - is less error-prone - @import is expressive and self-explanatory - better clarifies whether files or folders are imported (in comparison to the old `FILE:` and `DIR:` syntax) The following rules apply: - Multiple files are imported in alphabetical order. - Recursion is allowed. Imported files can have `@import` statements. - The `@import` statement does not take a condition clause as the old `` statement did. That kind of condition should be considered a conceptual mistake. It should not be used. - Both the old syntax `` and the new one `@import` can be used at the same time. - Directory imports are not recursive, meaning that a directory import does not automatically travel down its subdirectories. - Quoting the filename is necessary with the new syntax. Either double quotes (") or single quotes (') can be used. *Internals:* Under the hood, Symfony Finder is use to find the file and provides the "globbing" feature (\* syntax). *Outlook:* The syntax is designed to stay and there are absolutely no plans to extend the `@import` statement in the future. However, the `@...` syntax for annotations may be used to add more preparsing logic to TypoScript in future. ## Alternative, traditional Syntax {#alternative-traditional-syntax} A traditional include-instruction will work as well and for example looks like this: ```typoscript ``` - It must have its own line in the TypoScript template, otherwise it is not recognized. - It is processed BEFORE any parsing of TypoScript (contrary to conditions) and therefore does not care about the nesting of confinements within the TypoScript code. The "source" parameter points to the source of the included content. The string before the first ":" (in the example it is the word "FILE") will determine which source the content is coming from. These options are available: | Option | Description | | --- | --- | | FILE | A reference to a file relative to `\TYPO3\CMS\Core\Core\Environment::getPublicPath()`. Also paths *relative to the including file* can be passed to INCLUDE_TYPOSCRIPT, if the inclusion is called from inside a file. These paths start with `./` or `../`. The `./` is needed to distinguish them from paths relative to `\TYPO3\CMS\Core\Core\Environment::getPublicPath()`. This mechanism allows simple, nested TypoScript templates that can be moved or copied without the need to adapt all includes. If you use a syntax like `EXT:myext/directory/file.txt` the file included will be searched for in the extension directory of extension "myext", subdirectory `directory/file.txt`. | | DIR | This includes all files from a directory relative to `\TYPO3\CMS\Core\Core\Environment::getPublicPath()`, including subdirectories. If the optional property `extensions="..."` is provided, only files with these file extensions are included; multiple extensions are separated by comma. This allows e.g. to include both setup and constants from the same directory tree, using different file extensions for both. Files are included in alphabetical. Also files are included first, then directories. Example: ```typoscript ``` This includes all those files from the directory `fileadmin/templates/` and from subdirectories, which have the file extension `.typoscript`. | ## Conditions {#typoscript-syntax-includes-conditions} Since TYPO3 v7, it is possible to use conditions on include directives. The conditions are the same as was presented in the [previous chapter](https://docs.typo3.org/permalink/t3coreapi:typoscript-syntax-conditions@11.5). The files or directories will be included only if the condition is met. Example: ```text ``` The syntax of condition has switched to the [symfony expression language](https://symfony.com/doc/4.1/components/expression_language.html) which [is covered in this section of TSref](https://docs.typo3.org/m/typo3/reference-typoscript/11.5/en-us/Conditions/Index.html#conditions). If the condition requires double quotes, they must be converted to single quotes or escaped, e.g.: ```typoscript ``` ## Best practices {#typoscript-syntax-includes-best-practices} The option to filter by extension has been included exactly for the purpose of covering as many use cases as possible. In TYPO3 we often have many different ways of configuring something, with pros and cons and the extended inclusion command serves this purpose of letting you organize your files with different directories using whichever extension fits your needs better (e.g., `.typoscript`) and/or filter by extension (e.g., because you may have `.typoscript` and `.txt` in the directory or because you prefer having `.typoscript` as extension). It is recommended to separate files with different directories: - For TSconfig code use a directory called TSconfig/, possibly with subdirectories named Page/ for page TSconfig and User/ for user TSconfig. - For TypoScript template code, use a directory named TypoScript/. However, we understand that filtering by extension could make sense in some situations and this is why there is this additional option.