Adobe Commerce Cloud Deployment

Tailwind Stylesheet Generation

Warning

Tailwind v4 merging does not work with the default .gitignore from Adobe Cloud.
See the docs below how to resolve this.

For Hyvä projects on Magento Cloud, if the production stylesheet is not kept in version control, there are a few additional steps required to generate it during deployment.

Add the following code to the .magento.app.yaml file:

...

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/
        ...

If you run the ece-tools, make sure you run the Hyva scripts first. Otherwise, the style is built after the static content is deployed, and you get no stylesheets. Final .magento.app.yaml section should look similar to this:

...

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 Authorization

One possible approach is to commit the auth.json file to git and add a repository entry in composer.json for the Hyvä packagist:

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

Setting the COMPOSER_AUTH variable on the PROJECT level (not on the ENVIRONMENT level) is also an option if the auth.json should not be committed to the repository.

The app/etc/hyva-themes.json file

The file needs to be generated after Magento is installed, so it can't be run during the build phase. This means, for Adobe Commerce Cloud projects, the app/etc/hyva-themes.json file needs to be commited to the repository.
Otherwise the file will be missing during the compilation of the styles.

The .gitignore file for Tailwind 4 support

The default .gitignore file provided by Adobe Commerce Cloud uses a wildcard * to ignore all files, and then selectively un-ignores files that should be committed.

This approach can cause problems with Tailwind v4's @source feature, which ignores files listed in .gitignore.
As the wildcard * ignores everything (not just directories), this prevents Tailwind from accessing necessary files, for example, within the vendor/ directory.

This may break the Tailwind build process if your theme references other themes, for example, the Hyvä Default Theme in vendor/hyva-themes/magento2-default-theme.

To resolve this, you should use a .gitignore file that explicitly lists the files and directories to be ignored, rather than ignoring everything and then un-ignoring. This is a "deny-list" approach, which is more compatible with tools that need to scan the project structure.

You can use the standard Magento 2 .gitignore as a starting point. This file is well-maintained and follows the recommended practices for a Magento 2 project.

By using this .gitignore, you ensure that tools like Tailwind can correctly resolve @source paths, while still keeping your repository clean from generated files and vendor dependencies.