Guía de integración Clione + Hydrogen (Remix)

Renderiza las señales SEO de Clione en un storefront Shopify Hydrogen.

Instalar

npm install @clione/seo

Opción A: modo metafield (recomendado para Hydrogen)

Hydrogen ya consulta la Storefront API de Shopify. Añade el metafield clione.jsonld a tu query de producto — cero llamadas API extra.

1. Actualiza tu query de producto

query Product($handle: String!) {
  product(handle: $handle) {
    id
    title
    description
    # ... campos existentes
    metafields(identifiers: [
      { namespace: "clione", key: "jsonld" },
      { namespace: "global", key: "description_tag" },
      { namespace: "global", key: "title_tag" }
    ]) {
      namespace
      key
      value
    }
  }
}

2. Extrae y renderiza en tu loader

// routes/products.$handle.tsx
import { createClioneSeo } from '@clione/seo'
import { json, type LoaderFunctionArgs } from '@shopify/remix-oxygen'

export async function loader({ params, context }: LoaderFunctionArgs) {
  const { product } = await context.storefront.query(PRODUCT_QUERY, {
    variables: { handle: params.handle },
  })

  const clione = createClioneSeo({ source: 'metafield' })
  const signals = clione.extractSignals({
    id: product.id,
    metafields: product.metafields.filter(Boolean).map(m => ({
      namespace: m.namespace,
      key: m.key,
      value: m.value,
    })),
  })

  return json({ product, seoSignals: signals })
}

export default function ProductPage() {
  const { product, seoSignals } = useLoaderData<typeof loader>()

  return (
    <>
      {seoSignals.jsonLd && (
        <script
          type="application/ld+json"
          dangerouslySetInnerHTML={{
            __html: JSON.stringify(seoSignals.jsonLd),
          }}
        />
      )}
      {/* contenido de la página de producto */}
    </>
  )
}

// En la función meta de root.tsx:
export const meta: MetaFunction<typeof loader> = ({ data }) => {
  const signals = data?.seoSignals
  return [
    { title: signals?.metaTitle ?? data?.product?.title },
    { name: 'description', content: signals?.metaDescription ?? '' },
  ]
}

Opción B: modo API

Si prefieres no modificar tus queries de Storefront API:

// routes/products.$handle.tsx
import { createClioneSeo } from '@clione/seo'

export async function loader({ params, context }: LoaderFunctionArgs) {
  const clione = createClioneSeo({
    source: 'api',
    apiUrl: context.env.CLIONE_API_URL,
    apiKey: context.env.CLIONE_API_KEY,
    platform: 'shopify',
  })

  const [product, signals] = await Promise.all([
    context.storefront.query(PRODUCT_QUERY, { variables: { handle: params.handle } }),
    clione.getSignals('product', params.handle),
  ])

  return json({
    product: product.product,
    seoHead: clione.renderHead(signals),
  })
}

Variables de entorno

# Solo necesarias para el modo API
CLIONE_API_URL=https://your-clione-instance.com
CLIONE_API_KEY=sk-...

Por qué el modo metafield es mejor para Hydrogen

Hydrogen ya hace una llamada a la Storefront API por cada página de producto. Añadir 3 identificadores de metafield a esa query cuesta cero latencia extra. El modo API añade una segunda llamada de red durante SSR — sigue siendo rápida (cacheada), pero innecesaria cuando los datos ya están en Shopify.

Tipos de entidad soportados

Funciona para productos, colecciones y páginas — cualquier entidad con metafields de Clione.