--- title: "Installation" manual: "TYPO3 Astryx" version: "main" permalink: "https://docs.typo3.org/permalink/skom/typo3-astryx:installation@main" source: "Installation/Index.rst" rendered: "2026-11-01T11:49:05+00:00" --- # Installation {#installation} This chapter describes how to install and set up TYPO3 Astryx (`skom/typo3-astryx`) in a TYPO3 v14 project. ## Prerequisites {#installation-prerequisites} ### System Requirements {#system-requirements} - **PHP**: `>= 8.3 < 8.5` - **TYPO3 Core**: `~14.3.0` (including `typo3/cms-core`, `typo3/cms-fluid`, `typo3/cms-frontend`, and `typo3/cms-rte-ckeditor`) - **MariaDB** or **MySQL**: MariaDB 10.6+ or MySQL 8.0+ ### Required TYPO3 Extensions {#required-typo3-extensions} TYPO3 Astryx requires the following Composer packages: - `friendsoftypo3/content-blocks`: `^2.4.10` (provides the Content Blocks schema and rendering) - `b13/container`: `^4.1` (powers multi-column and single-column container elements) - `skom/stylex-connector`: `^1.1.2` (bridges TYPO3 Fluid with the StyleX manifest) - `praetorius/vite-asset-collector`: `^1.18` (asset collection and Vite integration) ### Conflict with Fluid Styled Content {#conflict-with-fluid-styled-content} > [!IMPORTANT] > **TYPO3 Astryx explicitly conflicts with Fluid Styled Content (FSC).** > > Astryx is designed to completely replace `typo3/cms-fluid-styled-content`. Both extensions > cannot be active simultaneously. Before installing Astryx, remove FSC from your Composer > dependencies and remove its Site Set / TypoScript imports from your site configuration. ### Frontend Build Requirements (Optional) {#frontend-build-requirements-optional} If you use the default packaged assets, no Node.js runtime or build step is required. If you compile custom StyleX styles or consume the extension through Vite: - **Node.js**: `v22.x` - **Vite**: `^7.3.0` - **StyleX Compiler**: `@stylexjs/stylex: 0.19.1`, `@stylexjs/unplugin`, and `@babel/parser` ## Installing in a New Project {#installation-steps} ### Step 1: Require the Package via Composer {#step-1-require-the-package-via-composer} Run Composer from your project root: ```bash # If fluid-styled-content is installed, remove it first: composer remove typo3/cms-fluid-styled-content # Require TYPO3 Astryx and its pinned dependencies: composer require skom/typo3-astryx ``` Ensure that `skom/stylex-connector` is referenced at `^1.1.2` in your root `composer.json`: ```json "require": { "skom/typo3-astryx": "^0.1.0", "skom/stylex-connector": "^1.1.2" } ``` ### Step 2: Activate the Site Set {#step-2-activate-the-site-set} TYPO3 Astryx provides a reusable Site Set named `skom/typo3-astryx`. #### Option A: In Your Site Package {#option-a-in-your-site-package} In your custom site package's Site Set configuration (`packages/my_sitepackage/Configuration/Sets/SitePackage/config.yaml`), declare the dependency: ```yaml name: my-vendor/site-package label: 'My Site Package' dependencies: - skom/typo3-astryx ``` #### Option B: In the Site Configuration Directly {#option-b-in-the-site-configuration-directly} Alternatively, add the Site Set directly to your site configuration in `config/sites//config.yaml`: ```yaml dependencies: - skom/typo3-astryx ``` ### Step 3: Update Database Schema and Clear Caches {#step-3-update-database-schema-and-clear-caches} Apply the database schema additions and flush system caches: ```bash vendor/bin/typo3 cache:flush vendor/bin/typo3 extension:setup ``` > [!NOTE] > `vendor/bin/typo3 extension:setup` creates the required database tables, including the > Content Block collection tables (`tx_astryx_list_item`, `tx_astryx_table_item`, > `tx_astryx_table_cell`, `tx_astryx_card_grid_item`, `tx_astryx_accordion_item`, > and `tx_astryx_carousel_item`). ### Step 4: Select Asset Delivery Mode {#step-4-select-asset-delivery-mode} Astryx supports two asset delivery modes: 1. **Packaged Assets (Default)**: Pre-compiled frontend and editor stylesheets/scripts are served directly from `EXT:typo3_astryx/Resources/Public/Assets/`. This mode requires no Node build pipeline on your web server. Site setting: `Astryx.useVite: false`. 1. **Consuming Vite Integration**: The consuming site package compiles frontend assets via Vite and `praetorius/vite-asset-collector`, reading from `Configuration/ViteEntrypoints.json`. Site setting: `Astryx.useVite: true`. ## Migrating an Existing FSC Site {#installation-migration} If you are migrating an existing TYPO3 site from `typo3/cms-fluid-styled-content` to Astryx, follow this structured migration workflow: ### Workflow Steps {#workflow-steps} 1. **Full Backup**: Export your database (`mysqldump`) and create a full backup of `fileadmin/` and FAL storages. Record the current Composer lock state and Git commit hash. 1. **Inventory Records**: Audit all existing `tt_content` records, checking for CTypes, hidden/deleted records, workspace versions, and multi-language records. 1. **Rehearse in an Isolated Environment**: Perform the migration first on a staging or local DDEV fixture before touching production. 1. **Switch Composer Requirements**: Remove `typo3/cms-fluid-styled-content` and add `skom/typo3-astryx` in the same Composer operation: ```bash composer remove typo3/cms-fluid-styled-content composer require skom/typo3-astryx composer update ``` 1. **Flush Caches and Apply Schema**: ```bash vendor/bin/typo3 cache:flush vendor/bin/typo3 extension:setup ``` 1. **Run Migration Dry Run**: Execute the migration console command in dry-run mode (read-only): ```bash vendor/bin/typo3 astryx:migrate ``` Review the JSON output. If any records appear under `manualReview`, investigate them. The migration tool refuses to apply changes if unsupported types, deleted records, or draft workspace versions are detected. 1. **Apply Migration with Report**: When all records are accounted for, run the migration with `--apply` and a mandatory absolute path for the audit report file: ```bash vendor/bin/typo3 astryx:migrate --apply --report=/var/backup/astryx-migration-report.json ``` > [!WARNING] > **Caution** > > The report file path must be absolute, must **not** already exist, and must be located > **outside** the web root (outside `public/`). It saves the full pre-migration state > of every modified record before writing changes through TYPO3's `DataHandler`. 1. **Verify and Flush**: Flush caches and run a second dry run, which should report zero pending changes: ```bash vendor/bin/typo3 cache:flush vendor/bin/typo3 astryx:migrate ``` ### CType Mapping Matrix {#ctype-mapping-matrix} The migration command maps supported legacy FSC content types losslessly: | FSC Source CType | Astryx Target CType | Handling & Notes | | --- | --- | --- | | `header` | `astryx_heading` | Preserves core header, layout, link, etc. | | `text` | `astryx_text` | Preserves core bodytext and RTE formatting | | `textmedia`, `textpic`, `image` | `astryx_textmedia` | Preserves FAL image and assets relations, bodytext, and orientation settings | | `div` | `astryx_divider` | Maps to Astryx horizontal divider | | `uploads` | `astryx_downloads` | Preserves core `media` FAL file relations | | `menu_sitemap`, `menu_subpages`, `menu_pages` | Retained CType (same CType identifier) | Rendered with native Astryx components (`astryx:treeList`, `astryx:sideNav`) | | `shortcut` | Retained CType | Uses native RECORDS reference renderer | | `html` | Retained CType | Rendered with sanitized HTML standard wrap | | `bullets`, `table` | Manual Conversion | Convert manually to Collection-based list / table Content Blocks | | Dedicated Plugins | Unchanged | Plugin registration is fully preserved | ## Rollback Procedure {#installation-rollback} If you must revert a migration: 1. Restore the prior Git commit and Composer lock file. 1. Run `composer install`. 1. Restore the database dump and FAL storage backup taken prior to migration. 1. Flush caches: `vendor/bin/typo3 cache:flush`. 1. Verify that legacy FSC rendering is restored. > [!NOTE] > Do not attempt to replay the JSON migration report directly back into a database where > TCA definitions have changed. Full recovery relies on the database dump.