skills.rest
saleor
saleorOFFICIAL
Explore all skills by this author →
Website𝕏@getsaleorGitHub

paper-migrations

Apply chronological upstream Paper storefront migrations to forked Saleor shops.

1.6k|885|Updated Aug 20, 2021
Search Tags:#next.js#upgrade#Checkout#Caching#saleor#storefront#Migration
One-click install
npx skills add https://github.com/saleor/storefront --skill paper-migrations
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: paper-migrations
Source: https://github.com/saleor/storefront/tree/main/skills/saleor-paper-storefront/migrations
Command: npx skills add https://github.com/saleor/storefront --skill paper-migrations

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Forks of the Saleor Paper storefront drift behind upstream releases, and manually porting caching, PPR, and checkout architecture changes risks overwriting custom styling or breaking payments. This Skill applies ordered, dependency-aware migrations that port architecture while preserving fork customizations.

Core Features & Use Cases

  • Ordered migration registry: Reads manifest.json and paper-version.json to compute pending migrations, enforce hard requires dependencies, and record applied or skipped entries with upstream SHAs.
  • Detect-before-port workflow: Each atomic migration ships detect.md heuristics, a MIGRATION.md prompt, and a verify.md checklist so already-applied or partial states are recognized before any code changes.
  • Styling-safe porting: Distinguishes architecture, presentation-default, and styling tags so Suspense boundaries, cache tags, and data layers are ported while fork classNames and brand tokens are preserved.
  • Use Case: A team forked Paper six months ago and wants checkout v2. The Skill inventories fork payment customizations, adopts the upstream RSC checkout tree, replays deltas at extension points, and records the migration in paper-version.json.

Quick Start

Ask the assistant to check which Paper migrations are pending for this fork and apply them in order.

Frequently Asked Questions about paper-migrations

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I upgrade a forked Saleor Paper storefront to the latest upstream version?▼

Read migrations/manifest.json for the ordered registry and the fork's paper-version.json for applied entries, then compute pending migrations. For each one, run its detect.md heuristics, follow MIGRATION.md steps, and record the result with the upstream SHA in paper-version.json.

How do I migrate Paper checkout from urql to server actions?▼

Apply the 2026-06-checkout-v2 migration, which is a subsystem replacement rather than an incremental port. Adopt the upstream src/checkout tree and (checkout) route group as the base, then replay fork customizations at extension points like the INTEGRATED_GATEWAYS payment registry.

Will Paper migrations overwrite my custom styling?▼

No. Migrations tag changes as architecture, presentation-default, or styling. Architecture changes like Suspense boundaries and cache tags are always ported, presentation-default ports structure while preserving existing classNames, and styling changes are never auto-applied.

What happens if a Paper migration dependency is not applied?▼

Migrations declare hard requires dependencies in the manifest. If a dependency is missing or was skipped, the blocked migration is skipped and revisited in a later pass, looping until no pending applicable migrations remain.

Can I skip optional Paper migrations?▼

Yes. Migrations marked optional in the manifest present a skipPrompt asking for confirmation. If skipped, the Skill records skipped: true and an optional skipReason in paper-version.json, and warns when dependents are affected.

What are the limitations of the Paper migrations workflow?▼

Version 1 has no automated verify script, CI enforcement, or cross-repo automation for paper-app webhook setup, which requires manual steps. It also stops and reports rather than guessing when checkout, cart, or payment paths are ambiguous.

Related Skills

Explore More Software Engineering Skills→
finsilabsfinsilabs
44

saleor-development

Develop and extend Saleor commerce platform via GraphQL API and webhooks.

Official
Intermediate
NagyViktNagyVikt
2

saleor-paper-storefront

Guide Next.js 16 Saleor storefront architecture with caching and checkout patterns.

Community
Advanced
krl76krl76

unity-addressables-design

Codify Unity Addressables design rules across versions 1.22.3 and 2.9.1.

Community
Advanced
ResearchMonkeyResearchMonkey

foundation-sync

Bidirectionally synchronize a fork with Foundation_template using git subtree.

Community
Intermediate