Adobe Commerce Cloud Deployment

Deploying a Hyvä theme to Adobe Commerce Cloud requires special build configuration to generate Tailwind CSS stylesheets during the Cloud deployment process. Adobe Commerce Cloud uses a containerized build environment that differs from traditional hosting: Node.js is not pre-installed, the build phase runs before Magento is fully initialized, and generated files must be created during specific build hooks or they won't be included in deployed static assets.

This guide explains how to configure Adobe Commerce Cloud deployment for Hyvä themes. You'll learn to configure .magento.app.yaml build hooks for Tailwind CSS compilation, set up Composer authentication for Hyvä private packagist packages, commit required configuration files that can't be generated during Cloud builds, and fix .gitignore compatibility issues for Tailwind v4 source path resolution.

Tailwind CSS Stylesheet Generation in Build Hooks

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 using build hooks in .magento.app.yaml. The Tailwind CSS build process requires Node.js to compile the stylesheet from source files, but Adobe Commerce Cloud containers don't include Node.js by default, so the build hook must install it dynamically.

Configuring the Build Hook for Tailwind CSS Compilation

The following .magento.app.yaml build hook configuration performs the complete Tailwind CSS build process during Adobe Commerce Cloud deployment. This configuration installs Node.js 20 (LTS version) via NVM (Node Version Manager), creates the required output directory for compiled CSS, installs Tailwind dependencies from package.json, runs the Tailwind build script to generate the production stylesheet, and removes the node_modules directory to reduce the deployed artifact size.

Replace {VENDOR} and {THEME} with your theme's vendor name and theme name:

...

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

        # Install Node.js via NVM (Node Version Manager)
        # Unset NPM_CONFIG_PREFIX to avoid conflicts with system npm
        unset NPM_CONFIG_PREFIX
        # Download and execute NVM installation script
        curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
        # Load NVM into the current shell session
        export NVM_DIR="$HOME/.nvm"
        [ -s "$NVM_DIR/nvm.sh"  ] && . "$NVM_DIR/nvm.sh"
        # Install Node.js 20 LTS (required for Tailwind CSS CLI)
        nvm install 20

        # Create output directory for compiled CSS file
        # Adobe Commerce Cloud build containers don't include theme directories by default
        mkdir -p app/design/frontend/{VENDOR}/{THEME}/web/css/

        # Install Tailwind CSS and PostCSS dependencies from package.json
        npm --prefix app/design/frontend/{VENDOR}/{THEME}/web/tailwind/ install

        # Run the Tailwind CSS build script to compile styles.css
        # This executes the "build" script defined in package.json
        npm --prefix app/design/frontend/{VENDOR}/{THEME}/web/tailwind/ run build

        # Clean up to reduce deployed artifact size
        # Remove node_modules directory (dependencies not needed at runtime)
        rm -rf app/design/frontend/{VENDOR}/{THEME}/web/tailwind/node_modules/
        # Remove NVM installation (Node.js not needed after build)
        rm -rf ~/.nvm/
        ...

Integrating Tailwind CSS Build with ECE-Tools

When using Adobe Commerce Cloud's ECE-Tools, the Hyvä Tailwind CSS 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 discovered by static content deployment and won't be included in the deployed static assets.

The following example shows the complete build hook configuration with Composer install, Hyvä Tailwind CSS build steps (inserted at the correct position), and ECE-Tools scenarios in the proper execution 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.

Troubleshooting: Fixing .gitignore for Tailwind v4 Compatibility

Tailwind v4 introduces the @source directive for automatic content path discovery in source CSS files. This directive respects .gitignore patterns when determining which files to scan for Tailwind classes. Adobe Commerce Cloud's default .gitignore file uses an "allow-list" approach that conflicts with Tailwind v4's source path resolution, causing build failures.

The Problem: Allow-List .gitignore Blocks Tailwind v4 Source Resolution

Adobe Commerce Cloud's default .gitignore file starts with a wildcard * pattern to ignore all files, then selectively un-ignores specific files and directories using ! negation patterns. This allow-list approach creates a problem for Tailwind v4: the initial * pattern matches everything including the vendor/ directory, and Tailwind v4 interprets this literally when resolving @source paths.

When your Hyvä child theme's tailwind-source.css uses @source to include parent theme files from vendor/hyva-themes/magento2-default-theme, Tailwind v4 cannot access those files because .gitignore marks the entire vendor/ directory as ignored. This causes the Tailwind CSS build to fail during Adobe Commerce Cloud deployment.

The Solution: Use Deny-List .gitignore Pattern

Replace the Adobe Commerce Cloud .gitignore file with a "deny-list" approach that explicitly lists files and directories to ignore, rather than ignoring everything by default and then selectively un-ignoring paths. Use the standard Magento 2 .gitignore as a starting point, which lists specific paths to ignore (generated files, caches, IDE files) without using a catch-all wildcard at the beginning.

This deny-list approach allows Tailwind v4's @source directive to correctly resolve vendor paths for parent theme files while still excluding generated files and build artifacts from version control.