Minimal site package

Create a minimal TYPO3 extension manually

Create the following file in the folder packages in your TYPO3 installation:

{
	"name": "myvendor/my-site-package",
	"type": "typo3-cms-extension",
	"description": "My site package",
	"require": {
		"typo3/cms-core": "^13.4"
	},
    "autoload": {
        "psr-4": {
            "Myvendor\\MySitePackage\\": "Classes/"
        }
    },
	"extra": {
		"typo3/cms": {
			"extension-key": "my_site_package"
		}
	}
}

In order to see any changes in the TYPO3 backend or frontend your site package needs to be installed:

ddev composer req myvendor/my-site-package

Create a minimal TYPO3 extension using b13/make

b13/make is a convenient TYPO3 extension which you can use during development to create a new TYPO3 extension quickly or add functionality to an existing one.

Use Composer to install it for development only:

ddev composer req b13/make --dev

Execute the command ddev typo3 make:extension and answer the prompt

ddev typo3 make:extension

 Enter the composer package name (e.g. "vendor/awesome"):
 > myvendor/my-site-package

 Enter the extension key [my_site_package]:
 >

 Enter the PSR-4 namespace [Myvendor/MySitePackage]:
 >

 Choose supported TYPO3 versions (comma separate for multiple) [TYPO3 v12 LTS]:
  [10.4] TYPO3 v10 LTS
  [11.5] TYPO3 v11 LTS
  [12.4] TYPO3 v12 LTS
  [13.4] TYPO3 v13 LTS
 > 13.4

 Enter a description of the extension:
 > My site package

 Where should the extension be created? [src/extensions/]:
 > packages

 May we add a basic service configuration for you? (yes/no) [yes]:
 > no

 May we create a ext_emconf.php for you? (yes/no) [no]:
 >

 [OK] Successfully created the extension my_site_package (myvendor/my-site-package).

This script creates a new folder called packages with a subfolder, my-site-package. It mainly contains only a file called composer.json.

You could of course also create this file manually. Step Composer configuration composer.json will explain the content of the composer.json. For the time being just remember the Composer name you have chosen (myvendor/my-site-package) and the extension name (my_site_package).

In order to see any changes in the TYPO3 backend or frontend your site package needs to be installed:

ddev composer req myvendor/my-site-package

After you have created your site package extension you can uninstall b13/make :

ddev composer remove b13/make --dev

Create a minimal TYPO3 extension using the Site Package Builder

To quickly build a site package you can also use the Sitepackage Builder.

To follow this tutorial you can fill in the form like that:

The summary of your data is then displayed.

You have to click on the "Download" link, on the top of the summary in order to get your zipped site package.

You can then unzip the zip file, place the resulting folder in your packages folder, and install it.

Extension installation

This tutorial assumes that your TYPO3 instance is a brand new installation, without any themes, templates, pages or content.

We assume that you are working on your local machine using DDEV and that you followed these steps:

Installing TYPO3 with DDEV

{
   "name": "myvendor/my-site-package"
}

composer require myvendor/my-site-package:@dev

Create a basic site set

Create a folder called Configuration/Sets/SitePackage/ in the site package and add a file called config.yaml to it. This file contains the site set of your site package:

name: myvendor/my-site-package
label: "Example: My Site package"

You will learn more about site sets in chapter The site set.

You can find the complete reference in TYPO3 explained: Site sets.

Edit the site configuration that was created in step Site configuration and add the site set to it. You can do this by using the backend module:

On saving, the site package is added to your site configuration file, which changes to this:

 base: '/'
+dependencies:
+  - myvendor/my-site-package
 languages:
    # ...

The TypoScript-only version

Create a file called setup.typoscript containing basic TypoScript configuration in the folder of the site set you created in step Create a basic site set:

# Create the frontend output of the page
page = PAGE
page {
    # Show a text with value "Hello TypoScript World!"
    10 = TEXT
    10.value = Hello TypoScript World!
}

Clear all caches and preview the web page.

You can learn more about the TypoScript syntax used here in chapter A minimal page created by pure TypoScript of the "Getting Started Tutorial".

The TYPO3 Fluid version

Replace file setup.typoscript of previuous example with the following lines:

page = PAGE
page {
    10 = PAGEVIEW
    10 {
        paths {
            100 = EXT:my_site_package/Resources/Private/Templates/
        }
    }
}

If you preview your page now you would get an error output like:

Oops, an error occurred! Request: bddd8a816bda3

This is because the template has not been found.

By searching for the hash bddd8a816bda3 in the log file you will find such an entry:

Mon, 07 Oct 2024 04:09:44 +0000 [ALERT] request="bddd8a816bda3"
component="TYPO3.CMS.Frontend.ContentObject.Exception.ProductionExceptionHandler":
Oops, an error occurred! Request: bddd8a816bda3- InvalidTemplateResourceException:
Tried resolving a template file for controller action "Default->Pages/Default"
in format ".html", but none of the paths contained the expected template file
(Default/Pages/Default.html).
The following paths were checked: /var/www/html/vendor/myvendor/my-site-package/Resources/Private/Templates/

This error message also tells you the path where TYPO3 expects to find the file. If no path is listed here, the path defined in line 6 of the TypoScript above is incorrect, for example if you mistyped the extension name or part of the path.

Create a file named Default.html in folder packages/my-site-package/Resources/Private/Templates/Pages.

Hello Fluid World!

Clear all caches and preview the web page.

Learn more about using Fluid Templates in chapter Fluid Templates.

Preview page

Whenever we have made changes to the Fluid templates or TypoScript files, it is necessary to Flush frontend caches in the menu in the top bar before you can preview the page properly:

You can then preview your page by clicking on the button View webpage in the page module.

Composer configuration composer.json

In step Create a minimal TYPO3 extension a file called composer.json was created for you:

{
	"name": "myvendor/my-site-package",
	"type": "typo3-cms-extension",
	"description": "Example site package from the site package tutorial",
	"require": {
		"typo3/cms-core": "^13.4|dev-main",
		"typo3/cms-fluid-styled-content": "^13.4|dev-main"
	},
	"homepage": "https://github.com/TYPO3-Documentation/TYPO3CMS-Tutorial-SitePackage-Code",
	"license": "MIT",
	"support": {
		"issues": "https://github.com/TYPO3-Documentation/TYPO3CMS-Tutorial-SitePackage-Code/issues"
	},
	"extra": {
		"typo3/cms": {
			"extension-key": "my_site_package"
		},
		"branch-alias": {
			"dev-master": "13.0.x-dev"
		}
	}
}

At the top of the composer.json file we see the Composer package name myvendor/my-site-package (with a dash) and at the bottom we see the TYPO3 extension key in the extra section - my_site_package (with an underscore). The Composer "name" consists of a vendor name followed by a forward slash and the lowercase extension name with dashes.

When you reference files in your extension, the extension key is used, for example when setting your favicon in TypoScript:

page {
    shortcutIcon = EXT:my_site_package/Resources/Public/Icons/favicon.ico
}