Migrations with Tento CLI

Shopify Metaobject and Metafield definitions require you to specify a strict schema of definitions and if (when) you need to change those entities - you will need to do it via migrations.

Overview

This guide assumes familiarity with:

Get started with Tento - read here
Tento schema foundamentals - read here

Tento has a CLI tool for managing Shopify Metaobjects and Metafields schema definitions.

Based on your schema, Tento let’s you push your definitions schema directly to the Shopify, pull schema definitions from Shopify and has a couple of commands.

npm

yarn

pnpm

bun

npx tento pull
npx tento push

yarn tento pull
yarn tento push

pnpm tento pull
pnpm tento push

bun tento pull
bun tento push


`tento pull`	lets you pull (introspect) Shopify definitions schema, convert it to Tento schema and save it to your codebase, see here
`tento push`	lets you push your Tento definitions schema directly to Shopify, see here

tento.config.ts

Tento migrations is configured through tento.config.ts configuration file.
It’s required to provide schemaPath, shop and X-Shopify-Access-Token for Tento.

📦 <project root>
 ├ 📂 src
 ├ 📜 .env
 ├ 📜 tento.config.ts  <--- Tento config file
 ├ 📜 package.json
 └ 📜 tsconfig.json

import 'dotenv/config';
import { defineConfig } from "@drizzle-team/tento/cli";

export default defineConfig({
  schemaPath: './src/schema.ts',
  shop: process.env.SHOPIFY_SHOP_ID!,
  headers: {
    'X-Shopify-Access-Token': process.env.SHOPIFY_ACCESS_TOKEN!,
  },
});

IMPORTANT

To have understanding of what SHOPIFY_SHOP_ID and SHOPIFY_ACCESS_TOKEN variables represent go through Tento Get started with OAuth.

`pull`

tento pull lets literally pull (introspect) your Shopify definitions schema and generate schema.ts tento schema file.

How it works under the hood?

When you run pull command it will:

Pull Metaobject and Metafield definitions schema from Shopify
Generate schema.ts tento schema file and save it to out folder

                                   ┌────────────────────────┐
                                   │                        │
┌──────────────────────────┐       │                        │
│ ~ tento pull             │       │                        │
└─┬────────────────────────┘       │        Shopify         │
  │                                │                        │
  └ Pull definitions schema -----> │                        │
  ┌ Generate Tento schema   <----- │                        │
  │ TypeScript file                └────────────────────────┘
  │
  v

import { metaobject, metafield } from '@drizzle-team/tento';

export const description = metafield({
  name: "Description",
  key: "description",
  namespace: "custom",
  ownerType: "PRODUCT",
  fieldDefinition: (f) => f.multiLineTextField(),
});

export const designer = metaobject({
  name: "Designer",
  type: "designer",
  fieldDefinitions: (f) => ({
    name: f.singleLineTextField({
      name: "Title",
      required: true,
      validations: (v) => [v.min(1), v.max(50)],
    }),
    description: f.multiLineTextField({
      name: "Description",
    }),
    website: f.url({
      name: "Website",
    }),
  }),
});

`push`

tento push lets literally push your Tento definitions schema directly to Shopify.

How it works under the hood?

When you run Tento push command it will:

Read through your Tento definitions schema file
Pull (introspect) Shopify definitions schema
Based on differences between those two it will generate list of definitions to create, update or delete
Apply those differences to the Shopify

import { metaobject, metafield } from '@drizzle-team/tento';

export const description = metafield({
  name: "Description",
  key: "description",
  namespace: "custom",
  ownerType: "PRODUCT",
  fieldDefinition: (f) => f.multiLineTextField(),
});

export const designer = metaobject({
  name: "Designer",
  type: "designer",
  fieldDefinitions: (f) => ({
    name: f.singleLineTextField({
      name: "Title",
      required: true,
      validations: (v) => [v.min(1), v.max(50)],
    }),
    description: f.multiLineTextField({
      name: "Description",
    }),
    website: f.url({
      name: "Website",
    }),
  }),
});

┌─────────────────────┐                  
│ ~ tento push        │                  
└─┬───────────────────┘                  
  │                                            ┌──────────────────────────┐
  └ Pull current definitions schema ---------> │                          │
                                               │                          │
  ┌ Generate alternations based on diff <----  │         Shopify          │
  │                                            │                          │
  └ Apply differences to the Shopify ------->  │                          │
                                       │       └──────────────────────────┘
                                       │
  ┌────────────────────────────────────┴────────────────┐
   create metafield description, create metaobject designer;

Client

Tento also supports apply and remove schema definitions using client.

Apply

option	default	values	description
`unknownEntities`	`ignore`	`ignore`, `remove`	helps define the scope of metaobjects and metafields to be migrated, preventing unnecessary downloads and avoiding the deletion of other existing items

import 'dotenv/config';
import '@shopify/shopify-api/adapters/web-api';
import * as schema from './db/schema';
import { createClient, tento } from '@drizzle-team/tento';

const client = tento({
  client: createClient({
    shop: process.env.SHOPIFY_SHOP_ID!,
    headers: {
      "X-Shopify-Access-Token": process.env.SHOPIFY_ACCESS_TOKEN!,
    },
  }),
  schema,
});

async function main() {
  // 'ignore' strategy as default
  await client.applySchema();

  // you can specify explicitly configuration option you want
  await client.applySchema({ unknownEntities: "ignore" });
  await client.applySchema({ unknownEntities: "delete" });
}

main();


`ignore`	means that only the metaobjects and metafields from your definitions schema will be processed.
`delete`	means that all metaobjects and metafields will be processed. If you select this option and run command, we will create/ update your schema in Shopify and remove all metaobjects and metafields that do not exist in your schema.

Remove

option	default	values	description
`unknownEntities`	`ignore`	`ignore`, `remove`	helps define the scope of metaobjects and metafields to be migrated, preventing unnecessary downloads and avoiding the deletion of other existing items

import 'dotenv/config';
import '@shopify/shopify-api/adapters/web-api';
import * as schema from './db/schema';
import { createClient, tento } from '@drizzle-team/tento';

const client = tento({
  client: createClient({
    shop: process.env.SHOPIFY_SHOP_ID!,
    headers: {
      "X-Shopify-Access-Token": process.env.SHOPIFY_ACCESS_TOKEN!,
    },
  }),
  schema,
});

async function main() {
  // 'ignore' strategy as default
  await client.removeSchema();

  // you can specify explicitly configuration option you want
  await client.removeSchema({ unknownEntities: "ignore" });
  await client.removeSchema({ unknownEntities: "delete" });
}

main();


`ignore`	means that only the metaobjects and metafields from your definitions schema will be processed.
`delete`	means that all metaobjects and metafields will be processed. If you select this option and run command, we will create/ update your schema in Shopify and remove all metaobjects and metafields that do not exist in your schema.