Adobe Commerce Cloud Deployment

Deploying a Hyvä theme to Adobe Commerce Cloud requires specific configuration to generate the Tailwind CSS production stylesheet during the build phase. Unlike traditional hosting environments, Adobe Commerce Cloud uses a containerized build process where Node.js must be installed dynamically, and stylesheets must be generated before the static content deployment step runs.

This guide covers configuring .magento.app.yaml build hooks, setting up Composer authentication for the Hyvä private packagist, and ensuring all required files are available during deployment.

Tailwind Stylesheet Generation

Tailwind v4 Compatibility

Tailwind v4 source merging does not work with the default Adobe Commerce Cloud .gitignore file. See The .gitignore file for Tailwind 4 support for the solution.

When the production Tailwind CSS stylesheet (styles.css) is not committed to version control, Adobe Commerce Cloud must generate it during the build phase. The build hook must install Node.js, run the Tailwind build process, and clean up before the application is packaged.

The following .magento.app.yaml configuration installs Node.js 20 via NVM (Node Version Manager), creates the required output directory, installs Tailwind dependencies, builds the production stylesheet, and removes the node_modules directory to reduce deployment size:

...

hooks:
    # build hooks run before the application has been packaged
    build: |
        ...

        # install latest nvm and node 20 (LTS version)
        unset NPM_CONFIG_PREFIX
        curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
        export NVM_DIR="$HOME/.nvm"    
        [ -s "$NVM_DIR/nvm.sh"  ] && . "$NVM_DIR/nvm.sh"
        nvm install 20

        # create required directory
        mkdir -p app/design/frontend/{VENDOR}/{THEME}/web/css/

        # install Tailwind dependencies
        npm --prefix app/design/frontend/{VENDOR}/{THEME}/web/tailwind/ install

        # build Tailwind production stylesheet
        npm --prefix app/design/frontend/{VENDOR}/{THEME}/web/tailwind/ run build

        # cleanup
        rm -rf app/design/frontend/{VENDOR}/{THEME}/web/tailwind/node_modules/
        rm -rf ~/.nvm/
        ...

Integrating with ECE-Tools

When using Adobe Commerce Cloud's ECE-Tools, the Hyvä Tailwind build must execute before the static content deployment phase. If the stylesheet is generated after ece-tools run scenario/build/generate.xml runs, the CSS file will not be included in the deployed static assets.

The following example shows an example section of the build hook configuration with Composer install, the location for the Hyvä Tailwind build steps, and ECE-Tools scenarios in the correct order:

...

hooks:
    # build hooks run before the application has been packaged
    build: |
        set -e
        composer --no-ansi --no-interaction install --no-progress --prefer-dist --optimize-autoloader --no-dev

        ... steps from above ...

        php ./vendor/bin/ece-tools run scenario/build/generate.xml
        php ./vendor/bin/ece-tools run scenario/build/transfer.xml
    deploy: |
        ...

Composer Authentication for Hyvä Packages

Adobe Commerce Cloud requires authentication credentials to download Hyvä packages from the private Hyvä packagist repository during composer install. There are two approaches to provide these credentials: committing an auth.json file or using environment variables.

Option 1: Commit auth.json with Repository Configuration

Add a repository entry in composer.json for the Hyvä private packagist, then commit the auth.json file containing your Hyvä license credentials. Replace {{MERCHANT-ID}} with your Hyvä merchant ID from the license portal:

...
"repositories": {
    ...
    "hyva-private-packagist": {
        "type": "composer",
        "url": "https://hyva-themes.repo.packagist.com/{{MERCHANT-ID}}/",
        "only": [
            "hyva-themes/*"
        ]
    },
    ...
},
...

Option 2: Use COMPOSER_AUTH Environment Variable

If you prefer not to commit credentials to the repository, set the COMPOSER_AUTH environment variable at the PROJECT level (not the ENVIRONMENT level) in the Adobe Commerce Cloud console. This variable should contain the JSON-encoded authentication credentials that would otherwise be in auth.json.

Committing the hyva-themes.json Configuration File

The app/etc/hyva-themes.json file contains the Tailwind CSS source path configuration for all installed Hyvä modules. Normally this file is generated by running bin/magento hyva:config:generate after Magento is installed.

On Adobe Commerce Cloud, the build phase runs before Magento is fully installed, so this file cannot be generated during deployment. The solution is to commit app/etc/hyva-themes.json to your repository after generating it locally. Without this file, the Tailwind build process will not find the required source files and the stylesheet compilation will fail.

Fixing .gitignore for Tailwind v4 Compatibility

Tailwind v4 introduces the @source directive for automatic content path discovery, which respects .gitignore patterns when determining which files to scan. The default Adobe Commerce Cloud .gitignore uses an "allow-list" approach that breaks this feature.

The Problem

Adobe Commerce Cloud's default .gitignore starts with a wildcard * to ignore all files, then selectively un-ignores specific files and directories. Tailwind v4 interprets this pattern literally: because * matches everything including the vendor/ directory, Tailwind cannot access parent theme files such as vendor/hyva-themes/magento2-default-theme.

This causes the Tailwind build to fail when your child theme references the Hyvä Default Theme or any other themes in the vendor directory.

The Solution

Replace the Adobe Commerce Cloud .gitignore with a "deny-list" approach that explicitly lists files and directories to ignore, rather than ignoring everything by default. Use the standard Magento 2 .gitignore as a starting point.

This approach allows Tailwind v4's @source directive to correctly resolve paths while still excluding generated files and vendor dependencies from version control.