Tento provides a simple yet powerful API for working with Shopify data, including metaobjects and metafields. It also provides a CLI tool for two-way synchronization between your local schema definition and Shopify.
You can install Tento with your preferred package manager:
npm install @drizzle-team/tento
yarn add @drizzle-team/tento
pnpm add @drizzle-team/tento
bun add @drizzle-team/tentoDeclare your Tento metaobjects schema in schema.ts file.
As of now Tento CLI only supports one schema file:
import { metaobject } from '@drizzle-team/tento';
export const designers = metaobject({
name: 'Designer',
type: 'designer',
fieldDefinitions: (f) => ({
fullName: f.singleLineTextField({
name: 'Full Name',
required: true,
validations: (v) => [v.min(5), v.max(100)],
}),
description: f.singleLineTextField({
name: 'Description',
required: true,
validations: (v) => [v.min(5), v.max(300)],
}),
link: f.url(({
name: 'Link',
validations: (v) => [v.allowedDomains(["github.com"])],
}),
}),
});import { tento } from '@drizzle-team/tento';
import * as schema from './schema';
// Using @shopify/shopify-api (or its wrappers)
import '@shopify/shopify-api/adapters/node';
import { shopifyApi, ApiVersion } from '@shopify/shopify-api';
const shopifyClient = shopifyApi({ ... });
const gqlClient = new shopifyApiClient.clients.Graphql({
session: ...,
});
// Using raw fetch
import { createClient } from '@drizzle-team/tento';
const gqlClient = createClient({
shop: 'your-shop-name',
headers: {
// any headers you need
// Content-Type is added automatically unless you override it
'X-Shopify-Access-Token': 'your-admin-api-access-token',
},
fetch: customFetch, // optionally provide your own fetch implementation
});
// Create Tento client from any Shopify client above
const client = tento({
client: gqlClient,
schema,
});
// Apply the local schema to Shopify
await client.applySchema();
// Query metaobjects
const designers = await tento.metaobjects.designers.list({
first: 10,
});
/*
{
_id: string;
_handle: string;
_updatedAt: Date;
fullName: string;
description: string;
link: string;
}[]
*/Now let's pull your existing Shopify Metaobjects schema, first we need to create a tento.config.ts file:
import { defineConfig } from '@drizzle-team/tento/cli';
export default defineConfig({
schemaPath: './src/schema.ts',
shop: 'd91122',
headers: {
'X-Shopify-Access-Token': process.env['SHOPIFY_ADMIN_API_TOKEN']!,
},
});Now let's run Tento CLI pull command
npx tento pull
yarn tento pull
pnpm tento pull
bun tento pullTento CLI will consume tento.config.ts and fetch your Shopify schema to your project schema.ts file:
import { metaobject } from '@drizzle-team/tento';
export const orm = metaobject({
name: 'ORM',
type: 'orm',
fieldDefinitions: (f) => ({
name: f.singleLineTextField({
name: 'Name',
required: true,
validations: (v) => [v.min(1), v.max(50)],
}),
git_hub_repo: f.url({
name: 'GitHub repo',
required: true,
validations: (v) => [v.allowedDomains(["github.com"])],
}),
stars: f.integer({
name: 'Stars',
required: true,
validations: (v) => [v.min(0)],
}),
datetime: f.dateTime({
validations: (v) => [v.min('2023-12-01T13:30:00Z'), v.max('2023-12-02T13:30:00Z')],
}),
multiline_text: f.multiLineTextField({
validations: (v) => [
v.min(1),
v.max(2),
v.regex(/^[a-zA-Z]+$/),
],
}),
decimal: f.decimal({
validations: (v) => [
v.min(1.0),
v.max(2.0),
v.maxPrecision(2),
],
}),
decimal_list: f.decimalList({
required: true,
validations: (v) => [
v.min(1.0),
v.max(2.0),
v.maxPrecision(2),
],
}),
date_list: f.dateList({
validations: (v) => [v.min('2023-12-01'), v.max('2023-12-02')],
}),
dimension: f.dimension({
validations: (v) => [v.min({ value: 1, unit: "METERS" }), v.max({ value: 5, unit: "FEET" })],
}),
dimension_list: f.dimensionList({
validations: (v) => [v.min({ value: 1, unit: "INCHES" }), v.max({ value: 5, unit: "YARDS" })],
}),
volume: f.volume({
validations: (v) => [v.min({ value: 1, unit: "MILLILITERS" }), v.max({ value: 4, unit: "PINTS" })],
}),
volume_list: f.volumeList({
validations: (v) => [v.min({ value: 1, unit: "CENTILITERS" }), v.max({ value: 4, unit: "IMPERIAL_FLUID_OUNCES" })],
}),
date: f.date({
validations: (v) => [v.min('2023-12-01'), v.max('2023-12-02')],
}),
weight: f.weight({
validations: (v) => [v.min({ value: 1, unit: "GRAMS" }), v.max({ value: 5, unit: "OUNCES" })],
}),
weight_list: f.weightList({
validations: (v) => [v.min({ value: 1, unit: "KILOGRAMS" }), v.max({ value: 100, unit: "POUNDS" })],
}),
}),
});
export const book = metaobject({
name: 'Book',
type: 'book',
fieldDefinitions: (f) => ({
title: f.singleLineTextField({
name: 'Title',
required: true,
validations: (v) => [v.min(1), v.max(100)],
}),
author: f.singleLineTextField({
name: 'Author',
required: true,
validations: (v) => [v.min(1), v.max(50)],
}),
isbn: f.singleLineTextField({
name: 'ISBN',
required: true,
validations: (v) => [v.regex(/^(97(8|9))?\d{9}(\d|X)$/)],
}),
genre: f.singleLineTextField({
name: 'Genre',
validations: (v) => [v.min(1), v.max(30)],
}),
language: f.singleLineTextField({
name: 'Language',
validations: (v) => [v.min(1), v.max(20)],
}),
summary: f.multiLineTextField({
name: 'Summary',
validations: (v) => [v.min(10), v.max(5000)],
}),
price: f.decimal({
name: 'Price',
validations: (v) => [
v.min(0.0),
v.max(999.99),
v.maxPrecision(2),
],
}),
publication_date: f.date({
name: 'Publication date',
validations: (v) => [v.min('2000-01-01'), v.max('2023-12-31')],
}),
page_count: f.integer({
name: 'Page count',
required: true,
validations: (v) => [v.min(1), v.max(2000)],
}),
cover_type: f.singleLineTextField({
name: 'Cover type',
validations: (v) => [v.min(1), v.max(20)],
}),
}),
});Whenever you change your locall schema - you can apply changes to your Shopify by using tento push command:
~ npx tento push
- Updated metaobject definition "ORM"
✅ All changes appliedIt will consume your tento.config.ts file, traverse your schema and apply any diffs to Shopify.
Tento supports all Shopify Metaobject API methods:
.list()
tento.metaobjects.designers.list({
query: {
$raw: 'state:disabled AND ("sale shopper" OR VIP)',
},
});
tento.metaobjects.designers.list({
query: ['Bob', 'Norman'],
});
tento.metaobjects.designers.list({
query: {
displayName: {
$raw: 'Bob Norman',
},
},
});
tento.metaobjects.designers.list({
query: {
displayName: 'Bob Norman',
updatedAt: new Date('2023-01-01'),
},
});
tento.metaobjects.designers.list({
query: {
updatedAt: {
$gte: new Date('2023-01-01'),
$lte: new Date('2024-01-01'),
},
},
});
tento.metaobjects.designers.list({
query: {
displayName: {
$not: 'bob',
},
},
});
tento.metaobjects.designers.list({
query: [{ $or: ['bob', 'norman'] }, 'Shopify'],
});
tento.metaobjects.designers.list({
query: [{ displayName: 'Bob' }, { $or: ['sale shopper', 'VIP'] }],
});
tento.metaobjects.designers.list({
query: {
displayName: 'Bob Norman',
},
});
tento.metaobjects.designers.list({
query: 'norm*',
});
tento.metaobjects.designers.list({
query: {
displayName: 'norm*',
},
});- Accept existing Shopify client instance
- Support OAuth
- Expose CLI operations as API
- Allow providing custom
fetchimplementation - Support all field types and validations
- Metafields management
- Assign metaobjects to resources and metafields
- Products management
- Support multiple schema files