Shopify Apps custom: scaffold base

Una custom app Shopify estende il backend e l'admin con funzionalità su misura: integrazioni ERP, sync prodotti da supplier, automazioni complesse. Dal 2023 Shopify raccomanda Remix come stack di riferimento. In questa guida vediamo come creare un'app da zero.

Tipi di app

Public app: pubblicata sull'App Store, installabile da chiunque, OAuth flow, tariffa per merchant. Custom app: installabile su uno store specifico, OAuth, distribuzione privata via link. Private/legacy app: deprecata, sostituita da custom app dal 2022. Per la maggior parte degli use case interni Custom app è perfetta.

Stack consigliato

Shopify CLI offre template Remix preconfigurato: Remix (React full-stack), Polaris (UI components Shopify-native), App Bridge (interazione con Admin), GraphQL Admin API, Webhooks, Prisma (ORM database). Lingua principale TypeScript.

Procedura passo-passo

1. Installa Shopify CLI: npm install -g @shopify/cli@latest.
2. Crea app: shopify app init e scegli Remix template.
3. Esegui npm install nella cartella creata.
4. Avvia dev: shopify app dev. CLI apre tunnel ngrok e crea app sul Partner dashboard.
5. Vai a Partner dashboard, copia API key e secret in .env.
6. Apri preview URL e installa l'app sul tuo development store.
7. Sviluppa: app/routes/app._index.tsx è la home dell'admin app.
8. Aggiungi route per pagine custom: app/routes/app.products.tsx.
9. Usa GraphQL Admin API: admin.graphql(query, { variables }).
10. Aggiungi webhook handler in app/routes/webhooks.tsx.
11. Configura scopes in shopify.app.toml: read_products, write_orders, ecc.
12. Deploy: shopify app deploy pubblica estensioni.
13. Per produzione: hosting su Render/Heroku/Vercel + database (PostgreSQL).

Esempio: leggere prodotti

In una route Remix: const response = await admin.graphql(`
query { products(first: 10) { edges { node { id title } } } }
`);
const data = await response.json();. Restituisce JSON con i primi 10 prodotti. Usa Polaris per UI: <Page title="Products">...</Page>.

Webhook

I webhook permettono di reagire a eventi: order/created, product/updated, ecc. Configurali in shopify.app.toml: [[webhooks.subscriptions]] topics = ["orders/create"] uri = "/webhooks/orders". Nel handler app/routes/webhooks.tsx elabora il payload (ID prodotto, dati ordine) e fai logica custom (sync ERP, notifica Slack, ecc.).

Errori comuni e come risolverli

• Scopes insufficienti: errore Access denied; aggiungi scope in toml e reinstalla app.
• Webhook duplicati: Shopify ritrasmette se non rispondi 200; gestisci idempotenza con header X-Shopify-Webhook-Id.
• Tunnel ngrok scaduto: shopify app dev rigenera tunnel automaticamente; tieni terminale aperto.
• Rate limit GraphQL: 1000 cost points/secondo; usa bulk operations per esportazioni massive.

Domande frequenti

D: Posso usare Next.js invece di Remix?
R: Sì, ma il template default e supporto Shopify è migliore con Remix.

D: Quanto costa hostare un'app custom?
R: 0-50 dollari/mese su Render/Railway/Vercel per traffico basso.

D: Devo pagare per registrare la custom app?
R: No, account Partner gratuito.

Distribuzione e installazione

Per custom app interna: Partner dashboard > App > Distribution > Custom distribution genera link installazione unico per uno store specifico. L'admin store apre il link, autorizza scope, app installata. Per app pubbliche sull'App Store servono: App listing con screenshot, video, descrizione SEO, pricing model (free, recurring, usage-based), review Shopify (2-4 settimane), conformity a Best practices (performance, security, GDPR).

Billing e pricing

Le app possono addebitare merchant tramite Shopify Billing API: RecurringApplicationCharge (mensile fisso), UsageCharge (variabile basato su uso), AppSubscription (multi-tier piani). Shopify trattiene 0-20% di commissione sul revenue app (15% per app sotto 1M annuo, 0% per il primo 1M revenue del developer). Implementi in Remix template via app/billing.server.ts con redirect a Shopify checkout app billing.

Checklist operativa

Prima di considerare l'argomento implementato correttamente, verifica questa checklist sintetica: configurazione tecnica testata in ambiente di staging o development store, backup attivo prima di ogni modifica critica, documentazione interna aggiornata per il team operativo, training agli operatori che useranno la funzionalità, monitoraggio di metriche chiave (conversion rate, AOV, ticket support) per 30 giorni post-implementazione, revisione legale se l'implementazione tocca aspetti GDPR, fiscali o di pagamento, piano di rollback chiaro nel caso di problemi imprevisti, comunicazione ai clienti se il cambiamento influenza la loro esperienza (es. nuovo checkout, nuovi metodi di pagamento, nuovi tempi di spedizione). Una implementazione tecnica senza queste fasi di accompagnamento spesso non produce i risultati attesi e genera attriti interni o sui clienti.

Risorse utili e community

Per approfondire ulteriormente: la documentazione ufficiale Shopify su shopify.dev e help.shopify.com aggiorna costantemente le guide; il Shopify Community Forum ha thread attivi su quasi ogni argomento con risposte da Shopify Experts; Shopify Partner Academy offre corsi gratuiti per merchant e sviluppatori; YouTube channel ufficiale Shopify pubblica walkthrough delle nuove feature. Per il mercato italiano cerca community come Shopify Italia su Facebook o gruppi LinkedIn dedicati a e-commerce manager italiani: il confronto con altri merchant che vivono problemi simili è una scorciatoia preziosa rispetto a documentazione internazionale generica.

Una buona pratica supplementare è coinvolgere il proprio commercialista o consulente fiscale per qualsiasi configurazione che impatti su fatturazione, IVA o regimi speciali: in Italia ogni semplificazione tecnica deve essere accompagnata da verifica legale puntuale per evitare contestazioni successive. Allo stesso modo, valuta sempre l'impatto SEO di ogni cambiamento: monitora Search Console per le 4-6 settimane successive alla modifica, controlla che il numero di pagine indicizzate non cali e che le query principali continuino a posizionarsi. Per modifiche al tema, mantieni sempre una copia del tema precedente come fallback e documenta i cambiamenti in un changelog interno consultabile dal team. Una governance leggera ma costante è la differenza tra uno store che cresce nel tempo e uno che accumula debito tecnico nascosto.

Hai bisogno di aiuto?

Se vuoi un Shopify ottimizzato dal team di G Tech Group, scrivici tramite il modulo di contatto.