shopify app import-custom-data-definitions

.changeset/bumpy-doors-change.md

@@ -0,0 +1,5 @@
+---
+'@shopify/app': minor
+---
+
+Add `shopify app import-custom-data-definitions` -- a command to automatically convert existing metafields and metaobjects to declarative TOML.

docs-shopify.dev/commands/app-import-custom-data-definitions.doc.ts

@@ -0,0 +1,34 @@
+// This is an autogenerated file. Don't edit this file manually.
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs'
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'app import-custom-data-definitions',
+  description: `Import metafield and metaobject definitions from your development store. [Read more about declarative custom data definitions](/docs/apps/build/custom-data/declarative-custom-data-definitions).`,
+  overviewPreviewDescription: `Import metafield and metaobject definitions.`,
+  type: 'command',
+  isVisualComponent: false,
+  defaultExample: {
+    codeblock: {
+      tabs: [
+        {
+          title: 'app import-custom-data-definitions',
+          code: './examples/app-import-custom-data-definitions.example.sh',
+          language: 'bash',
+        },
+      ],
+      title: 'app import-custom-data-definitions',
+    },
+  },
+  definitions: [
+  {
+    title: 'Flags',
+    description: 'The following flags are available for the `app import-custom-data-definitions` command:',
+    type: 'appimportcustomdatadefinitions',
+  },
+  ],
+  category: 'app',
+  related: [
+  ],
+}
+
+export default data

docs-shopify.dev/commands/examples/app-import-custom-data-definitions.example.sh

@@ -0,0 +1 @@
+shopify app import-custom-data-definitions [flags]

docs-shopify.dev/commands/interfaces/app-import-custom-data-definitions.interface.ts

@@ -0,0 +1,50 @@
+// This is an autogenerated file. Don't edit this file manually.
+export interface appimportcustomdatadefinitions {
+  /**
+   * The Client ID of your app.
+   * @environment SHOPIFY_FLAG_CLIENT_ID
+   */
+  '--client-id <value>'?: string
+
+  /**
+   * The name of the app configuration.
+   * @environment SHOPIFY_FLAG_APP_CONFIG
+   */
+  '-c, --config <value>'?: string
+
+  /**
+   * Include existing declared definitions in the output.
+   * @environment SHOPIFY_FLAG_INCLUDE_EXISTING
+   */
+  '--include-existing'?: ''
+
+  /**
+   * Disable color output.
+   * @environment SHOPIFY_FLAG_NO_COLOR
+   */
+  '--no-color'?: ''
+
+  /**
+   * The path to your app directory.
+   * @environment SHOPIFY_FLAG_PATH
+   */
+  '--path <value>'?: string
+
+  /**
+   * Reset all your settings.
+   * @environment SHOPIFY_FLAG_RESET
+   */
+  '--reset'?: ''
+
+  /**
+   * Store URL. Must be an existing development or Shopify Plus sandbox store.
+   * @environment SHOPIFY_FLAG_STORE
+   */
+  '-s, --store <value>'?: string
+
+  /**
+   * Increase the verbosity of the output.
+   * @environment SHOPIFY_FLAG_VERBOSE
+   */
+  '--verbose'?: ''
+}

docs-shopify.dev/generated/generated_docs_data.json

@@ -1750,6 +1750,116 @@
     "category": "app",
     "related": []
   },
