Adobe Commerce Cloud Deployment

Deploying a Hyvä theme on Adobe Commerce Cloud involves specific steps to generate the Tailwind CSS production stylesheet. Due to ACC's containerized build process, Node.js must be dynamically installed, and stylesheets generated before static content deployment.

This guide details configuring .magento.app.yaml build hooks, setting up Composer authentication for the Hyvä private packagist, and managing essential files for successful deployment.

Tailwind Stylesheet Generation

If your production Tailwind CSS stylesheet (styles.css) is not committed to version control, Adobe Commerce Cloud must generate it during the build phase. This requires a build hook to install Node.js, execute the Tailwind build, and perform cleanup before packaging the application.

The .magento.app.yaml configuration below demonstrates how to install Node.js 20 (via NVM), create the necessary output directory, install Tailwind dependencies, build the production stylesheet, and remove node_modules to optimize 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 complete before the static content deployment phase. Generating the stylesheet after ece-tools run scenario/build/generate.xml will prevent the CSS file from being included in your deployed static assets.

The following example illustrates the correct order within the build hook configuration, including Composer install, the Hyvä Tailwind build steps, and ECE-Tools scenarios:

...

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 needs authentication credentials to download Hyvä packages from the private Hyvä packagist during composer install. You can provide these credentials using two methods: committing an auth.json file or using environment variables.

Option 1: Commit auth.json with Repository Configuration

First, add a repository entry for the Hyvä private packagist in your composer.json. Then, commit an auth.json file containing your Hyvä license credentials. Remember to 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 directly to your repository, set the COMPOSER_AUTH environment variable at the PROJECT level (not ENVIRONMENT level) in the Adobe Commerce Cloud console. This variable should contain the JSON-encoded authentication credentials, mirroring what would be in an auth.json file.

Committing the hyva-themes.json Configuration File

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

However, on Adobe Commerce Cloud, the build phase occurs before Magento is fully installed, preventing this file from being generated during deployment. Therefore, you must generate app/etc/hyva-themes.json locally and commit it to your repository. Without it, the Tailwind build process will fail to find necessary source files, and stylesheet compilation will not complete.

Fixing .gitignore for Tailwind v4 Compatibility

Tailwind v4's new @source directive automatically discovers content paths, respecting .gitignore patterns during file scanning. The default Adobe Commerce Cloud .gitignore uses an 'allow-list' approach that interferes with this feature.

The Problem

Adobe Commerce Cloud's default .gitignore begins by ignoring all files (*), then selectively un-ignores specific ones. Tailwind v4 interprets this literally: the * pattern matches the vendor/ directory, preventing Tailwind from accessing parent theme files like vendor/hyva-themes/magento2-default-theme.

Consequently, the Tailwind build fails if your child theme references the Hyvä Default Theme or any other themes within the vendor directory.

The Solution

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

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