Ghost Release: 4.0.0-rc.0

TL;DR

Ghost 4.0.0-rc.0 introduces significant architectural improvements and new features that enhance the publishing experience. This release candidate brings a new accent color system for better theme customization, improved URL handling with the __GHOST_URL__ placeholder, enhanced price formatting with the updated {{price}} helper, and better member management with refined event tracking. The update also includes important security improvements with foreign key constraints in SQLite, performance optimizations for test suites, and API standardization with v4 as the new default API version. This is a major release with some breaking changes, so testing in a non-production environment is recommended before upgrading.

Highlight of the Release

• New accent color system with CSS variable integration for consistent branding
• Improved URL handling with __GHOST_URL__ placeholder for better performance
• Enhanced price formatting with the updated {{price}} helper
• Default API version bumped to v4
• Better member management with refined event tracking and timeline visualization
• Foreign key constraints added to SQLite databases for improved data integrity
• New limit service for managing feature restrictions in hosted environments

Migration Guide

Preparing for Upgrade

1. Update Ghost-CLI:

   npm install -g ghost-cli@latest
   

   Ghost 4.0 requires Ghost-CLI version 1.16.0 or higher.

2. Backup Your Site:

   ghost backup
   

3. Check Theme Compatibility: Ensure your theme is compatible with Ghost 4.0. Themes using deprecated features like {{@labs.members}} or Ghost API v2 will receive warnings.

API Version Changes

If you're developing custom integrations or themes:

1. Update API references from v3 to v4
2. Replace {{@site.lang}} with {{@site.locale}} in themes
3. Update any custom webhooks to use the v4 API

Theme Updates

1. Price Helper: If using the {{price}} helper, review its implementation as it now has enhanced formatting capabilities.

2. Date Helper: The default format for the date helper now uses locale-based strings. Test your theme to ensure dates display as expected.

