@itonomy/magento

Reusable Magento integration module for Nuxt 4 applications.

Development

Local development (using source)

During development, you may want to use the package directly from its source instead of the published version. This allows instant updates without rebuilding or publishing In your Nuxt app (Main App) package.json:

{
  "dependencies": {
    "@itonomy/magento": "portal:../frontend-modules/packages/magento"
  }
}

Then install dependencies:

pnpm install
or
yarn install

Important

• In development, the package should expose source files (src) instead of dist
• This enables Nuxt to process the module correctly (auto-imports, composables, etc.)
• Changes in the Magento module will be reflected immediately without rebuild

⚠️ Important (Magento package requirement)

{
  "exports": {
    ".": {
     "types": "./dist/module.d.ts",
      "import": "./src/module.ts" // add this for development build
      // "import": "./dist/module.mjs" // remove it for development build
    }
  }
}

Production usage (published package)

{
  "dependencies": {
    "@itonomy/magento": "^0.1.3"
  }
}

What it provides

• Nuxt module registration with defineNuxtModule
• auto-imported Magento composables such as useMagento
• Nitro server handlers for /api/magento/graphql and /api/magento/rest/*
• reusable Magento runtime and API types

Build

pnpm install
pnpm --filter @itonomy/magento build

Playground (GraphQL test)

This module includes a Nuxt playground to test Magento GraphQL requests locally.

1. Copy the example env file:

cp packages/magento/playground/.env.example packages/magento/playground/.env

2. Update Magento endpoints in .env.
3. Run the playground:

pnpm dev:playground

From the playground UI you can test:

• Registered operation (storeConfig, products, etc.)
• Custom GraphQL query
• Custom GraphQL mutation

All requests are sent to POST /api/magento/graphql.

Playground sample data

1) Registered Operation - storeConfig

• Mode: Registered Operation
• Operation: storeConfig
• Variables (JSON):

{}

2) Registered Operation - products

• Mode: Registered Operation
• Operation: products
• Variables (JSON):

{
  "search": "shirt",
  "filter": {
    "price": {
      "from": "10",
      "to": "120"
    }
  },
  "currentPage": 1,
  "pageSize": 5
}

3) Custom Query - products

• Mode: Custom Query
• Query:

query Products($search: String, $currentPage: Int, $pageSize: Int) {
  products(search: $search, currentPage: $currentPage, pageSize: $pageSize) {
    total_count
    items {
      uid
      sku
      name
      stock_status
      price_range {
        minimum_price {
          final_price {
            value
            currency
          }
        }
      }
    }
  }
}

• Variables (JSON):

{
  "search": "shirt",
  "currentPage": 1,
  "pageSize": 5
}

4) Custom Mutation - createEmptyCart

• Mode: Custom Mutation
• Mutation:

mutation CreateEmptyCart {
  createEmptyCart
}

• Variables (JSON):

{}

5) Registered Operation - productDetails with extraVariableDeclarations and extraSelections

• Mode: Registered Operation
• Operation: productDetails
• extraVariableDeclarations:

, $warehouseCode: String

• extraSelections:

warehouse_stock(warehouse_code: $warehouseCode) {
  qty
  is_in_stock
}

• Variables (JSON):

{
  "urlKey": "example-product-slug",
  "warehouseCode": "WH-NL-01",
  "productReviewsPageSize": 5,
  "productReviewsPage": 1
}

6) Registered Operation - getProductAttributes with extraVariableDeclarations and extraSelections

• Mode: Registered Operation
• Operation: getProductAttributes
• extraVariableDeclarations:

, $entityType: String

• extraSelections:

frontend_input
entity_type

• Variables (JSON):

{
  "attributes": [{ "attribute_code": "color" }, { "attribute_code": "size" }],
  "entityType": "catalog_product"
}

Note: extraVariableDeclarations and extraSelections are applied only for operations that include placeholders in the query template. In this module, that is currently productDetails and getProductAttributes.

{
  "exports": {
    ".": {
      "types": "./dist/module.d.ts",
      // "import": "./src/module.ts" remove it for production build
      "import": "./dist/module.mjs" // add this for production build
    }
  }
}

Use in a Nuxt app

export default defineNuxtConfig({
  modules: ['@itonomy/magento'],
  magento: {
    graphqlUrl: process.env.MAGENTO_GRAPHQL_URL,
    restUrl: process.env.MAGENTO_REST_URL,
    baseUrl: process.env.MAGENTO_BASE_URL,
    defaultStore: 'default',
  },
})

Runtime type imports

import type { ProductDetailsItem } from '@itonomy/magento/runtime/types'

Notes

This package was extracted from the storefront app with minimal behavior changes to preserve the existing integration first.