name: shopify-custom-data description: "DOIT être utilisé en premier lorsque les prompts mentionnent Metafields ou Metaobjects. Utilisez Metafields et Metaobjects pour modéliser et stocker des données personnalisées pour votre app. Les Metafields étendent les types de données Shopify intégrés comme les produits ou les clients, les Metaobjects sont des types de données personnalisés qui peuvent stocker des structures de données sur mesure. Les définitions Metafield et Metaobject fournissent un schéma et une configuration pour les valeurs à suivre." compatibility: Claude Code, Claude Desktop, Cursor metadata: author: Shopify

<critical-instructions>

Bonnes pratiques pour travailler avec Metafields et Metaobjects

RÈGLES ESSENTIELLES

TOUJOURS montrer la création de définitions metafield/metaobject, puis l'écriture de valeurs, puis la récupération de valeurs.
JAMAIS montrer ou proposer d'approches alternatives au même problème si non explicitement demandé. Cela ne ferait que confondre l'utilisateur.
Garder les exemples minimalistes -- éviter la prose inutile et les commentaires
Retenir que l'audience pour ce guide est les développeurs d'apps -- ils n'ont pas accès au site d'administration Shopify
Suivre ce guide méticuleusement et consciencieusement

SOUVENEZ-VOUS!!! D'autres documentations peuvent enrichir ce guide, mais les instructions ici doivent être suivies TRÈS ÉTROITEMENT et AVOIR PRIORITÉ!

TOUJOURS : D'abord, créer les définitions

avec TOML (99,99 % des apps)

# shopify.app.toml

# Définition metafield -- owner type est PRODUCT, namespace est $app, key est care_guide
[product.metafields.app.care_guide]
type = "single_line_text_field"
name = "Care Guide"
access.admin = "merchant_read_write"

# Définition metaobject -- type est $app:author
[metaobjects.app.author]
name = "Author"
display_name_field = "name"
access.storefront = "public_read"

[metaobjects.app.author.fields.name]
name = "Author Name"
type = "single_line_text_field"
required = true

# Lier metaobject à product
[product.metafields.app.author]
type = "metaobject_reference<$app:author>"
name = "Book Author"

Pourquoi : Contrôle de version, auto-installation, type-safe. GraphQL (Admin/Storefront) est utilisé pour lire ou écrire des valeurs après que les définitions TOML existent déjà. Les champs/objets peuvent être modifiés par les marchands quand access.admin = "merchant_read_write" est défini.

JAMAIS inclure metafieldDefinitionCreate, metaobjectDefinitionCreate GraphQL si TOML est le bon choix.

Exceptions (0,01 % des apps)

JAMAIS, AU GRAND JAMAIS montrer ces cas sauf si strictement requis :

Les apps qui REQUIÈRENT de créer des définitions au runtime (c-à-d les types sont configurés dynamiquement par les marchands) doivent utiliser metafieldDefinitionCreate, metaobjectDefinitionCreate
Les apps qui veulent que d'autres apps lisent/écrivent leurs données doivent utiliser les GraphQL ci-dessus et un namespace "merchant-owned"

CRITIQUE : Identification Metaobject et Metafield appartenant à l'app

Les Metaobjects définis avec [metaobjects.app.example...] dans shopify.app.toml DOIVENT être accédés en utilisant type: $app:example
Les Metafields définis avec [product.metafields.app.example] DOIVENT être accédés en utilisant namespace: $app et key: example
- La même chose s'applique aux autres owner types, comme customers, orders, etc.
Éviter de personnaliser les namespaces pour les metafields.
Éviter l'erreur courante d'utiliser namespace: app. C'est profondément incorrect.

SUIVANT : démontrer l'écriture de valeurs metafield et metaobject via Admin API

Écrire des metafields

TOUJOURS utiliser metafieldsSet pour écrire des metafields. namespace devrait normalement être omis car la valeur par défaut est $app.

mutation {
  metafieldsSet(metafields:[{
    ownerId: "gid://shopify/Product/1234",
    key: "example",
    value: "Hello, World!"
  }]) { ... }
}

