Ghost Release: 3.22.0

TL;DR

Ghost 3.22.0: Settings Refactoring & Stripe Connect Integration

Ghost 3.22.0 introduces significant changes to the settings architecture and enables Stripe Connect by default. This release includes extensive refactoring of the settings table structure, improved handling of image paths in subdirectory setups, and better API property access. However, there is a known issue with settings in this version that users should be aware of, making it advisable to skip to a later version.

Highlight of the Release

• Stripe Connect is now enabled by default, replacing the previous API key UI
• Extensive refactoring of the settings table structure with new columns and naming conventions
• Fixed image handling in subdirectory setups and image cards
• Improved access property availability across the API
• Route ordering changed to prioritize posts over taxonomies when routes overlap

Migration Guide

Settings Refactoring

Several settings keys have been renamed for consistency:

• default_locale → lang
• active_timezone → timezone
• ghost_head → codeinjection_head
• ghost_foot → codeinjection_foot
• brand.publicationColor → accent_color
• members_allow_signup → members_allow_free_signup

The settings table structure has been updated with new columns:

• group: Replaces the type column with more descriptive grouping
• flags: Indicates special handling (e.g., PUBLIC, RO)
• type: Specifies data type (string, number, boolean, array)

Stripe Connect

Stripe Connect is now enabled by default. If you were using the previous API key integration method, you'll need to:

1. Navigate to the Ghost Admin settings
2. Go to the Membership settings section
3. Follow the new Stripe Connect flow to reconnect your Stripe account

Known Issues

⚠️ There is an issue with settings in 3.22.0. It is recommended to skip this version and update directly to the latest version.

Upgrade Recommendations

⚠️ IMPORTANT: It is strongly recommended to skip version 3.22.0 due to a known issue with settings (GitHub issue #12020). Please update directly to the latest version instead.

If you must upgrade to this version:

• Take a complete backup of your Ghost installation and database before upgrading
• Be prepared for potential issues with settings functionality
• Plan to upgrade to a newer version as soon as possible

For developers working with custom themes or integrations:

• Review your code for any direct references to renamed settings keys
• Test thoroughly with the new settings structure
• Be aware of the route priority changes if you have custom routes that might conflict

Bug Fixes

• Image Handling:

  • Fixed potentially squashed images in image cards by removing automatic width/height attributes
  • Fixed populateImageSizes handling of images in subdirectory setups
  • Fixed Facebook/Twitter images having relative URLs in API output

• Access Property:

  • Moved access property to the API level, making it available in more contexts (post loops, get helper)
  • Updated logic to use the same membersHasAccess logic as post gating

• Route Handling:

  • Reordered routes to load taxonomies last, ensuring posts take priority when routes overlap
  • Fixed issue where /edit route would default to looking up tags

• Settings and Migrations:

  • Fixed migration handling when brand setting is null
  • Fixed migration exiting for single missing setting
  • Fixed default values for various settings
  • Fixed grouping error in members CSV importer

• Member Import:

  • Refined error messages for member import post-validation
  • Fixed Stripe error detection in member imports

New Features

• Stripe Connect Integration: Enabled by default, replacing the old API Key UI with a new Stripe Connect flow
• Settings Architecture Overhaul:
  • Added new columns to settings table: group, flags, and type
  • Implemented explicit typing for settings (string, number, boolean, array)
  • Added flags to indicate special handling (e.g., PUBLIC, RO for read-only)
• Improved Settings Organization:
  • Renamed settings groups for clarity (e.g., blog → site, bulk_email → email)
  • Reorganized settings into more appropriate groups
• Enhanced Permissions Management:
  • Added new migration utilities for permissions that interact directly with the database
• Optimized Favicon Handling:
  • Custom favicons now only output link tags when needed, improving page load efficiency

Security Updates

No specific security fixes were mentioned in this release.

Performance Improvements

• Favicon Optimization: Updated head to only output custom favicon links when needed, reducing unnecessary HTML and browser requests
• Settings Handling: More efficient settings organization and access patterns through the refactored settings architecture
• Database Interactions: Direct database interactions for permissions and settings population, reducing overhead from the model layer

Impact Summary

Ghost 3.22.0 represents a significant architectural update focused on modernizing the settings system and improving the Stripe integration experience. The extensive refactoring of the settings table structure introduces new columns, explicit typing, and better organization of settings into logical groups. This provides a more robust foundation for future features while improving code maintainability.

The switch to Stripe Connect as the default integration method simplifies the payment setup process for site administrators, offering a more streamlined experience compared to the previous API key approach.

Several bug fixes improve the handling of images, particularly in subdirectory setups and for social media sharing. The access property improvements enhance the flexibility of membership features by making access controls more consistently available throughout templates.

However, the presence of a known issue with settings functionality makes this release problematic for production use. Site administrators should consider skipping this version and updating directly to a later release that addresses this issue.

Full Release Notes