3. Accent Color: Take advantage of the new --ghost-accent-color CSS variable:

   .my-element {
     color: var(--ghost-accent-color, #defaultColor);
   }
   

4. Last4 Helper: The {{last4}} helper now returns **** instead of null when empty.

URL Structure Changes

Ghost 4.0 changes how URLs are stored internally using a __GHOST_URL__ placeholder. This should be transparent to most users, but if you've done any direct database manipulation of URLs, you'll need to update your approach.

After Upgrading

1. Verify Member Data: Check that member data and subscriptions are working correctly.

2. Test Email Functionality: Send test emails to ensure the updated email templates work as expected.

3. Review Site Settings: Check your site settings, particularly accent color and locale settings, to ensure they're configured correctly.

Upgrade Recommendations

Who should upgrade: This release candidate is primarily intended for testing purposes. Production sites should wait for the final 4.0.0 release unless they specifically need features in this version or want to help test.

When to upgrade:

• Test environments: Immediately, to help identify any issues before the final release
• Production environments: Wait for the final 4.0.0 release unless you're comfortable with potential RC issues

How to upgrade:

1. Ensure you're on Ghost-CLI 1.16.0 or higher: npm install -g ghost-cli@latest
2. Take a full backup: ghost backup
3. Run the upgrade: ghost update v4.0.0-rc.0 --force

Important: The --force flag is required as this is a major version upgrade.

Rollback plan: If issues are encountered, restore from your backup using ghost restore [backup-file].

Testing recommendation: Test thoroughly in a staging environment before upgrading production sites. Pay special attention to theme compatibility, member features, and any custom integrations.

Bug Fixes

Portal Display on Error Pages

Fixed an issue where the member portal wasn't appearing on 404 pages, ensuring consistent member access across all site pages.

Email Analytics Processing

Fixed a critical bug that was causing Ghost to crash when sending bulk emails due to improper handling of Mailgun API responses.

Theme Preview Rendering

Fixed theme preview not decoding values properly, which caused nulls to be treated as truthy values, resulting in inconsistent preview behavior compared to live themes.

Email Permissions

Fixed email permissions for all roles. The migrations in 3.1.0 which added email permissions did not add those permissions to the correct roles, limiting email functionality to only the Owner role.

Stripe Data Cleanup

Fixed issues with orphaned Stripe data in SQLite databases that could cause problems with member management and subscription tracking.

Migration Path from 1.x

Fixed migrations to 4.x from 1.x by addressing issues with the Slack settings migration that was causing errors on SQLite.

Last4 Card Display

Updated the last4 helper to return a masked value (****) instead of null when card details are empty, preventing null from being displayed in themes.

New Features

Accent Color System

Ghost now automatically generates a CSS variable (--ghost-accent-color) based on your site's accent color setting. This variable is injected into {{ghost_head}} and can be used by themes to maintain consistent branding across your site and the member portal.

Enhanced Price Formatting

The {{price}} helper has been completely revamped to provide well-formatted currency values. It now supports:

• Automatic formatting based on currency ({{price plan}} → "€5")
• Custom number formats ({{price plan numberFormat="long"}} → "€5.00")
• Currency symbol output ({{price currency='EUR'}} → "€")

Improved Member Analytics

Member analytics have been enhanced with:

• Refined event timeline that includes signup events
• Cleaner response format for MRR and volume stats endpoints
• Better visualization of member activity

Locale Support

Ghost now uses locale instead of lang for site settings, providing better internationalization support:

• New {{@site.locale}} property (with {{@site.lang}} maintained for backward compatibility)
• Default date formatting now uses locale-based strings
• API responses include the locale property

URL Transformation Improvements

Ghost now stores URLs with a __GHOST_URL__ placeholder, providing:

• Faster and less memory-intensive URL transformations
• Ability to change subdirectory paths without manual database updates
• More efficient content rendering

Security Updates

Foreign Key Constraints

Added 'on delete cascade' to several foreign keys in SQLite databases, preventing orphaned records and potential security issues related to data integrity.

Authentication Response Codes

Fixed status code for unauthenticated requests to return 401 Unauthorized instead of 400 Bad Request, providing more accurate security responses.

Analytics Error Handling

Improved error handling in analytics tracking by wrapping the tracking call in try-catch blocks and adding Sentry logging, preventing potential crashes from malformed analytics data.

Performance Improvements

Test Suite Organization

The test suite has been significantly improved:

• Site test suite split into separate files for v2/v3/v4 API versions
• Extracted API engine-specific suites from site spec
• Simplified file structure and nesting of test suites
• Renamed files to follow consistent snake_case pattern

URL Transformation Efficiency

The new URL storage format using __GHOST_URL__ placeholders provides substantial performance benefits:

• Eliminates the need for HTML or Markdown parsing during URL transformations
• Reduces memory usage during content rendering
• Speeds up page load times by simplifying the transformation process

ElasticSearch Logging

Added ElasticSearch logging support when available, improving logging capabilities and performance for larger installations.

Foreign Key Constraints

Added foreign key constraints to SQLite databases, which improves data integrity and can lead to better query performance in some cases.

Impact Summary

Ghost 4.0.0-rc.0 represents a significant evolution of the platform with architectural improvements that enhance performance, security, and developer experience. The introduction of the accent color system and improved price formatting provides better branding consistency and monetization capabilities. The shift to v4 as the default API version standardizes the platform's interfaces while maintaining backward compatibility.

For theme developers, the new CSS variables and helper improvements offer more powerful customization options. Site owners benefit from enhanced member analytics and more consistent styling across their sites. Developers will appreciate the more efficient URL handling and improved test organization.

This release also introduces a new limit service that allows hosting providers to better manage feature restrictions based on subscription tiers, which is particularly important for Ghost(Pro) and other managed hosting services.

While this is a major version update with breaking changes, the Ghost team has worked to minimize migration pain points. Most changes are architectural improvements that should be transparent to end users but provide a more solid foundation for future development. The migration path has been carefully considered, with backward compatibility maintained where possible and clear upgrade paths provided where not.

Full Release Notes