Packages | Automad

All themes and extensions are distributed as packages. A package is simply a directory inside the packages directory of an Automad installation that contains a composer.json file. A single package can contain one or more themes, extensions, block templates and snippets at the same time. Automad uses Composer as dependency manager. Therefore releasing a package basically works the same as for any other Composer package.

The composer.json File

Every package needs a composer.json file in its root directory. The following example shows the minimal configuration of a theme package:

{
  "name": "vendor/theme-name",
  "description": "Your description ...",
  "type": "automad-package",
  "keywords": ["theme"],
  "license": "MIT",
  "require": {
    "automad/package-installer": "^1.1"
  }
}

name: The name of the package in the form of vendor/package. Only lowercase letters, numbers, dots, dashes and underscores are allowed.
description: A short description of the package that is displayed in the package manager.
type: The type always has to be automad-package. That makes sure that the package is installed into the packages directory instead of the vendor directory.
keywords: Keywords like theme or extension help to classify your package.
require: The automad/package-installer package is required in order to install a package into the correct location and must not be removed. You can of course add other dependencies as well.
autoload: Extension packages should also define an autoload configuration, like "classmap": [""], so that their classes can be loaded by Composer.

Installing Packages

There are several ways of getting a package into an Automad installation, depending on whether a package is public, private or still in development.

Package Manager

Public packages that are listed in the Automad package registry can be browsed and installed directly in the Packages section of the dashboard. Installed packages can also be updated there.

Private Repositories

Packages that are hosted in private repositories on GitHub or GitLab can be installed as well. Go to Packages → Private Repositories in the dashboard and add the repository by its name, URL and branch. In order to grant access, create a read-only access token on GitHub or GitLab and add it in the dashboard. Private packages can then be installed and updated just like public ones.

Manual Installation

During development or for packages that are not hosted anywhere, a package can simply be copied into the packages directory, for example using SFTP or rsync. Such local packages are detected automatically. The deployment of a theme using rsync can for example be automated with a GitHub workflow, as it is described in the Starter Kit readme.

rsync -av --delete ./ user@server:/path/to/automad/packages/vendor/theme-name/

Publishing Packages

In order to make a package available to everyone, it has to be released as a public Composer package. The basic requirements are:

A valid composer.json file as described above.
A README.md file with a description of your package and instructions for using it. For themes, it is recommended to include some preview images in order to quickly give people an idea of the look and feel of your design.
A public repository, for example on GitHub, that is registered on Packagist.
Releases that are tagged following the semantic versioning convention, so that the package manager can detect updates.