Building extensions and creating archives

Extensions consists of PHP Changes, JavaScript and CSS. To release an extension to the Shopware Store or upload it to a Shopware 6 instance without having to rebuild Storefront and Administration your extension needs to provide the compiled assets.

Building an extension

Shopware-CLI allows you to easily build the assets of an extension. To build an extension, you can use the following command:

shopware-cli extension build <path>

Shopware-CLI reads the shopware/core requirement from composer.json or manifest.xml and builds the assets using the lowest compatible Shopware version. This ensures the extension remains usable across multiple Shopware versions. If the selected version is incorrect, you can override it using a .shopware-extension.yml file.

# .shopware-extension.yml
build:
  shopwareVersionConstraint: '6.6.9.0'

This only affects the build process and not on the installation of the extension. For full control you can also specify the environment variable SHOPWARE_PROJECT_ROOT pointing to a Shopware 6 project, and it will use that Shopware to build the extension assets.

Additional bundles

If your plugin consists of multiple bundles, usually when you have implemented getAdditionalBundles in your Plugin class, you have to provide the path to the bundle you want to build in the config:

# .shopware-extension.yml
build:
  extraBundles:
    # Assumes the bundle name is the same as the directory name
    - path: src/Foo
    # Explictly specify the bundle name
    - path: src/Foo
      name: Foo

Using esbuild for JavaScript Bundling

WARNING

Building with esbuild works completely standalone without the Shopware codebase. This means if you import files from Shopware, you have to copy it to your extension.

Esbuild can be utilized for JavaScript bundling, offering a significantly faster alternative to the standard Shopware bundling process, as it eliminates the need to involve Shopware for asset building.

# .shopware-extension.yml
build:
  zip:
    assets:
      # Use esbuild for Administration
      enable_es_build_for_admin: true
      # Use esbuild for Storefront
      enable_es_build_for_storefront: true

Creating an archive

To create an archive of an extension, you can use the following command:

shopware-cli extension zip <path>

The command copies the extension to a temporary directory, builds the assets, deletes unnecessary files and creates a zip archive of the extension. The archive is placed in the current working directory.

By default the command picks the latest released git tag, use --disable-git as flag to disable this behavior and use the current source code. Besides disabling it completely, you can also specify a specific tag or commit using --git-commit.

Bundling composer dependencies

Before Shopware 6.5, bundling the composer dependencies into the zip file is required. Shopware-CLI automatically runs composer install and removes duplicate composer dependencies to avoid conflicts.

To disable this behavior, you can adjust the configuration:

# .shopware-extension.yml
build:
  zip:
    composer:
      enabled: false

This is automatically disabled for plugins targeting Shopware 6.5 and above and executeComposerCommands should be used instead.

Delete files before zipping

Shopware-CLI deletes a lot of known files before zipping the extension. If you want to delete more files, you can adjust the configuration:

# .shopware-extension.yml
build:
  zip:
    pack:
      excludes:
        paths:
          - <path>

JavaScript Build optimization

If you bring additional NPM packages, make sure that you added only runtime dependencies to dependencies inside package.json and tooling to devDependencies and enabled npm_strict in the configuration:

# .shopware-extension.yml
build:
  zip:
    assets:
      npm_strict: true

This skips unnecessary npm install and npm ci commands and only installs the runtime dependencies.

Release mode

If you are building an archive for distribution, you can enable the release mode with the flag --release. This will remove the App secret from the manifest.xml and generate changelog files if enabled.

The changelog generation can be enabled with the configuration:

# .shopware-extension.yml
changelog:
  enabled: true

It utilizes the commits between the last tag and the current commit to generate the changelog. Additionally, it can be configured to filter commits and build the changelog differently.

changelog:
  enabled: true
  # only the commits matching to this regex will be used
  pattern: '^NEXT-\d+'
  # variables allows to extract metadata out of the commit message
  variables:
    ticket: '^(NEXT-\d+)\s'
  # go template for the changelog, it loops over all commits
  template: |
    {{range .Commits}}- [{{ .Message }}](https://issues.shopware.com/issues/{{ .Variables.ticket }})
    {{end}}

This example checks that all commits in the changelog needs to start with NEXT- in the beginning. The variables section allows to extract metadata out of the commit message. The template is a go template which loops over all commits and generates the changelog. With the combination of pattern, variables and template we link the commit message to the Shopware ticket system.

Overwrites

Extension configuration can be overwritten during the zipping process, allowing changes to aspects such as the version and app-related settings.

shopware-cli extension zip --overwrite-version=1.0.0 <path>

Replaces the version in composer.json or manifest.xml with the given version.

shopware-cli extension zip --overwrite-app-backend-url=https://example.com <path>

Replaces all external URLs in manifest.xml to that given URL.

shopware-cli extension zip --overwrite-app-backend-secret=MySecret <path>

Replaces the App secret in manifest.xml with the given secret.