File imports

@import

This keyword allows including files inspired by a syntax similar to SASS. It is restricted, but still allows wildcards on file level. Single files must end with .typoscript if included in frontend Typoscript. In backend TSconfig, single files should end with .tsconfig, but may end with .typoscript as well (for now).

The include logic is a bit more restrictive with TYPO3 v12, previous versions have been slightly more relaxed in this regard. See this changelog for more details.

The following rules apply:

• Multiple files are imported in alphabetical order. If a special loading order is desired it is common to prefix the filenames with numbers that increase for files that shall be loaded later.
• Recursion is allowed: Imported files can have @import statements.
• The @import statement does not take a condition clause as the old <INCLUDE_TYPOSCRIPT condition=""> statement did. That kind of condition should be considered a conceptual mistake. It should not be used.

• Changed in version 12.0

  It is allowed to put @import within a condition. This example imports the additional file only if a frontend user is logged in:

  [frontend.user.isLoggedIn]
      @import './userIsLoggedIn.typoscript'
  [END]

  Copied!
• Both the old syntax <INCLUDE_TYPOSCRIPT> 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.
• Wildcards * are only allowed on file level, not on directory level. Only a single wildcard character is allowed.
• Includes relative to the current file location are allowed using ./ as prefix.
• Includes must start with EXT: if not relative. Loading files outside of extensions is not possible.
• Directory traversal using ../ is not allowed.

Some examples:

# Import a single file
@import 'EXT:my_extension/Configuration/TypoScript/randomfile.typoscript'

# Import multiple files in a single directory, sorted by file name
@import 'EXT:my_extension/Configuration/TypoScript/*.typoscript'

# It's possible to omit the file ending. For frontend TypoScript, ".typoscript" is
# appended automatically, backend TSconfig allows both ".typoscript" and ".tsconfig"
@import 'EXT:my_extension/Configuration/TypoScript/'

# Import files starting with "foo", ending with ".typoscript" (frontend)
@import 'EXT:my_extension/Configuration/TypoScript/foo*'

# Import files ending with ".setup.typoscript"
@import 'EXT:my_extension/Configuration/TypoScript/*.setup.typoscript'

# Import "bar.typoscript" relative to current file
@import './bar.typoscript'

# Import all ".setup.typoscript" files in sub directory relative to current file
@import './subDirectory/*.setup.typoscript'

Alternatives to using file imports

The following features can make file inclusion unnecessary:

• Automatic global inclusion of user TSconfig of extensions
• Automatic global inclusion of page TSconfig of extensions
• Automatic page TSconfig on site level
• TypoScript provider for sites and sets automatically loads TypoScript per site when the site set is included in the site configuration.

Migration from <INCLUDE_TYPOSCRIPT: to @import

Most usages of <INCLUDE_TYPOSCRIPT: can be turned into @import easily. A few examples:

-<INCLUDE_TYPOSCRIPT: source="FILE:EXT:my_extension/Configuration/TypoScript/myMenu.typoscript">
+@import 'EXT:my_extension/Configuration/TypoScript/myMenu.typoscript'

 # Including .typoscript files in a single (non recursive!) directory
-<INCLUDE_TYPOSCRIPT: source="DIR:EXT:my_extension/Configuration/TypoScript/" extensions="typoscript">
+@import 'EXT:my_extension/Configuration/TypoScript/*.typoscript'

# Including .typoscript and .ts files in a single (non recursive!) directory
-<INCLUDE_TYPOSCRIPT: source="DIR:EXT:my_extension/Configuration/TypoScript/" extensions="typoscript,ts">
+@import 'EXT:my_extension/Configuration/TypoScript/*.typoscript'
 # Rename all files ending from .ts to .typoscript

 # Including a file conditionally
-<INCLUDE_TYPOSCRIPT: source="FILE:EXT:my_extension/Configuration/TypoScript/user.typoscript" condition="[frontend.user.isLoggedIn]">
+[frontend.user.isLoggedIn]
+    @import 'EXT:my_extension/Configuration/TypoScript/user.typoscript'
+[END]

There are a few more use cases that cannot be transitioned so easily since @import is a bit more restrictive.

As one restriction @import cannot include files from arbitrary directories like fileadmin/, but only from extensions by using the EXT: prefix. Instances that use <INCLUDE_TYPOSCRIPT: with source="FILE:./someDirectory/..." should move these TypoScript files into a project or site extension. Such instances are also encouraged to look into the TYPO3 v13 Site sets feature and eventually transition towards it along the way.

@import allows to import files with the file ending .typoscript and .tsconfig. If you used any of the outdated file endings like .ts or .txt rename those files before switching to the @import syntax.

-<INCLUDE_TYPOSCRIPT: source="FILE:EXT:my_sitepackage/Configuration/TypoScript/Setup">

+@import 'EXT:my_sitepackage/Configuration/TypoScript/Setup'
+@import 'EXT:my_sitepackage/Configuration/TypoScript/Extensions'
+@import 'EXT:my_sitepackage/Configuration/TypoScript/Extensions/Solr'
+@import 'EXT:my_sitepackage/Configuration/TypoScript/ContentElements'