Warning This project is on the backburner due to higher priority projects. Putting in maintenance mode until PayloadCMS 3.0 is released.
PayloadThemes is a CLI application to simplify the implementation and communal sharing of PayloadCMS themes. The CLI is currently in a private repo and will be added here as time allows. Until then, this repo qualifies as "Stupid/awesome GitHub tricks." Rather than using a dedicated file storage service like AWS, Azure, Vercel, etc, everything is managed and version controlled through GitHub. A theme developer makes a pull request with a SCSS file, GitHub Actions parses it, places the file appropriately in the repo, then updates the manifest file. Any necessary metadata is provided in comments at the top of the SCSS file. The payloadthemes CLI keeps up with the available themes by reading the manifest, providing options to the user, and downloading the appropriate SCSS file from this repo.
PayloadCMS is a great content management system! However the UI is very distinctive and, perhaps, not to everyone's tastes. There are a number of boiler-plate, opaque, and onerous steps you'll need to do for significant visual overhauls. PayloadCMS has no current theme marketplace or repository.
- Kick off the CLI without downloading
npx payloadthemesor installnpm add -D payloadthemes- The app will create a themes directory and add an overrides entry in your Payload config file (if it doesn't already exist). This is non-disruptive and won't otherwise break anything.
- The app will read the
manifest.jsonfile from this github repository
- Select the theme you want
- The app will download the theme's
.scssfile to the themes directory - The app will update the payload config to point to the new
.scssfile. Note that the downloaded theme will have its own name to allow easily reverting to the prior theme.
- The app will download the theme's
- Restart your payload project to see the new changes
This project uses a GitHub Actions workflow to automatically process theme submissions and update a manifest file. This allows theme developers to easily contribute new themes while maintaining an up-to-date catalog for CLI tools to access.
The workflow is triggered whenever a push is made to the repository that includes changes to SCSS files in the themes/ directory. Here's what the workflow does:
-
Theme Processing:
- Parses each SCSS file in the
themes/directory. - Extracts metadata (theme name, description, author, version) from the file comments.
- Generates a download link for each theme.
- Parses each SCSS file in the
-
Manifest Generation:
- Creates or updates a
manifest.jsonfile. - Adds an entry for each theme with its metadata and download link.
- Creates or updates a
-
Automatic Commit and Push:
- Commits the updated
manifest.jsonfile. - Pushes the changes back to the repository.
- Commits the updated
- The workflow is defined in
.github/workflows/update-manifest.yml. - It uses a custom bash script (
scripts/process_themes.sh) to process the themes and generate the manifest. - The script reads the first four lines of each SCSS file to extract metadata:
- Line 1: Theme name
- Line 2: Description
- Line 3: Author
- Line 4: Version
- A download link is generated for each theme, pointing to the raw file in the repository.
- The manifest is updated with the new or changed theme information.
- Changes are committed and pushed back to the repository automatically.
To submit a new theme or update an existing one:
-
Create or modify an SCSS file in the
themes/directory. -
Ensure the first four lines of your SCSS file contain the required metadata:
/* MyTheme */ /* A brief description of the theme */ /* Author Name */ /* 1.0.0 */
-
Commit and push your changes to the repository.
-
The GitHub Action will automatically process your theme and update the manifest.
The manifest.json file at the root of the repository contains up-to-date information about all available themes. You can use this file to retrieve theme metadata and download links for integration with your CLI tools.
This automated process ensures that the theme catalog stays current with minimal manual intervention, facilitating easy theme submission for developers and providing reliable, up-to-date information for CLI tools.
- Add params to allow initialization only, i.e.
npx payloadthemes --init - Use semantic versioning in the manifest and denote upgrades
- Add support for themes that overwrite (or add) components
- Diff the current version of the theme and confirm for overwrite
- Establish conventions for easily modified elements (such as color)
- Add mechanism to add screenshots for a theme
- Finish README.md
- Add license (MIT)
- Publish to npm