DEVREL-2671: Example for component.getInstanceCount() (#18)

Author: tim-webflow

src/components/PermissionsMap.tsx

@@ -53,6 +53,7 @@ export const permissionsMap: PermissionsMap = {
     getAllComponents: { permissions: ['canAccessCanvas'] },
     getComponentByName: { permissions: ['canAccessCanvas'] },
     getComponentByNameAndGroup: { permissions: ['canAccessCanvas'] },
+    getInstanceCount: { permissions: ['canAccessCanvas'] },
     enterComponent: { permissions: ['canModifyComponents'] },
     exitComponent: { permissions: ['canAccessCanvas'] },
   },

src/designer-extension-typings/api.d.ts

@@ -184,6 +184,29 @@ interface WebflowApi {
    * ```
    */
   getComponentByName(a: string, b?: string): Promise<Component>;
+  /**
+   * Gets the number of instances of a component.
+   * @returns A Promise that resolves to the number of instances of the component across the entire site.
+   * @example
+   * ```ts
+   * // Audit component usage across the site
+   * const components = await webflow.getAllComponents();
+   * for (const component of components) {
+   *   const name = await component.getName();
+   *   const count = await component.getInstanceCount();
+   *   console.log(`${name}: ${count} instances`);
+   * }
+   * // Guard against removing a component that's still in use
+   * const hero = components[0];
+   * const instanceCount = await hero.getInstanceCount();
+   * if (instanceCount > 0) {
+   *   console.log(`Cannot safely remove — ${instanceCount} instances exist`);
+   * } else {
+   *   await webflow.unregisterComponent(hero);
+   * }
+   * ```
+   */
+  getInstanceCount(): Promise<number>;
   /**
    * Focus the designer on a Component. When a component is in focus, all Globals pertain specifically to that
    * Component, not the entire Site.

src/examples/components.ts

@@ -64,6 +64,24 @@ export const Components = {
     console.log(marketingHero.id);
   },
 
+  getInstanceCount: async () => {
+    // Audit component usage across the site
+    const components = await webflow.getAllComponents();
+    for (const component of components) {
+      const name = await component.getName();
+      const count = await component.getInstanceCount();
+      console.log(`${name}: ${count} instances`);
+    }
+    // Guard against removing a component that's still in use
+    const hero = components[0];
+    const instanceCount = await hero.getInstanceCount();
+    if (instanceCount > 0) {
+      console.log(`Cannot safely remove — ${instanceCount} instances exist`);
+    } else {
+      await webflow.unregisterComponent(hero);
+    }
+  },
+
   createComponent: async () => {
     // Get selected element
     const rootElement = await webflow.getSelectedElement()