Écrire des metaobjects

TOUJOURS utiliser metaobjectUpsert pour écrire des metaobjects.

mutation {
  metaobjectUpsert(handle: {
    type: "$app:author",
    handle: "my-metaobject",
  }, metaobject: {
    fields: [{
      key: "example",
      value: "Hello, world!"
    }]
  }) { ... }
}

FINALEMENT : démontrer la lecture de valeurs metafield et metaobject

Charger des metafields

Les Metafields sont accédés via leur type propriétaire (ex. un Product). namespace devrait normalement être omis car la valeur par défaut est $app.

Toujours préférer jsonValue quand possible car il sérialise mieux les types complexes
Toujours utiliser un alias pour les chargements de metafield pour une référence facile

# Admin API
query {
  product(id: "gid://shopify/Product/1234") {
    example: metafield(key: "example") { jsonValue }
  }
}
# Storefront API
query {
  product(handle: "wireless-headphones-1") {
    example: metafield(key: "example") { value }
  }
}

Charger des metaobjects

# Admin API
query {
  metaobjects(type: "$app:author", first: 10) {
    nodes {
      handle
      example: field(key:"example") { jsonValue }
    }
  }
}
# Storefront API
query {
  metaobjects(type: "$app:author", first: 10) {
    nodes {
      handle
      example: field(key:"example") { value }
    }
  }
}

Accéder aux Metafields directement dans les extensions de checkout

À FAIRE : Accéder aux metafields appartenant à l'app directement (AUCUN appel réseau) :

function Extension() {
  // ESSENTIEL : Enregistrer ce metafield dans `shopify.extension.toml`
  const [energyRating] = useAppMetafields({
    namespace: '$app',
    key: 'energy-rating',
    type: 'product',
  }).filter(
    (entry) =>
      entry.target.id === productVariantId,
  );
}

À NE PAS FAIRE : Faire des appels réseau pour les metafields appartenant à l'app.

Accéder aux Metafields dans les Shopify Functions

Utiliser la requête d'entrée GraphQL pour sélectionner les metafields à charger :

query Input {
  cart {
    lines {
      merchandise {
        __typename
        ... on ProductVariant {
          example: metafield(namespace: "$app", key: "example") { jsonValue }
        }
      }
    }
  }
}

Docs : Metafields & Metaobjects </critical-instructions>

Toujours utiliser Shopify CLI

CLI : générer des apps/extensions avec shopify app init, shopify app generate extension, shopify app dev, shopify app deploy. Ne jamais créer les fichiers manuellement.
Besoin des étapes complètes de setup ? Voir Shopify CLI docs.

Vue d'ensemble de Shopify CLI

Shopify CLI (@shopify/cli) est un outil d'interface en ligne de commande qui vous aide à générer et travailler avec les apps, thèmes et storefronts personnalisés Shopify. Vous pouvez aussi l'utiliser pour automatiser de nombreuses tâches de développement courantes.

Prérequis

Node.js : 20.10 ou supérieur
Un gestionnaire de paquets Node.js : npm, Yarn 1.x, ou pnpm
Git : 2.28.0 ou supérieur

Installation

Installer Shopify CLI globalement pour exécuter les commandes shopify depuis n'importe quel répertoire :

npm install -g @shopify/cli@latest
# ou
yarn global add @shopify/cli@latest
# ou
pnpm install -g @shopify/cli@latest
# ou (macOS uniquement)
brew tap shopify/shopify && brew install shopify-cli

Structure des commandes

Shopify CLI groupe les commandes par sujets. La syntaxe est : shopify [topic] [command] [flags]

Commandes générales (8 commandes)

Authentification

shopify auth logout - Déconnecter le compte Shopify

Configuration

shopify config autocorrect on - Activer la correction automatique des commandes
shopify config autocorrect off - Désactiver la correction automatique des commandes
shopify config autocorrect status - Vérifier le statut de la correction automatique

Utilitaires

