---
title: "TYPO3 Sitepackage Development"
description: "Skill: typo3-sitepackage-development"
canonical: index.html
navigation-title: "TYPO3 Sitepackage Development"
---

<a id="typo3-sitepackage-development"></a>

# TYPO3 Sitepackage Development

- [Markdown source](#markdown-source)
- [References](#references)
  - [Where every task starts](#where-every-task-starts)

**Skill:** `typo3-sitepackage-development`

Create a TYPO3 sitepackage or change how one is laid out: the extension, its
site set, the page templates with header and footer, the page layouts editors
choose, and the wiring into the site. Content elements, asset builds and the
installation itself belong to their own workflows.

<a id="markdown-source"></a>

## Markdown source

```markdown
---
name: typo3-sitepackage-development
description: 'Create a TYPO3 sitepackage or change how one is laid out: the extension, its site set, the page templates with header and footer, the page layouts editors choose, and the wiring into the site. Content elements, asset builds and the installation itself belong to their own workflows.'
compatibility: Needs the typo3-dev-companion MCP server, which owns every lookup this workflow routes to and publishes this skill together with the references/base.md it opens on. Install it from github.com/TYPO3/dev-companion and run typo3-dev-companion install in the project. A copy taken out of that repository's skills directory alone has neither the tools nor that base file.
---

# TYPO3 Sitepackage Development

Build the sitepackage a site renders through, or change its layout. Keep this
skill as routing and order. The tree, the TypoScript and the page layout rules
are lookups. A copy of them here is one nobody can correct.

**The work ends on a frontend that renders, one page for each page layout.** A
list of questions is not that result. Where the request leaves a choice open,
take the default this skill names and go on. Name every default in the report,
with the alternative and what it costs. Ask only for what neither the request
nor the project answers. The design is the one exception, in *Ask for the design
once*.

## Establish the site, then the package

Work through [references/base.md](references/base.md) first. It fixes the order
every task here starts in.

Then, for this workflow:

- Read the sites and their sets out of the base's `typo3_project_describe`. A
  sitepackage replaces the sets a site depends on, so note them now.
- Where a sitepackage exists already, `typo3_extension_describe` with its key
  says what it registers. Change that package rather than start a second one.
- Keep the core's content elements, and with them the dependency on
  fluid_styled_content, unless the user said otherwise. `typo3_hint_lookup` with
  `id="sitepackage-fluid-styled-content"` says what the other choice costs. Put
  that in the report.
- Run the base's deprecation sweep with `tags` set to `TypoScript`, `TSConfig`,
  `Fluid`, `YAML` and `Frontend`, the kinds of file a sitepackage ships, and
  `excludeTags` set to `PHP-API`. Add the entries about a file the package
  ships, such as `ext_localconf.php`.
- Take the vendor from the project's own packages, and the author from the root
  `composer.json` or the git configuration. Name the first page layout
  `Default`, so a page with no layout selected renders through it too.

## Ask for the design once

**Where the request names no design, ask one question before the first
template.** Bundle these four points into it, each with the default you take:

- Colours and fonts. The default is a neutral palette and the system font stack.
- A logo and a favicon. The default is the site title as text and no favicon.
- A website, a mockup or a styleguide to follow. The default is none.
- A CSS framework. The default is plain CSS without a build step.

Say that one reply such as "use the defaults" is enough. Ask once, and do not
ask again for a point the user left out. Take its default.

Put colours and fonts into CSS custom properties. Make a value a setting of the
set where an editor changes it per site. A framework with a build step is
`typo3-extension-asset-build`'s, at the point the templates are written.

## Convert a design

**Where the user hands in a design, convert it rather than paste it.** Before
the first template, ask `typo3_hint_lookup` with `ids` set to
`sitepackage-from-a-design` and `content-model-vs-markup`. Put each part of a
static page where that hint says:

- The doctype and the html, head and body tags go to the page object. A partial
  is a fragment of the body.
- The stylesheets and scripts go to `includeCSS` and `includeJS`. Each other
  asset goes through `f:uri.resource`.
- The navigation is a menu processor, not a list of page uids.
- Each kind of page in the design is a page layout of its own.
- Each block that repeats is a content element with fields, not markup in the
  page template. Name each one in the report as a content element still owed.

## Choose where a new package comes from

There are two starts. Use the one the user named. Where the user named none, use
the builder, and name the other start in the report.

1. **The builder at get.typo3.org.** It generates a base package from one
   request. Fetch `https://get.typo3.org/api/doc.json` first. Take the endpoint,
   the fields and the values each one accepts from that schema, never from an
   example. Choose the base package that matches the fluid_styled_content
   decision. The TYPO3 version is the line the installation runs. The request
   carries an author email to a service outside the project. Send a placeholder
   unless the user agreed, and write the real author into the local files. The
   builder takes the vendor from the company and the key from the title, so send
   the ones the package is meant to carry.
2. **A tree written by hand.** `typo3_hint_lookup` with
   `id="sitepackage-layout"` gives the tree and what each directory is for. Take
   this start where the builder does not offer the installed line, or does not
   answer.

`typo3_hint_lookup` with `id="sitepackage-start"` says what else creates a
sitepackage, and what each tool writes on the installed major.

**A generated package is a starting point.** Read each generated file against
the hints in *Lay it out* and the sweep before you keep it. Remove the empty
directories and the files this site does not use, and say which ones you
removed. Move each part that stands outside the tree of `sitepackage-layout`
into that tree. Where `sitepackage-start` names the place of a builder part,
take that place. Report the moves.

## Lay it out

Ask `typo3_hint_lookup` for these parts in one call, with their ids in `ids`,
before you write them. Leave out the ones the brief of `typo3_task_guide`
already carries in its hints:

- `sitepackage-templates` for the template root, the layouts and the partials.
- `sitepackage-backend-layouts` for the page layouts, where they live, and what
  a page with no layout selected renders.
- `sitepackage-typoscript-reference` for which package defines each object you
  reference.
- `page-content-areas` for the areas a page template may address.
- `page-variables-and-processors` for what a page template is handed: the
  settings of the set, the site, the page and the menu.

A page layout and its page template are one name in three places. Write them in
one step, not one after the other.

## Wire it in and prove it

The package is not done when its files exist. Work these steps in order:

1. Require the package through Composer, from the path it sits in.
2. Set it up with the console's `extension:setup`.
3. Add its set to the dependencies of the site configuration. Remove the sets it
   replaces.
4. Find the installer's welcome page. `typo3_hint_lookup` with
   `id="installation-setup"` says where the installed major puts it: the site's
   own `setup.typoscript`, or a root `sys_template` row that clears. Replace the
   file's content with a comment, or hide the row. Delete neither, and report
   what it held.
5. Flush the caches, then render one page for each page layout. Where the
   installation has no page with a layout, set one page's layout in its page
   properties. Without a backend at hand, write its `backend_layout` field as
   `pagets__<identifier>` through DataHandler, never by SQL. A write by SQL
   skips the caches, the history and the reference index. `typo3_hint_lookup`
   with `ids` set to `datahandler-seeding` and `datahandler-writing` gives the
   script and its datamap. Read the old value first with `typo3_record_lookup`.
   Put it back the same way after the request, and report both writes. A
   layout whose template addresses an area other than `main` also proves that
   the set's page TSconfig loaded. Place a content element in that area the
   same way, and delete it the same way afterwards.
6. Count the tags in each response of step 5. Each page holds one `<html>`,
   one `<head>` and one `<body>`. A second set passes every other check. Take
   it out of the templates, and keep the page object. Never meet the count with
   `config.disableAllHeaderCode`, because that drops every asset the page
   object includes.

A request to the page proves the render. Where the site's base names a host the
environment does not serve, `typo3_project_describe` says so and names the Host
header to send instead. For a look in a browser, ask `typo3_rule_lookup` with
`documentId="any/testing/browser-check"` at step 5, not earlier. Then open the
page module once, and check that each layout shows its title and columns. Where
you could not render a layout, report it as unproven and name it.

**Where no shell runs Composer and the console, stop after the files.** Leave
the site's dependencies as they are, because a set nothing installed breaks
every page. Hand the user steps 1 to 5 as commands, and say the frontend is
untested.

## Read what the finished site serves

**A page that renders is not yet a page a search engine can index or a
keyboard user can work.** Run this pass after step 5, on the responses of that
step. Read the home page and one subpage in each language.

Ask `typo3_hint_lookup` once, with `ids` set to `page-head-seo`,
`page-heading-levels`, `xml-sitemap` and `sitepackage-focus-contrast`. Then
read each point off a response, not off a file:

- One h1 per page, and no heading before it.
- The meta description and the canonical in the head. Where the page has a
  translation, also the hreflang set.
- `/sitemap.xml` and `/robots.txt`, each answered by the site.
- The focus colour against every surface a link sits on. Compute that ratio from
  the declared colours.

Fix what this skill owns: the page templates, the partials and the CSS. Report
the rest with the page and the language. An empty description is the editors'
text to write. For a sitemap or a `robots.txt` that is missing, report the fix
the hints name.

## Where this stops

**When the user asks for a content element, invoke
`typo3-content-element-development`.** Carry across the extension key, the set
and the template root. **When the package needs an asset build, invoke
`typo3-extension-asset-build`** with the same three. Where the site has no
running installation to render in, **invoke `typo3-development-installation`**
at the point the package is written and wired.

The site configuration's languages, base and error handling are the user's.
Leave them as they are.

`typo3_commit_message_guide` with `workflow="project"` drafts the message for
the commit in the project repository.

This skill owns the sitepackage extension, its set, its page templates, its page
layouts and their wiring into the site. Stop before you edit another owner's
files.
```

<a id="references"></a>

## References

<a id="where-every-task-starts"></a>

### Where every task starts

```markdown
# Where every task starts

## Nothing starts until the server answers

A skill is a file the installer left behind. It loads and reads the same whether
the tools behind it are there or not, and neither side notices. So the first
call below is also the check.

- A client may carry this server's name in each tool's name:
  `mcp__<server>__typo3_project_describe`. So a search for the bare name comes
  back empty where the server is there. A search for a tool's schema needs the
  same form. A `select:` on the bare names returns nothing where the tools are
  there. Look for the qualified form before you read an empty result as an
  answer about the server.
- No `typo3_` tool in this session, or a first call that errors: stop. Say that
  this workflow needs the server and it is not there, and name what came back.
- Do not fall back to general TYPO3 knowledge, and do not start to read the
  checkout. That answer carries this workflow's order and confidence and none of
  its evidence. Nothing in it says which of the two it is.
- Continue only when the user asks you to after you said so. Repeat it in the
  answer and in every finding a lookup would have carried.

## The order

This is an order rather than a list. Each step decides what the next one is
worth. Where a step below carries a condition to skip it, that condition is
narrow on purpose. A skipped prescription teaches the next reader to skip the
ones that matter too.

1. **`typo3_project_describe`** — the repository and whether it holds an
   installation yet. It reports the TYPO3 and PHP version, the project's own
   extensions, its sites, and the commands this repository declares. That
   version filters every later answer. A check the repository does not declare
   is a wrong answer however sensible it sounds.

   The answer ends with the whole procedures this server carries, as ids. That
   list is the only place a client that renders no resource list sees their
   names. Each one is a `typo3_rule_lookup` with that `documentId` rather than a
   search.
2. **`typo3_extension_describe`** for each extension in scope. It says what the
   extension registers, and what it ships beside that. That is its manual, its
   README, its test layers, and its XLF files with the source language each one
   declares. It also says what the extension does *not* ship, and that is the
   half no file listing gives you.

   Where step 1 reported no extension, that answer is this step, and there is
   nothing to call. Say so. A core checkout is that case, because step 1 names
   the project's own extensions and not TYPO3's.
3. **`typo3_task_guide`** with a short English task, the paths it touches and
   the change type. It answers the workflow this task belongs to and the checks
   that come with it.

   Leave `targetVersion` out unless the task is about one major alone. Without
   it, the guide answers for every major the package declares. The installed
   version is one of those majors. A version you state narrows the answer to it.

   Run it in every session, this skill's own tasks included. The guide builds
   the brief from the paths as well as the task text. No skill knows which paths
   the caller holds.

   A skill that covers the task is not that brief. A skipped step costs the
   hints and the core checks those paths match. Where the guide's own answer
   named this skill, this is one call for an answer already in the session. The
   price of a step there is nothing to decide about.
4. **`typo3_hint_lookup`** for each subsystem in scope, with its concrete paths.
   One query per subsystem. A single broad query is not subsystem evidence.

   Where step 3 ran with those paths, its answer says whether you still owe this
   step. A brief that carried everything the lookup matched says so: "these are
   everything typo3_hint_lookup matches for these paths". There the guide made
   the call, and the same query returns the same hints. A brief that stopped
   short says that instead and names the ids it left. You owe those: fetch them
   by id rather than repeat the query.

   Read the sentence rather than the populated `hints` key. That key is present
   either way and does not tell the two apart. `omittedHints` is that sentence
   as data. It is empty where the brief carried everything, and it holds the ids
   the brief left where it stopped short.
5. **`typo3_changelog_lookup` with `type: deprecation`**, at each major the
   package declares. Omit the query and raise `limit` to carry that major whole.
   Those two are the changelog's own axes, and the extension's vocabulary is not
   among them. An entry carries a query only when its title carries every word
   of it at once. The core titled those entries about its own code.

   That is one call per declared major, and what comes back is the major. Every
   entry carries its own index tags. `ext:core`, `ext:frontend`, `ext:form` and
   the rest name the system extension a change is **in**. `TCA`, `TypoScript`,
   `Fluid`, `YAML`, `Backend`, `Frontend` name the surface.

   Step 2 picks the package's entries out of that answer by those tags. The tags
   are the system extensions it requires, renders through or registers into, and
   the kinds of file it ships. That costs no further call. An extension key of
   your own is not among them and matches nothing. `tag` narrows one question
   inside a major rather than composes the sweep out of eleven.

   You check the answers against step 2, which is the other half the words did.
   Verify each identifier that comes back in the checkout. A deprecation nothing
   here calls is not a finding.

   Carry the `FullyScanned` / `PartiallyScanned` tag into the answer. It says
   whether the Extension Scanner can find the remaining call sites or whether
   that reading is yours. Bounded this way, you can write the sweep before you
   open a file. That is why it is a step of the order rather than something the
   reading stumbles into.

   **What its silence is worth.** A changelog records change events. So a
   pattern nothing has touched for ten majors has no entry at all. An empty
   sweep is therefore not an answer about what still works. "Does this still
   work in version N" goes to `typo3_documentation_lookup` at that version. Ask
   it here, and whenever the reading raises it again.

   That is a question for a documented surface: a ViewHelper, a TCA type, a
   TypoScript setting. The manual matches page titles, section paths and what
   each manual declares by name, never the text of a page. Declared is a
   property, a class or method the manual documents, a console command. You
   reach one by its own name where the query writes that name the way code does.
   You also reach it where the query is nothing but the name. A PHP identifier
   the manual does not declare has no page named after it.

   An identifier goes to `typo3_changelog_lookup` under its own name. That
   reaches the entries that write it, however the core titled the change. Then
   it goes to the class below. Where the manual has no page for a surface
   either, that is a result and not an answer. Undocumented is not unsupported.

   **A second declared major.** A package that declares more than one asks a
   second question of every deprecation the sweep returns. Is the replacement on
   the lower one? The entry's `issue` is a query of its own, and it reaches
   every entry filed under that number. The Feature the core announced the
   replacement in is among them.

   The version the core released it in settles that question. Where the number
   reaches no sibling, nobody wrote an entry for the replacement.
   `typo3_rule_lookup` with
   `documentId="extension/compatibility/a-declared-major-that-is-not-installed"`
   is the reading that closes it.

   **Where you do not owe the sweep.** A task that produces no change does not
   reach this step at all. The property is what the task produces. A triage, a
   reproduction and a review illustrate it; they are not the list you read it
   off. The sweep asks what a package will have to stop calling. A task that
   writes nothing is not going to call anything.

   The exemption ends where the workflow produces a change. A review asked to
   make the change is that other workflow. It starts this order again with the
   files it is about to write. To carry somebody else's patch onto current code
   is on the same side. It writes commits. The sweep says whether the code that
   moved under the patch deprecated something the patch calls.

   Skip the sweep only where the change touches no TYPO3 API: a code style
   fixer, a CI file, an `.editorconfig`. A deprecation is a statement about API
   the package calls. So a change that calls none has nothing for the sweep to
   land on. The sweep is empty before it runs.

   That condition is worth a statement, because this step is the largest answer
   the order asks for. It is one call per declared major, with that major's
   deprecations whole. You read which side a change falls on off the files it
   touches, never off the task it started as. One PHP file edited along the way
   puts it back among the ordinary ones.

   A skip there costs the deprecation no finding would have walked into. How
   small the change is decides nothing either. Three statements can call a
   deprecated API as easily as three hundred.

   A test file is one of those wherever it sits. It calls the API it exercises
   and the framework around it, and both deprecate. A fixture is exempt where it
   is data the suite reads, and not where it is a class.

**Before the reading**, write down what the order established. That is the
version that filters every later answer, the packages in scope, and the commands
this repository declares. Write down which steps what discharged. Those are
answers already in the session rather than a second reading. What the files show
belongs to the report at the other end. A caller who cannot see what an answer
rests on cannot tell it from one that rests on nothing.

**Then** read the checkout. Not before. A file list first makes everything after
the list look optional. The conventions then arrive as a footnote to a verdict
that has already formed.

**Before the first edit**, name the files this change will create, change or
delete. A deletion is the caller's to ask for, and this is somebody else's
checkout. It is the one act nothing here can put back.

**Last**, the report names every step of this order it did not reach, and what
stood in for it. That is an answer already in the session, a condition that made
the step empty, or an exemption. A reader cannot tell a step passed over in
silence from one somebody dropped.

## When the lookups run out

A behaviour question that survives the lookups above is one you read out of the
installed source. Do not guess at it. The class that implements the behaviour
and the one it inherits from answer it. That reading is the step after the
lookups. It replaces a change to the code until it works.

A first change that did not work is evidence about the reading. So the second
attempt at one failure reads the source rather than changes the code again.

What it settles is what this installation does and never what TYPO3 supports. So
a finding says that you could not settle the question beyond the version
installed. An answer built on the reading names the version it holds for.

## What each runtime lookup adds after the extension answer

`typo3_extension_describe` in step 2 says what one package registers. The
lookups below say what the installation resolved. That is a different fact even
where the words are the same. So step 2 has made none of these calls:

- `typo3_backend_module_lookup` — the tree position, the labels, the access
  level, the routes and the navigation component the parent module supplies.
  Step 2 lists the modules the package declares. A declaration cannot show that
  inheritance.
- `typo3_icon_lookup` — whether any installed package registers an identifier.
  That validates the ones a template uses. Step 2 lists the identifiers this
  package contributes.
- `typo3_label_lookup` — the labels as the installation resolves them, with its
  overrides applied. Step 2 lists the package's XLF files and the source
  language each declares, never what a unit says here.
- `typo3_fluid_namespace_list` — the prefixes any template may use without a
  declaration, from every package at once. Step 2 lists the package's own
  declarations. So an empty list there is no evidence that no package registers
  a prefix globally.
- `typo3_configuration_lookup` — the resolved configuration value, after every
  extension has had its say. For a form data group it gives the order the
  providers really run in. Step 2 answers nothing about that surface at all.
  What a registration declares is not what the installation resolves.
- `typo3_service_lookup` — the class the container really injects for a service
  id, an interface or a tag. Decorations and overrides count. Step 2 lists what
  the package's own `Services.yaml` declares, never what won.
- `typo3_schema_lookup` — the columns TYPO3 derives for a table from its TCA. It
  gives the type, the nullability and the default each one gets. Step 2 lists
  the tables the package registers and nothing about their shape.
- `typo3_flexform_lookup` — the data structure the installation resolves a
  `type=flex` field to, sheet by sheet, with listeners and migrations applied.
  Step 2 lists the content elements a package registers, never the structure
  each one's form builds.
- `typo3_record_lookup` — the rows of any table the installation has TCA for. It
  says how many there are and where they sit. It says what one column holds
  across them and which rows depart from its default. Step 2 has no row in its
  answer at all.

None of these says whether what it reports is right. `typo3_hint_lookup` and
`typo3_documentation_lookup` do. A subsystem its own runtime lookup confirmed
can still break every rule that governs it. So it is not established until you
asked both.

## A rule reads in both directions

It says what new code should do, and it says what this checkout already does
wrong. A file that settled into the opposite of a rule is a finding, not a local
style to preserve. Consistency with a project's own habit establishes nothing
about whether the habit is right.

## What the code is for is evidence, and the repository states it

A mechanism that costs something is not a defect because it costs. Before you
report one, find what it is there for and say so. That is the manual, the
README, the changelog, the setting that drives it, or the declared versions.

Where the documentation states a purpose, what you have is a trade-off, not a
defect. Name it with its cost and its alternative. Where you cannot find one,
the finding says that you could not establish one, not that none exists. If you
skip this, your review is a list of everything the author did on purpose.

## What contradicts the brief goes to the person first

Where the project contradicts the brief, say so before you build on either
reading. This server states what the project holds, and it does not state what
the person meant. Where two answers are both right, name them and ask. A
question after the work is a correction with a sunk cost beside it.

## What a finding rests on is part of the finding

Three things carry one. A file you read, at its path and its line. A command you
ran, with what it printed. A mechanism you traced into an installed package. Say
which of the three it is. If you leave it unsaid, a finding from a CI file
weighs as much as one with a verified line.

Read several files with one call per file, and send the calls together. One
command that prints them all numbers its own output. A line cited from that
output is wrong in every file after the first.

Where one of the project's own commands would settle it, run it.
`typo3_project_describe` marks each command it lists **check**, **change** or
**unknown**, read off the declared body. A check reports and hands the code back
as it was. So even a task told not to change files runs it. The linter the
repository already declares is the cheapest evidence in it.

Do not run a change under that instruction. Name an unknown in the answer as
evidence that is available, and do not run it unasked. An unknown is a test
suite, a shell pipeline, a console command.

What a check prints is not the finding. The configuration that makes it fail is
still what the finding is about. The run takes that finding from derived to
established.

## What this server does not know

It does not read your working tree. You establish which files changed, which
branch you are on, and whether a path or an identifier still exists there. Then
pass the concrete paths back, because that turns a general convention into an
answer about this code.

## Query it in English

The knowledge is English and the match is lexical. So a query in another
language reaches the loanwords the two happen to share and nothing else.
Translate the subject before the call and the answer back afterwards, whatever
language you speak with the user.
```
