DISCLAIMER: This repository is currently only for doing some experiments. I am not yet 100% convinced on the approach here, and I am experimenting various other approaches to interact with metaobjects.

Metaobject Repository Documentation

Welcome to the documentation for Metaobject Repository, a fully-typed abstraction layer for working with Shopify metaobjects. The library helps you managing definitions (both metaobjects and metafields), metaobjects, metafields and storefront access tokens.

---

📦 Installation

npm install metaobject-repository

---

🚀 Quick Start

This library can be used in different environements:

• In Remix loader and actions for Shopify embedded app (using an authenticated GraphQL client).
• In Remix client loaders for Shopify embedded app using the direct access API.
• In Admin UI extensions using the direct access API.
• [TO BE DONE] In other contexts using the Storefront API.

Metaobjects

A minimal example to define a schema, create a metaobject, and delete it.

// definitions.ts
import { MetaobjectDefinitionSchema } from "metaobject-repository";

export const definitions = [
  {
    type: "$app:event",
    name: "Event",
    displayNameKey: "label",
    access: { storefront: "PUBLIC_READ" },
    capabilities: {
      translatable: { enabled: true },
      publishable: { enabled: true }
    },
    fields: [
      { name: "Label", key: "label", type: "single_line_text_field", validations: { max: 255 } },
      { name: "Banner", key: "banner", type: "file_reference", validations: { fileTypes: ["Image"] } }
    ]
  }
] as const satisfies MetaobjectDefinitionSchema;

// loader.ts
import { metaobjectDefinitions } from "./definitions";
import { createContext } from "metaobject-repository";

export const loader = async ({ request }: LoaderFunctionArgs) => {
  const { admin } = await authenticate.admin(request);
  
  const { eventRepository, metaobjectDefinitionManager } = createAdminContext({ client: admin.graphql, metaobjectDefinitions });

  // Create the schema on Shopify (dependencies between schemas are automatically resolved)
  await metaobjectDefinitionManager.createFromSchema();

  // Create an object, and populate the banner to fill references
  const event = await eventRepository.create({
    handle: "hello-world",
    fields: { label: "Hello World", banner: "gid://shopify/MediaImage/123" }
  }, { populate: ["banner" ]});

  // Delete the object
  await eventRepository.delete(event.system.id);
}

Metafields

A minimal example to define a schema, create a metafield, and delete it.

// definitions.ts
import { MetafieldDefinitionSchema } from "metaobject-repository";

export const definitions = [
  {
    type: "single_line_text_field",
    name: "Event",
    key: "event",
    namespace: "test"
  }
] as const satisfies MetafieldDefinitionSchema;

// loader.ts
import { metafieldDefinitions } from "./definitions";
import { createContext } from "metaobject-repository";

export const loader = async ({ request }: LoaderFunctionArgs) => {
  const { admin } = await authenticate.admin(request);
  
  const { metafieldRepository, metafieldDefinitionManager } = createAdminContext({ client: admin.graphql, metafieldDefinitions });

  // Create the schema on Shopify (dependencies between schemas are automatically resolved)
  await metafieldDefinitionManager.createFromSchema();

  // Create a metafield
  await metafieldRepository.setMetafields([
    { key: 'event', namespace: 'test', ownerId: 'gid://shopify/Product/123', value: 'something' }
  ])
  
  await metafieldRepository.delete({ key: 'event', namespace: 'test', ownerId: 'gid://shopify/Product/123' });
}

---

📚 Documentation

• Typing system
• Authentication
• Managing metaobject definitions
• Managing metaobjects
• Managing metafield definitions
• Managing metafields
• Storefront tokens
• Recipes

---

Roadmap

• Allowing to turn off automatic to camelCase / to snake_case.
• Adding a bulkUpsert method to upsert a high number of objects using a long standing job.
• Adding an export method to the repository to export up to 250 metaobjects.
• Adding a bulkExport method to export any number of metaobjects, using the bulk API.
• Adding a syncFromSchema method on the definition manager to sync definitions.

Ideas:

metaobjectRepository.query(MyQuery, { id: 'Foo' });