Skip to main content

Shopify-managed Installation Migration

Tutorial: https://somup.com/cTQuD3PZb0 Documentation: Shopify App Installation

Key Changes​

  • Permissions stored in Shopify (includes optional scopes)
  • Installation via verifyEmbedRequest middleware (no more redirects)
  • Requires deployment to Partner dashboard
  • Core version 4.2.0+ required

Migration Steps​

1. Update TOML Configuration​

⚠️ Critical: Include ALL scopes and update URL from /auth/shopify to /embed

application_url = "https://thomas-app-base-template.firebaseapp.com/embed"

# Example: Include all required scopes
[access_scopes]
# Learn more at https://shopify.dev/docs/apps/tools/cli/configuration#access_scopes
use_legacy_install_flow = false
scopes = "read_themes, read_orders, read_products, read_customers, write_customers"
optional_scopes = [ "read_translations",  "read_discounts"]

2. Update Avada Core​

Update @avada/core to version 4.2.0 to support the new authentication process:

{
  "@avada/core": "4.2.0"
}

3. Update API Handler Configuration​

With the new authentication system, authorization is handled through Shopify App Bridge instead of redirects. The afterInstall and afterLogin logic moves to the API endpoint. And pass these config to verifyEmbedRequest middleware.

Key Changes:

  • First API call triggers the installation process
  • Maintain existing verifyEmbedConfig structure
  • Add new required fields to the configuration
const verifyEmbedConfig = {
  // ...other fields
  afterLogin: installationService.afterLogin,
  afterInstall: installationService.installApp,
  accessTokenKey: shopifyConfig.accessTokenKey,
  initialPlan: {
    id: 'free',
    name: 'Free',
    price: 0,
    trialDays: 0,
    features: {}
  }
};

4. Update Optional Scopes Logic​

If your app uses optional scopes, update the implementation to use shopify.scopes.request from App Bridge directly. This streamlines the permission request process.

Configuration Best Practices:

  • TOML file can be added to CI pipeline only (not required in Git repository)
  • Maintain permissions in shopify.js config file for documentation
  • Critical: Verify all permissions before deployment - missing scopes will break functionality

Example Implementations​

Reference Merge Requests​

Pre-Deployment Checklist​

Core Requirements​

  • Updated @avada/core to version 4.2.0 or higher
  • Verified all dependencies are compatible

Configuration​

  • All required scopes listed in TOML file
  • Optional scopes properly configured
  • API handler updated with new configuration
  • verifyEmbedConfig includes all required fields

Testing​

  • Installation flow tested in staging environment
  • Permission grants verified for all scopes
  • App Bridge auto-detection confirmed working
  • Performance metrics reviewed (especially LCP)

Deployment Preparation​

  • Rollback plan documented and tested
  • App-specific permissions documented
  • Monitoring alerts configured
  • Support team briefed on changes

Troubleshooting​

Common Issues​

  1. Missing Permissions

    • Symptom: Features not working after migration
    • Solution: Review TOML file and ensure all scopes are included

  2. Installation Failures

    • Symptom: App fails to install or authenticate
    • Solution: Verify deployment to Partner dashboard and check middleware configuration

  3. Performance Issues

    • Symptom: Increased load times on first visit
    • Solution: This is expected behavior due to permission verification in middleware

Additional Resources​

Documentation​