I’m running into a problem with theme file cleanup after app uninstall.
When the app/uninstalled webhook fires, the Admin API session is already revoked, so we can’t remove the theme files we added.
Shopify Partner Support suggested a “Third Party App Developer Handoff” (manual instructions for merchants to delete leftover files), but that isn’t really an option for us, the files shouldn’t remain after uninstall.
Has anyone found a supported way to ensure theme files are removed automatically when the app is uninstalled? Or is there an official pattern for handling this?
Publish your theme files as theme blocks instead. These are automatically removed after the app is uninstalled, so it’s a much better clean up experience.
Use the Online Script Tag API to register a script tag. These are also removed after uninstallation automatically.
I would personally go with the theme block route if:
My app didn’t need to apply to every single page (think pop ups, self reported age gates, etc)
I need .liquid to reference objects/resources not available in the window.Shopify object
Merchants want to control where exactly your integration fits on their storefront
Otherwise the Script Tag API option is nice because it’s a zero click integration which is even more seamless.
Our use case requires installing actual theme files (sections/blocks/snippets/assets) that behave like native theme assets. Converting everything to App Blocks or ScriptTags doesn’t fit because:
App Blocks: great for embeds, but they don’t replace shipping standalone, file-based sections that persist as first-class theme assets.
ScriptTags: as far as I know, these were only for injecting JavaScript into vintage themes (and now deprecated), so they don’t apply to managing/removing Liquid files.
What we’d really need is a supported way to guarantee file cleanup on uninstall for file-based apps. Some ideas that could work (but not implemented to my knowledge):
Uninstall-scoped token (short-lived, only for themeFilesDelete)
File ownership marker + auto-purge (Shopify removes files tagged as “owned by app X” on uninstall)
Pre-uninstall hook (synchronous step allowing apps to clean up files before uninstall completes)
At this point I’m feeling a bit stuck, so hoping others have ideas.
App Blocks: great for embeds, but they don’t replace shipping standalone, file-based sections that persist as first-class theme assets.
I’m sorry I’m still not quite understanding why App Blocks don’t fit your use case.
Could you clarify? Why do you need first-class theme assets? What shortcomings do App Blocks have that don’t fit your use case?
ScriptTags : as far as I know, these were only for injecting JavaScript into vintage themes (and now deprecated), so they don’t apply to managing/removing Liquid files
Not quite true. ScriptTags are deprecated for the Order Status page, which are replaced by Customer Account Extensions. The Online Store scope is still available.
But yes, you’re correct you cannot register liquid files, only JS scripts.
Thanks for the follow-up! Let me explain more clearly.
The core of our app is building sections that extend a merchant’s existing theme. Merchants can install these sections and use them just like native theme sections — everything from content blocks to headers, footers, or even parts of the cart.
Because of this, we can’t rely on the customer’s default theme supporting @app blocks. We need to deliver standalone, file-based sections that work consistently across any theme, not just within the App Block context.
That’s why App Blocks don’t fit our use case: they don’t give us a way to provide reusable, theme-native sections that extend any theme directly. We did test App Blocks, but the experience wasn’t as smooth for merchants. Native-style sections were much easier for them to adopt, but that comes with this challange.
Just to clarify where we’re coming from. We’ve tested App Blocks thoroughly and while they work great in most cases, for our app they come with limitations.
Some of the limitations we’ve run into are limited settings (with a maximum of 25 total) and no real modularity with blocks (no content_for support or presets). For merchants this means the sections are less flexible, harder to customize, and don’t behave like the native sections they’re used to working with.
Right now our approach is a hybrid where App Blocks are used only for assets so they get removed on uninstall, while the sections and blocks themselves are added as theme files. Technically this works, but it leaves merchants with sections that remain in their theme but no longer function, which creates a broken and confusing experience.
From a merchant perspective, uninstall should feel complete. If an app installs or edits theme files, the expected behaviour is that those files are removed on uninstall, whether by the app or automatically doesn’t matter, as long as merchants aren’t left with leftovers. That’s why I wanted to revisit this topic, since the last discussion How to delete files when the app is uninstalled? - #4 by Nic-Shopify was marked as solved with App Blocks, but for our use case, that doesn’t actually solve the problem.
