Strapi Release: 3.0.0-beta.17

TL;DR

Strapi v3.0.0-beta.17 introduces several breaking changes including a new provider_metadata field for file uploads, changes to GraphQL context handling, and updates to the forgot password URL configuration. The release also brings new features like GraphQL authentication endpoints, improved admin customization, and numerous bug fixes for MongoDB, Cloudinary, and image handling.

Highlight of the Release

• New provider_metadata field for file upload providers
• GraphQL authentication with register and login endpoints
• Enhanced admin panel customization capabilities
• Improved documentation structure and content
• Fixed Cloudinary file deletion for non-image files

Migration Guide

Migrating to v3.0.0-beta.17

Cloudinary Provider Migration

For Cloudinary users, you need to migrate the public_id field to the new provider_metadata JSON field:

1. Create a migration script to move your existing public_id values
2. Update your code to use provider_metadata.public_id instead of public_id
3. The provider_metadata field will also store the resource_type for proper file deletion

GraphQL Custom Queries

If you have custom GraphQL queries, update your resolvers to access the Koa context through the GraphQL context:

Before:

module.exports = {
  Query: {
    customQuery(root, args, ctx) {
      // ctx was the Koa context
    }
  }
}

After:

module.exports = {
  Query: {
    customQuery(root, args, ctx) {
      // ctx is now the GraphQL context
      // To access the Koa context use ctx.context
    }
  }
}

Reset Password URL Configuration

You must now set the reset password URL page in the Users & Permissions advanced settings:

1. Navigate to Roles & Permissions > Advanced settings
2. Set the "Reset password page" URL to your frontend reset password page

Upgrade Recommendations

This release contains several breaking changes that affect file uploads (especially with Cloudinary), GraphQL custom queries, and authentication workflows. We recommend:

1. For Development Environments: Upgrade immediately to benefit from the new features and bug fixes.

2. For Production Environments:

   • Plan for the migration of Cloudinary data if you're using the Cloudinary provider
   • Test your GraphQL custom queries if you have any
   • Update your authentication flow if you're using the forgot password feature
   • Schedule a maintenance window for the upgrade

3. Testing Requirements:

   • Test file uploads and deletions, especially with Cloudinary
   • Verify all GraphQL queries, especially custom ones
   • Test the forgot password flow
   • If using MongoDB, verify connections work correctly with special characters in passwords

The upgrade process itself is straightforward:

npm install [email protected] [email protected] [email protected]
# Also update any strapi plugins you're using to the same version

Bug Fixes

File Upload and Management

• Fixed Cloudinary deletion of non-image files by adding required resource_type parameter
• Fixed image URL generation when using third-party providers
• Fixed issue where images weren't respecting the configurable: false setting

GraphQL Improvements

• Fixed context handling in custom GraphQL queries
• Created a dataloader for every model to improve performance with related data
• Fixed mutation resolver name selector

Authentication and Security

• Fixed forgot password URL configuration
• Escaped MongoDB passwords for better security
• Fixed race condition during startup when writing jwt.json

Admin Interface

• Fixed search functionality when using special characters like '%'
• Updated enum error message for special characters

New Features

GraphQL Authentication

Added GraphQL endpoints for user registration and login, allowing frontend applications to handle authentication directly through GraphQL instead of REST. This feature includes proper error handling and end-to-end testing.

Admin Panel Customization

New capabilities for customizing the admin panel, making it easier to develop and extend the frontend. This includes:

• A watch command for frontend development
• Ability to customize plugin frontend files
• Configuration options for the development server

Dynamic OAuth Callback

Added ability to pass OAuth callback URLs dynamically, providing more flexibility when integrating with third-party authentication providers.

GraphQL Playground Sharing

Added a share playground feature for GraphQL, making it easier to collaborate and share queries with team members.

Security Updates

Database Security

• MongoDB passwords are now properly escaped in connection strings, preventing potential security issues with special characters in passwords

Authentication

• Fixed forgot password URL configuration, ensuring reset password links work correctly and securely
• Improved JWT handling during startup to prevent race conditions

Performance Improvements

GraphQL Performance

• Created a dataloader for every model, significantly improving performance when querying related data in GraphQL
• Better handling of GraphQL context in custom queries

Project Creation and Startup

• Removed ESLint from project generation to improve speed and maintain Node.js compatibility
• Fixed race condition during startup by disabling reload when writing jwt.json
• Improved error diagnostics during project creation

Error Handling

• Enhanced error logging by capturing more detailed events
• Console logging errors before sending to Sentry for better diagnostics

Impact Summary

Strapi v3.0.0-beta.17 brings significant improvements to the platform with a focus on GraphQL capabilities, admin customization, and file upload handling. The introduction of GraphQL authentication endpoints enables frontend applications to handle user registration and login directly through GraphQL, streamlining authentication workflows.

The release includes three breaking changes that require attention:

1. A new provider_metadata field for file upload providers, requiring migration for Cloudinary users
2. Changes to GraphQL context handling in custom queries
3. Updates to the forgot password URL configuration

These changes improve the architecture and security of the platform but require careful migration planning.

The enhanced admin customization features make it easier for developers to extend and modify the admin panel, while numerous bug fixes address issues with MongoDB connections, Cloudinary file handling, and image URL generation.

Performance improvements for GraphQL queries and project creation will benefit all users, particularly those working with complex data relationships. The documentation has also been significantly restructured and improved, making it easier for new and existing users to find information.

Full Release Notes

module.exports = {
  Query: {
    customQuery(root, args, ctx) {
       // ctx is the koa context
    }
  }
}

module.exports = {
  Query: {
    customQuery(root, args, ctx) {
       // ctx is the graphql context
       // to access the koa context use ctx.context
    }
  }
}