npm package: @itonomy/magento
Description: Reusable Magento integration module for Nuxt 4 applications.
Latest version: 0.1.5

# @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:

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

Then install dependencies:

```bash
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

```bash
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:

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

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

```bash
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):

```json
{}
```

#### 2) Registered Operation - products

- Mode: `Registered Operation`
- Operation: `products`
- Variables (JSON):

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

#### 3) Custom Query - products

- Mode: `Custom Query`
- Query:

```graphql
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):

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

#### 4) Custom Mutation - createEmptyCart

- Mode: `Custom Mutation`
- Mutation:

```graphql
mutation CreateEmptyCart {
  createEmptyCart
}
```

- Variables (JSON):

```json
{}
```

#### 5) Registered Operation - productDetails with `extraVariableDeclarations` and `extraSelections`

- Mode: `Registered Operation`
- Operation: `productDetails`
- extraVariableDeclarations:

```graphql
, $warehouseCode: String
```

- extraSelections:

```graphql
warehouse_stock(warehouse_code: $warehouseCode) {
  qty
  is_in_stock
}
```

- Variables (JSON):

```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:

```graphql
, $entityType: String
```

- extraSelections:

```graphql
frontend_input
entity_type
```

- Variables (JSON):

```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

```ts
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

```ts
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.