This content originally appeared on DEV Community and was authored by Sulman Baig
Motivation
After building several Shopify embedded apps, I've learned valuable lessons about what works (and what definitely doesn't) in the embedded app environment. Today, I'm sharing these insights to help you avoid common pitfalls and build better Shopify apps.
The Challenge
Building embedded apps for Shopify presents unique challenges - particularly around navigation, authentication, and user experience. One of the biggest pitfalls? Trying to use regular URL navigation in an embedded app context.
Project Setup
First, let's look at the proper configuration for a Shopify embedded app:
# config/initializers/shopify_app.rb
ShopifyApp.configure do |config|
config.embedded_app = true
config.new_embedded_auth_strategy = false
config.scope = "read_customers,write_customers"
config.api_version = "2024-10"
# Webhook configuration
config.webhooks = [
{ topic: "app/uninstalled", address: "webhooks/app_uninstalled" },
{ topic: "customers/create", address: "webhooks/customers_create" }
]
end
Do's and Don'ts
✅ DO: Use App Bridge for Navigation
// app/javascript/shopify_app.js
var AppBridge = window['app-bridge'];
var createApp = AppBridge.default;
window.app = createApp({
apiKey: data.apiKey,
host: data.host,
});
var actions = AppBridge.actions;
var TitleBar = actions.TitleBar;
TitleBar.create(app, {
title: data.page,
});
❌ DON'T: Use Regular Rails Links
Avoid using regular Rails link_to helpers without proper App Bridge handling:
<%# Wrong way %>
<%= link_to "Settings", settings_path %>
<%# Right way %>
<%= link_to "Settings", settings_path(request.query_parameters) %>
✅ DO: Handle Authentication Properly
class AuthenticatedController < ApplicationController
include ShopifyApp::EnsureHasSession
before_action :verify_embedded_app_request
private
def verify_embedded_app_request
if ShopifyAPI::Context.embedded? &&
(!params[:embedded].present? || params[:embedded] != "1")
redirect_to(ShopifyAPI::Auth.embedded_app_url(params[:host]).to_s +
request.path,
allow_other_host: true)
end
end
end
✅ DO: Implement Proper Flash Messages
# app/helpers/application_helper.rb
module ApplicationHelper
def flash_class(type)
case type.to_sym
when :success, :notice
"bg-green-50"
when :error, :alert
"bg-red-50"
else
"bg-blue-50"
end
end
end
✅ DO: Use Proper Layout for Embedded Apps
<%# app/views/layouts/embedded_app.html.erb %>
<!DOCTYPE html>
<html lang="en">
<head>
<script src="https://unpkg.com/@shopify/app-bridge@3.7.9"></script>
<%= csrf_meta_tags %>
<%= javascript_importmap_tags %>
</head>
<body>
<div id="app">
<%= render 'shared/navbar' %>
<%= yield %>
</div>
<% if flash[:notice].present? || flash[:error].present? %>
<script>
document.addEventListener('DOMContentLoaded', function() {
var Toast = window['app-bridge'].actions.Toast;
<% if flash[:notice].present? %>
Toast.create(window.app, {
message: "<%= j flash[:notice] %>",
duration: 5000
}).dispatch(Toast.Action.SHOW);
<% end %>
});
</script>
<% end %>
</body>
</html>
❌ DON'T: Forget Query Parameters
When creating links or forms, always include the necessary query parameters:
# app/controllers/application_controller.rb
def maintain_query_parameters
@query_parameters = request.query_parameters
end
✅ DO: Implement Proper Navigation
<%# app/views/shared/_navbar.html.erb %>
<nav class="bg-white border-b border-gray-200 fixed w-full z-50">
<div class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
<div class="flex justify-between h-16">
<div class="hidden md:flex md:items-center md:space-x-6">
<%= link_to "Home",
root_path(params.except(:action, :controller).permit!.to_h),
class: "text-gray-600 hover:text-gray-900 px-3 py-2" %>
</div>
</div>
</div>
</nav>
Common Pitfalls to Avoid
- Direct URL Manipulation
# Wrong
redirect_to settings_path
# Right
redirect_to settings_path(request.query_parameters)
- Missing CSRF Protection
class ApplicationController < ActionController::Base
protect_from_forgery with: :exception
skip_before_action :verify_authenticity_token, if: :valid_shopify_request?
private
def valid_shopify_request?
return true if request.headers["HTTP_AUTHORIZATION"]&.start_with?("Bearer ")
return true if params[:session].present?
false
end
end
- Improper Session Handling
class Shop < ActiveRecord::Base
include ShopifyApp::ShopSessionStorageWithScopes
def api_version
ShopifyApp.configuration.api_version
end
end
Best Practices for Success
- Use App Bridge for All Navigation
- Maintain Query Parameters
- Implement Proper Error Handling
- Use Appropriate Authentication Checks
- Follow Shopify's Design Guidelines
Learning Journey
Building embedded Shopify apps has taught me the importance of proper navigation handling and session management. The biggest lesson? Never assume standard web development practices will work in an embedded context.
Results and Impact
- Smoother user experience
- Fewer authentication issues
- Better app stability
- Reduced support tickets
Next Steps
-
Enhanced Error Handling
- Implement better error boundaries
- Add detailed logging
-
Performance Optimization
- Optimize App Bridge usage
- Implement proper caching
-
User Experience Improvements
- Add loading states
- Enhance feedback mechanisms
Conclusion
Building embedded Shopify apps requires a different mindset from traditional web development. By following these best practices and avoiding common pitfalls, you can create robust, user-friendly applications that integrate seamlessly with the Shopify admin.
Have you encountered other challenges while building Shopify embedded apps? Share your experiences in the comments below!
Happy Coding!
Originally published at sulmanweb
This content originally appeared on DEV Community and was authored by Sulman Baig
Sulman Baig | Sciencx (2025-02-06T06:00:00+00:00) Master Shopify Embedded Apps with Rails 8. Retrieved from https://www.scien.cx/2025/02/06/master-shopify-embedded-apps-with-rails-8/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.