21/11/2025
Pellentesque arcu enim, euismod non quam placerat, blandit condimentum quam. Quisque vitae tellus vehicula, sollicitudin tortor et, porta nisi.
21/11/2025
Pellentesque arcu enim, euismod non quam placerat, blandit condimentum quam. Quisque vitae tellus vehicula, sollicitudin tortor et, porta nisi.
21/11/2025
Pellentesque arcu enim, euismod non quam placerat, blandit condimentum quam. Quisque vitae tellus vehicula, sollicitudin tortor et, porta nisi.
Sito Web: https://telaioshop.vercel.app/
Tra i trulli di Alberobello si trova "Il Telaio di Raffaella", una piccola realtà artigianale tessile dove Raffaella realizza tessuti fatti a mano con un antico telaio in legno. Ogni prodotto è realizzato con filati come il cotone, lino e seta e come puoi immaginare ogni pezzo è unico e irripetibile.
L'esigenza era chiara: portare questa bottega online con un e-commerce che rispettasse l'identità artigianale del brand, offrendo un'esperienza utente curata e professionale, senza però sostenere costi elevati di infrastruttura.
Ho quindi progettato e sviluppato un e-commerce su misura integrato con le API di Shopify. La gestione del magazzino, dei prodotti e dei pagamenti è delegata a Shopify, mentre il frontend è stato completamente personalizzato per trasmettere l'unicità e il calore della bottega.
Durante la scelta dello stack tecnologico, ho considerato due fattori chiave:
La scelta è ricaduta principalmente su: Next.js, Tailwind CSS, Shopify Storefront API e TypeScript.
Next.js è il framework su cui poggia l'intera applicazione. In questo progetto ho sfruttato in particolar modo:
getStaticProps e getStaticPaths per generare le pagine prodotto e le collezioni durante la build, garantendo performance elevate e tempi di caricamento minimi.next/image per servire le immagini dei prodotti nel formato e nella dimensione più adatti al dispositivo.Tailwind CSS è stato utilizzato per tutta la parte di styling. Le utility class mi hanno permesso di creare un design responsive in modo rapido e consistente, con animazioni personalizzate per arricchire l'esperienza utente:
module.exports = {
theme: {
extend: {
animation: {
pulse: "pulse 1s ease-in-out infinite",
rotate: "rotate 2s linear infinite",
color: "color 6s linear infinite",
fadeInOut: "fadeInOut 8s linear infinite",
},
},
},
};Queste animazioni sono state utilizzate per dare dinamicità agli elementi della pagina, come il logo animato e le transizioni tra le immagini dei prodotti.
TypeScript ha fornito il sistema di tipi necessario per gestire in modo sicuro i dati provenienti dalle API di Shopify. Con i tipi definiti per prodotti, collezioni e carrello, ho potuto lavorare con maggiore sicurezza e velocità, individuando errori a compile-time anziché a runtime.
Shopify è il cuore dell'e-commerce. Tramite le Storefront API (GraphQL), il frontend comunica direttamente con Shopify per:
Questo approccio "headless" permette di avere piena libertà creativa sul frontend, delegando a Shopify tutta la complessità della gestione ordini, pagamenti e inventario.
Una delle decisioni architetturali più importanti è stata la creazione di un livello di astrazione tra il frontend e le API di Shopify. Il progetto è strutturato con una directory framework che contiene:
Questa separazione rende il codice più manutenibile e, in futuro, renderebbe possibile sostituire Shopify con un altro backend senza dover riscrivere i componenti UI.
La comunicazione con le Storefront API avviene tramite una funzione fetchApi che esegue richieste POST verso l'endpoint GraphQL di Shopify:
import { API_URL, STOREFRONT_TOKEN } from "@framework/const";
const fetchApi = async <T>({
query,
variables,
}: ApiFetcherOptions): Promise<ApiFetcherResults<T>> => {
const res = await fetch(API_URL!, {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-Shopify-Storefront-Access-Token": STOREFRONT_TOKEN,
},
body: JSON.stringify({ query, variables }),
});
const { data, errors } = await res.json();
if (errors) {
throw new Error(errors[0].message ?? errors.message);
}
return { data };
};Le query GraphQL sono organizzate in file separati nella directory utils/queries, rendendo il codice pulito e facilmente estendibile.
Il carrello è implementato con un pattern di hook personalizzati basati su SWR, che garantisce un'esperienza utente fluida con aggiornamenti ottimistici e revalidazione automatica dei dati.
Gli hook principali sono:
useCart — Recupera lo stato corrente del carrellouseAddItem — Aggiunge un prodotto al carrellouseRemoveItem — Rimuove un prodottouseUpdateItem — Aggiorna la quantitàOgni operazione sul carrello si traduce in una mutation GraphQL verso Shopify, che aggiorna il checkout in tempo reale.
Il design è stato pensato per trasmettere calore e artigianalità. La homepage presenta un video dell'artigiana al lavoro al telaio (visibile su mobile) e un'immagine statica per desktop, accompagnata da una descrizione che racconta la storia della bottega.
Il logo del sito rappresenta una spoletta volante, uno strumento tipico dei telai artigianali. La spoletta l'ho realizzata in formato SVG utilizzando Adobe Illustrator, e tramite CSS le ho dato un'animazione che richiama il movimento reale della spoletta sul telaio. Questo dettaglio contribuisce a rafforzare l'identità visiva del sito e a trasmettere l'artigianalità del progetto.
La pagina prodotto è il cuore dell'esperienza di acquisto. Include:
export const getStaticPaths: GetStaticPaths = async () => {
const config = getConfig();
const { products } = await getAllProductsPaths(config);
return {
paths: products.map((p) => ({ params: { slug: p.slug } })),
fallback: false,
};
};
export const getStaticProps = async ({
params,
}: GetStaticPropsContext<{ slug: string }>) => {
const config = getConfig();
const { product } = await getProduct({
config,
variables: { slug: params?.slug },
});
return { props: { product } };
};Grazie a getStaticPaths e getStaticProps, tutte le pagine prodotto vengono generate staticamente durante la build, offrendo tempi di caricamento quasi istantanei.
Il carrello si apre come una sidebar laterale tramite un context provider (useUI) che gestisce lo stato dell'interfaccia. Quando l'utente aggiunge un prodotto, la sidebar si apre automaticamente mostrando il riepilogo dell'ordine con possibilità di procedere al checkout.
Per garantire una buona indicizzazione del sito, ho implementato:
const siteUrl = "https://www.telaiodiraffaella.com";
module.exports = {
siteUrl,
generateRobotsTxt: true,
additionalSitemaps: [
`${siteUrl}/sitemap.xml`,
`${siteUrl}/server-sitemap.xml`,
],
};Ho integrato Google Tag Manager con eventi personalizzati tramite il dataLayer per tracciare le azioni chiave degli utenti:
Questi dati permettono al cliente di monitorare il comportamento degli utenti e ottimizzare l'offerta di conseguenza.
Il sito è deployato su Vercel, che offre un'integrazione perfetta con Next.js. Ogni push sul branch principale attiva un deploy automatico, con preview deploy per i branch di sviluppo.
La combinazione di SSG e CDN di Vercel garantisce tempi di risposta bassissimi per l'utente finale, indipendentemente dalla sua posizione geografica. Il sito viene servito come pagine statiche, con le sole chiamate API necessarie per le operazioni del carrello.
Grazie a questo progetto ho affrontato diverse sfide tecniche:
Il risultato è un e-commerce performante, economico da mantenere e che riflette fedelmente l'identità artigianale del "Il Telaio di Raffaella".