+  {
+    "name": "app import-custom-data-definitions",
+    "description": "Import metafield and metaobject definitions from your development store. [Read more about declarative custom data definitions](/docs/apps/build/custom-data/declarative-custom-data-definitions).",
+    "overviewPreviewDescription": "Import metafield and metaobject definitions.",
+    "type": "command",
+    "isVisualComponent": false,
+    "defaultExample": {
+      "codeblock": {
+        "tabs": [
+          {
+            "title": "app import-custom-data-definitions",
+            "code": "shopify app import-custom-data-definitions [flags]",
+            "language": "bash"
+          }
+        ],
+        "title": "app import-custom-data-definitions"
+      }
+    },
+    "definitions": [
+      {
+        "title": "Flags",
+        "description": "The following flags are available for the `app import-custom-data-definitions` command:",
+        "type": "appimportcustomdatadefinitions",
+        "typeDefinitions": {
+          "appimportcustomdatadefinitions": {
+            "filePath": "docs-shopify.dev/commands/interfaces/app-import-custom-data-definitions.interface.ts",
+            "name": "appimportcustomdatadefinitions",
+            "description": "",
+            "members": [
+              {
+                "filePath": "docs-shopify.dev/commands/interfaces/app-import-custom-data-definitions.interface.ts",
+                "syntaxKind": "PropertySignature",
+                "name": "--client-id <value>",
+                "value": "string",
+                "description": "The Client ID of your app.",
+                "isOptional": true,
+                "environmentValue": "SHOPIFY_FLAG_CLIENT_ID"
+              },
+              {
+                "filePath": "docs-shopify.dev/commands/interfaces/app-import-custom-data-definitions.interface.ts",
+                "syntaxKind": "PropertySignature",
+                "name": "--include-existing",
+                "value": "\"\"",
+                "description": "Include existing declared definitions in the output.",
+                "isOptional": true,
+                "environmentValue": "SHOPIFY_FLAG_INCLUDE_EXISTING"
+              },
+              {
+                "filePath": "docs-shopify.dev/commands/interfaces/app-import-custom-data-definitions.interface.ts",
+                "syntaxKind": "PropertySignature",
+                "name": "--no-color",
+                "value": "\"\"",
+                "description": "Disable color output.",
+                "isOptional": true,
+                "environmentValue": "SHOPIFY_FLAG_NO_COLOR"
+              },
+              {
+                "filePath": "docs-shopify.dev/commands/interfaces/app-import-custom-data-definitions.interface.ts",
+                "syntaxKind": "PropertySignature",
+                "name": "--path <value>",
+                "value": "string",
+                "description": "The path to your app directory.",
+                "isOptional": true,
+                "environmentValue": "SHOPIFY_FLAG_PATH"
+              },
+              {
+                "filePath": "docs-shopify.dev/commands/interfaces/app-import-custom-data-definitions.interface.ts",
+                "syntaxKind": "PropertySignature",
+                "name": "--reset",
+                "value": "\"\"",
+                "description": "Reset all your settings.",
+                "isOptional": true,
+                "environmentValue": "SHOPIFY_FLAG_RESET"
+              },
+              {
+                "filePath": "docs-shopify.dev/commands/interfaces/app-import-custom-data-definitions.interface.ts",
+                "syntaxKind": "PropertySignature",
+                "name": "--verbose",
+                "value": "\"\"",
+                "description": "Increase the verbosity of the output.",
+                "isOptional": true,
+                "environmentValue": "SHOPIFY_FLAG_VERBOSE"
+              },
+              {
+                "filePath": "docs-shopify.dev/commands/interfaces/app-import-custom-data-definitions.interface.ts",
+                "syntaxKind": "PropertySignature",
+                "name": "-c, --config <value>",
+                "value": "string",
+                "description": "The name of the app configuration.",
+                "isOptional": true,
+                "environmentValue": "SHOPIFY_FLAG_APP_CONFIG"
+              },
+              {
+                "filePath": "docs-shopify.dev/commands/interfaces/app-import-custom-data-definitions.interface.ts",
+                "syntaxKind": "PropertySignature",
+                "name": "-s, --store <value>",
+                "value": "string",
+                "description": "Store URL. Must be an existing development or Shopify Plus sandbox store.",
+                "isOptional": true,
+                "environmentValue": "SHOPIFY_FLAG_STORE"
+              }
+            ],
+            "value": "export interface appimportcustomdatadefinitions {\n  /**\n   * The Client ID of your app.\n   * @environment SHOPIFY_FLAG_CLIENT_ID\n   */\n  '--client-id <value>'?: string\n\n  /**\n   * The name of the app configuration.\n   * @environment SHOPIFY_FLAG_APP_CONFIG\n   */\n  '-c, --config <value>'?: string\n\n  /**\n   * Include existing declared definitions in the output.\n   * @environment SHOPIFY_FLAG_INCLUDE_EXISTING\n   */\n  '--include-existing'?: ''\n\n  /**\n   * Disable color output.\n   * @environment SHOPIFY_FLAG_NO_COLOR\n   */\n  '--no-color'?: ''\n\n  /**\n   * The path to your app directory.\n   * @environment SHOPIFY_FLAG_PATH\n   */\n  '--path <value>'?: string\n\n  /**\n   * Reset all your settings.\n   * @environment SHOPIFY_FLAG_RESET\n   */\n  '--reset'?: ''\n\n  /**\n   * Store URL. Must be an existing development or Shopify Plus sandbox store.\n   * @environment SHOPIFY_FLAG_STORE\n   */\n  '-s, --store <value>'?: string\n\n  /**\n   * Increase the verbosity of the output.\n   * @environment SHOPIFY_FLAG_VERBOSE\n   */\n  '--verbose'?: ''\n}"
+          }
+        }
+      }
+    ],
+    "category": "app",
+    "related": []
+  },
   {
     "name": "app import-extensions",
     "description": "Import dashboard-managed extensions into your app.",

packages/app/src/cli/commands/app/import-custom-data-definitions.ts

@@ -0,0 +1,69 @@
+import {appFlags} from '../../flags.js'
+import {checkFolderIsValidApp} from '../../models/app/loader.js'
+import AppLinkedCommand, {AppLinkedCommandOutput} from '../../utilities/app-linked-command.js'
+import {linkedAppContext} from '../../services/app-context.js'
+import {storeContext} from '../../services/store-context.js'
+import {importDeclarativeDefinitions} from '../../services/generate/shop-import/declarative-definitions.js'
+import {Flags} from '@oclif/core'
+import {normalizeStoreFqdn} from '@shopify/cli-kit/node/context/fqdn'
+import {globalFlags} from '@shopify/cli-kit/node/cli'
+import {renderSingleTask} from '@shopify/cli-kit/node/ui'
+import {outputContent} from '@shopify/cli-kit/node/output'
+
+export default class ImportCustomDataDefinitions extends AppLinkedCommand {
+  static summary = 'Import metafield and metaobject definitions.'
+
+  static descriptionWithMarkdown = `Import metafield and metaobject definitions from your development store. [Read more about declarative custom data definitions](https://shopify.dev/docs/apps/build/custom-data/declarative-custom-data-definitions).`
+
+  static description = this.descriptionWithoutMarkdown()
+
+  static flags = {
+    ...globalFlags,
+    ...appFlags,
+    store: Flags.string({
+      char: 's',
+      description: 'Store URL. Must be an existing development or Shopify Plus sandbox store.',
+      env: 'SHOPIFY_FLAG_STORE',
+      parse: async (input) => normalizeStoreFqdn(input),
+    }),
+    'include-existing': Flags.boolean({
+      description: 'Include existing declared definitions in the output.',
+      default: false,
+      env: 'SHOPIFY_FLAG_INCLUDE_EXISTING',
+    }),
+  }
+
+  public async run(): Promise<AppLinkedCommandOutput> {
+    const {appContextResult, ...options} = await renderSingleTask({
+      title: outputContent`Loading application`,
+      task: async () => {
+        const {flags} = await this.parse(ImportCustomDataDefinitions)
+
+        await checkFolderIsValidApp(flags.path)
+
+        const appContextResult = await linkedAppContext({
+          directory: flags.path,
+          clientId: flags['client-id'],
+          forceRelink: flags.reset,
+          userProvidedConfigName: flags.config,
+        })
+        const store = await storeContext({
+          appContextResult,
+          storeFqdn: flags.store,
+          forceReselectStore: flags.reset,
+        })
+
+        return {
+          appContextResult,
+          appConfiguration: appContextResult.app.configuration,
+          remoteApp: appContextResult.remoteApp,
+          store,
+          includeExistingDeclaredDefinitions: flags['include-existing'],
+        }
+      },
+    })
+    await importDeclarativeDefinitions(options)
+
+    return {app: appContextResult.app}
+  }
+}

packages/app/src/cli/index.ts

@@ -32,6 +32,7 @@ import AppLinkedCommand from './utilities/app-linked-command.js'
 import DevClean from './commands/app/dev/clean.js'
 import AppUnlinkedCommand from './utilities/app-unlinked-command.js'
 import FunctionInfo from './commands/app/function/info.js'
+import ImportCustomDataDefinitions from './commands/app/import-custom-data-definitions.js'
 
 /**
  * All app commands should extend AppCommand.
@@ -44,6 +45,7 @@ export const commands: {[key: string]: typeof AppLinkedCommand | typeof AppUnlin
   'app:dev:clean': DevClean,
   'app:logs': Logs,
   'app:logs:sources': Sources,
+  'app:import-custom-data-definitions': ImportCustomDataDefinitions,
   'app:import-extensions': ImportExtensions,
   'app:info': AppInfo,
   'app:init': Init,

packages/cli/README.md

@@ -16,6 +16,7 @@
 * [`shopify app function schema`](#shopify-app-function-schema)
 * [`shopify app function typegen`](#shopify-app-function-typegen)
 * [`shopify app generate extension`](#shopify-app-generate-extension)
+* [`shopify app import-custom-data-definitions`](#shopify-app-import-custom-data-definitions)
 * [`shopify app import-extensions`](#shopify-app-import-extensions)
 * [`shopify app info`](#shopify-app-info)
 * [`shopify app init`](#shopify-app-init)
@@ -548,6 +549,32 @@ DESCRIPTION
   refer to "App structure" (https://shopify.dev/docs/apps/tools/cli/structure) and the documentation for your extension.
 ```
 
+## `shopify app import-custom-data-definitions`
+
+Import metafield and metaobject definitions.
+
+```
+USAGE
+  $ shopify app import-custom-data-definitions [--client-id <value> | -c <value>] [--include-existing] [--no-color] [--path <value>]
+    [--reset | ] [-s <value>] [--verbose]
+
+FLAGS
+  -c, --config=<value>     The name of the app configuration.
+  -s, --store=<value>      Store URL. Must be an existing development or Shopify Plus sandbox store.
+      --client-id=<value>  The Client ID of your app.
+      --include-existing   Include existing declared definitions in the output.
+      --no-color           Disable color output.
+      --path=<value>       The path to your app directory.
+      --reset              Reset all your settings.
+      --verbose            Increase the verbosity of the output.
+
+DESCRIPTION
+  Import metafield and metaobject definitions.
+
+  Import metafield and metaobject definitions from your development store. "Read more about declarative custom data
+  definitions" (https://shopify.dev/docs/apps/build/custom-data/declarative-custom-data-definitions).
+```
+
 ## `shopify app import-extensions`
 
 Import dashboard-managed extensions into your app.