Shopify Vue App

Appearance

Migration Guide: v2 to v3 ​

This guide will help you migrate your existing Shopify App Vue Template v2 applications to version 3, which introduces significant improvements and breaking changes, particularly in how authentication and App Bridge integration work.

Overview of Major Changes ​

Version 3 of the template brings several important improvements:

  1. Simplified Authentication: Authentication is now built-in without requiring explicit utilities
  2. Streamlined App Bridge: Direct integration with the Shopify App Bridge
  3. Improved Performance: Enhanced build and runtime performance
  4. Modern Frontend: Updated Vue 3.5 and Vite 6 with better TypeScript support
  5. Enhanced Security: Better token handling and CORS management

Breaking Changes ​

Authentication Flow ​

The most significant change in v3 is how authentication is handled. The useAuthenticatedFetch utility has been removed as authentication is now built-in.

Comparison ​

js
// Version 2 - Explicit authentication
import { useAuthenticatedFetch } from '@/services/useAuthenticatedFetch'
const fetch = useAuthenticatedFetch()
const response = await fetch('/api/products')

// Version 3 - Authentication handled automatically
const response = await fetch('/api/products')

App Bridge Implementation ​

The App Bridge implementation has been significantly simplified in v3:

Version 2 Approach ​

js
// v2 - plugins/appBridge.js
import { createApp } from '@shopify/app-bridge'

export const initAppBridge = () => {
  const host = new URLSearchParams(location.search).get('host') || window.__SHOPIFY_DEV_HOST
  window.__SHOPIFY_DEV_HOST = host
  return createApp({
    apiKey: process.env.SHOPIFY_API_KEY || '',
    host: host,
    forceRedirect: true
  })
}

export const ShopifyAppBridge = {
  install: (app) => {
    const useAppBridge = initAppBridge()
    app.config.globalProperties.$useAppBridge = useAppBridge
    app.provide('useAppBridge', useAppBridge)
  }
}

Version 3 Approach ​

js
// v3 - plugins/appBridge.js
export const appBridge = window.shopify

Script Loading ​

In v3, App Bridge is loaded directly in the HTML page:

html
<!-- v3 - index.html -->
<head>
  <!-- ... -->
  <meta name="shopify-api-key" content="%VITE_SHOPIFY_API_KEY%" />
  <script src="https://cdn.shopify.com/shopifycloud/app-bridge.js"></script>
  <!-- ... -->
</head>

ESLint Configuration ​

The ESLint configuration has been updated to use the new flat config system in v3.

Step-by-Step Migration Process ​

1. Update Project Dependencies ​

Start by updating your project dependencies:

bash
# Remove old lockfile to ensure a clean install
rm package-lock.json

# Install v3 dependencies
npm install

2. Update App Bridge Integration ​

  1. Modify your index.html to include the App Bridge script:
html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" href="/favicon.ico" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta name="shopify-api-key" content="%VITE_SHOPIFY_API_KEY%" />

    <script src="https://cdn.shopify.com/shopifycloud/app-bridge.js"></script>
    <title>Your Awesome App</title>
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/src/main.js"></script>
  </body>
</html>
  1. Replace your App Bridge plugin with the simplified version:
js
// plugins/appBridge.js
export const appBridge = window.shopify
  1. Remove the App Bridge initialization from your main.js file.

3. Update Authentication in Components ​

  1. Search for all instances of useAuthenticatedFetch in your codebase
  2. Replace authenticated fetch calls with standard fetch
  3. Remove import statements for useAuthenticatedFetch

Example:

js
// Old version (v2)
import { useAuthenticatedFetch } from '@/services/useAuthenticatedFetch'

export const useProductStore = defineStore('products', {
  actions: {
    async fetchProducts() {
      const fetch = useAuthenticatedFetch()
      const response = await fetch('/api/products')
      return await response.json()
    }
  }
})

// New version (v3)
export const useProductStore = defineStore('products', {
  actions: {
    async fetchProducts() {
      const response = await fetch('/api/products')
      return await response.json()
    }
  }
})

4. Update App Bridge Usage ​

Update components that use App Bridge:

js
// Old way (v2)
import { Loading, Toast } from '@shopify/app-bridge/actions'
const app = initAppBridge()
app.dispatch(Loading.Action.START)

// New way (v3)
import { appBridge } from '@/plugins/appBridge'
appBridge.loading.start()

Toast notifications:

js
// Old way (v2)
const toast = Toast.create(app, { message: 'Operation successful' })
toast.dispatch(Toast.Action.SHOW)

// New way (v3)
appBridge.toast.show('Operation successful')

5. Update Vite Configuration ​

Ensure your vite.config.js file matches the v3 template structure:

js
export default defineConfig({
  // ...
  plugins: [
    {
      name: 'vite-plugin-replace-shopify-api-key',
      transformIndexHtml: {
        handler(html) {
          return html.replace(/%VITE_SHOPIFY_API_KEY%/g, process.env.SHOPIFY_API_KEY || '')
        },
        order: 'pre'
      }
    },
    vue()
  ]
  // ...
})

Troubleshooting Common Issues ​

App Bridge Not Connecting ​

If App Bridge fails to connect:

  1. Check that the App Bridge script is correctly loaded in index.html
  2. Verify that your API key is correctly passed through the meta tag
  3. Check the browser console for errors related to App Bridge initialization

Authentication Issues ​

If you encounter authentication problems:

  1. Make sure all custom authentication code has been removed
  2. Verify that server routes are correctly configured for the new authentication flow
  3. Check that your Shopify app settings match the callback URLs

CORS Errors ​

If you see CORS errors after migration:

  1. Verify that the proxy settings in vite.config.js are correct
  2. Ensure your Shopify app's allowed URLs are up to date
  3. Check that your API endpoints are properly configured

Additional Considerations ​

TypeScript Support ​

Version 3 has improved TypeScript support. Consider adding proper type annotations to your code for better developer experience.

ESLint Configuration ​

Update your ESLint configuration to match the new flat config system:

js
// eslint.config.mjs
export default [
  {
    files: ['**/*.{js,mjs,cjs,jsx,ts,tsx,vue}'],
    rules: {
      // Your rules here
    }
  }
]

Deprecations ​

The following features have been deprecated in v3:

  1. The useAuthenticatedFetch utility (authentication is now automatic)
  2. Manual App Bridge initialization (now loaded via CDN)
  3. Old ESLint configuration format (now using flat config)

Conclusion ​

Migrating from v2 to v3 of the Shopify App Vue Template primarily focuses on simplifying authentication and App Bridge integration. The new version offers significant improvements in developer experience, performance, and security.

By following this guide, you should be able to update your existing applications to take advantage of all the improvements in v3.

If you encounter any issues not covered in this guide, please report them on GitHub or reach out to our community support.

Released under the MIT License.

Copyright © 2023-present