Direct answer
For recovery across a major Hoppscotch version bump, JSON Export/Import is the more resilient primary path. It produces a static, portable file that is independent of GitHub API availability, token validity, and rate limits. GitHub Gist Sync is useful as a convenience mirror, but it introduces more external failure points and can fail silently when you least expect it.
Why the failure modes differ
Both methods ultimately depend on how Hoppscotch handles schema changes. Neither format inherently guarantees backward compatibility with older collection schemas unless the application stores and applies schema version metadata. The practical difference is visibility:
- JSON Import: If the upgraded application rejects the file, you typically see an error or a partial import. You can then inspect the JSON, adjust fields, and retry.
- Gist Sync: A failed API call, expired token, or rate-limit response may not surface clearly in the UI. Restoration can appear to succeed while leaving stale or missing data.
What is confirmed versus what is likely
Confirmed by the persistence model: Hoppscotch defaults to localStorage, and both export and Gist sync are user-initiated mechanisms. There is no built-in automatic rollback.
Likely, but version-dependent: a breaking schema change in a new release may invalidate either an imported JSON file or a Gist payload. Whether the app migrates older formats depends on the specific versions involved. Treat this as a risk to verify, not a guarantee.
Recommended recovery workflow
- Before upgrading, export every collection and environment to JSON from the current version.
- Save the file outside the browser profile—local disk or an encrypted archive—so a
localStorage wipe does not destroy your only copy.
- After upgrading, import the JSON into the new version first in a separate browser profile or workspace.
- Verify that environments, variables, and request bodies render correctly. Note any schema-related errors before trusting the data.
- Keep Gist sync enabled for day-to-day convenience, but do not treat it as the sole recovery artifact.
Safe verification command
You can confirm that your browser profile still holds Hoppscotch data before an upgrade by checking localStorage keys in DevTools:
// Browser DevTools Console
Object.keys(localStorage).filter(k => k.includes('hoppscotch'))
This is read-only and scoped to the current origin. It helps you confirm that the expected keys exist before you rely on an export.
Bottom line
Use JSON Export/Import as your authoritative pre-upgrade backup because it is inspectable and API-independent. Use GitHub Gist Sync as a secondary mirror for accessibility. If your upgrade crosses a major version boundary and the target release does not document a migration path, assume the JSON file is your only guaranteed recovery point until you have successfully imported and validated it in the new version.
hoppscotch