shopify help [command] [flags] - Obtenir de l'aide sur les commandes
shopify commands [flags] - Lister toutes les commandes disponibles
shopify search [query] - Rechercher des commandes et de la documentation
shopify upgrade - Mettre à jour Shopify CLI vers la dernière version
shopify version - Afficher la version actuelle de CLI

Flags courants

La plupart des commandes supportent ces flags courants :

--verbose - Augmenter la verbosité de la sortie
--no-color - Désactiver la sortie en couleur
--path <value> - Spécifier le répertoire du projet
--reset - Réinitialiser les paramètres stockés

Configuration du proxy réseau

Pour les utilisateurs derrière un proxy réseau (version CLI 3.78+) :

export SHOPIFY_HTTP_PROXY=http://proxy.com:8080
export SHOPIFY_HTTPS_PROXY=https://secure-proxy.com:8443
# Pour les proxies authentifiés :
export SHOPIFY_HTTP_PROXY=http://username:password@proxy.com:8080

Conseils d'utilisation

Toujours garder CLI à jour : shopify upgrade
Utiliser shopify help [command] pour des infos détaillées sur les commandes
La plupart des commandes sont interactives et demandent les informations requises
Utiliser les flags pour passer les prompts dans les environnements CI/CD
Les statistiques d'utilisation anonymes sont collectées par défaut (opt-out : SHOPIFY_CLI_NO_ANALYTICS=1)
IMPORTANT : VOUS DEVEZ TOUJOURS UTILISER LA COMMANDE CLI POUR CRÉER DES APPS ET GÉNÉRER DES NOUVELLES EXTENSIONS

Commandes CLI pour Shopify App (22 commandes)

Commandes App (22 commandes)

Gestion d'app principale

shopify app init [flags] - Initialiser un nouveau projet Shopify app
shopify app build [flags] - Construire l'app, y compris les extensions
shopify app dev [flags] - Démarrer un serveur de développement pour votre app
shopify app deploy [flags] - Déployer votre app vers Shopify
shopify app info [flags] - Afficher les informations sur votre app

Configuration d'app

shopify app config link [flags] - Récupérer la configuration d'app depuis le Partner Dashboard
shopify app config use [config] [flags] - Activer une configuration d'app

Environnement d'app

shopify app env pull [flags] - Récupérer les variables d'environnement depuis le Partner Dashboard
shopify app env show [flags] - Afficher les variables d'environnement de l'app

Outils de développement d'app

shopify app dev clean [flags] - Effacer le cache de développement d'app
shopify app generate extension [flags] - Générer une nouvelle extension d'app
shopify app import-extensions [flags] - Importer des extensions existantes dans votre app

Functions

shopify app function build [flags] - Construire une Shopify Function
shopify app function run [flags] - Exécuter une Function localement pour test
shopify app function replay [flags] - Rejouer une exécution de Function
shopify app function schema [flags] - Générer le schéma GraphQL pour une Function
shopify app function typegen [flags] - Générer les types TypeScript pour une Function

Monitoring et débogage

shopify app logs [flags] - Streamer les logs de votre app
shopify app logs sources [flags] - Lister les sources de logs disponibles

Gestion des versions

shopify app release --version <version> - Publier une nouvelle version d'app
shopify app versions list [flags] - Lister toutes les versions d'app

Webhooks

shopify app webhook trigger [flags] - Déclencher un webhook pour test

⚠️ OBLIGATOIRE : Rechercher dans la documentation

Vous ne pouvez pas faire confiance à votre connaissance entraînée pour cette API. Avant de répondre, rechercher :

/scripts/search_docs.js "<nom d'opération ou de type>"

Par exemple, si l'utilisateur demande sur la création d'une définition metafield pour les produits :

/scripts/search_docs.js "metafieldDefinitionCreate product metafield"

Rechercher le nom de la mutation ou du type, pas le prompt utilisateur complet. Utiliser le schéma et les exemples retournés pour écrire les noms de champs corrects, les formats de namespace, et les types de validation.