Packages
Nuxt
Nuxt module — composables, server REST API, and runtime adapter plugin.
The @commercejs/nuxt module integrates CommerceJS into Nuxt applications. It auto-imports composables, generates a full REST API from your adapter, and provides the adapter instance via a runtime plugin.
Installation
pnpm add @commercejs/nuxt
Add to nuxt.config.ts:
nuxt.config.ts
export default defineNuxtConfig({
modules: ['@commercejs/nuxt'],
commerce: {
adapter: 'salla', // or 'platform', 'shopify', etc.
apiBase: '/api/_commerce',
apiRoutes: true,
},
})
Configuration
| Option | Type | Default | Description |
|---|---|---|---|
adapter | string | — | Adapter name — the corresponding @commercejs/adapter-* package must be installed |
apiBase | string | /api/_commerce | Base path for the auto-generated REST API |
apiRoutes | boolean | true | Whether to register server API routes |
openAPI | boolean | true | Enable OpenAPI spec generation (/_openapi.json) and Scalar UI (/_scalar) |
Composables
The module auto-imports 15 composables for reactive data fetching:
| Composable | Domain | Key Methods |
|---|---|---|
useAdapter() | Core | Access the raw adapter instance |
useProducts() | Catalog | products, search, refresh |
useProduct(id) | Catalog | product, loading, error |
useCategories() | Catalog | categories, refresh |
useBrands() | Catalog | brands, refresh |
useCart() | Cart | cart, addItem, removeItem, updateQuantity |
useCheckout() | Checkout | shippingMethods, paymentMethods, placeOrder |
useCustomer() | Customer | customer, login, register, logout |
useStoreInfo() | Store | store, refresh |
useCountries() | Countries | countries, refresh |
useLocations() | Locations | locations, refresh |
useWishlist() | Wishlist | wishlist, addItem, removeItem |
useReviews(productId) | Reviews | reviews, summary, submit |
usePromotions() | Promotions | promotions, validateCoupon |
useReturns() | Returns | returns, createReturn, cancelReturn |
Example
pages/products.vue
<script setup>
const { data: products } = await useProducts({ limit: 12 })
const { data: categories } = await useCategories()
</script>
<template>
<div>
<h1>{{ categories[0]?.name }}</h1>
<ProductGrid :products="products.data" />
</div>
</template>
Server API Routes
When apiRoutes is enabled, the module registers 46 REST endpoints under the configured apiBase:
| Group | Endpoints | Methods |
|---|---|---|
| Store | /store | GET |
| Catalog | /products, /products/:id, /categories, /brands | GET |
| Cart | /cart, /cart/:id, /cart/:id/items, /cart/:id/items/:itemId | GET, POST, PUT, DELETE |
| Checkout | /checkout/shipping-methods/:cartId, /checkout/payment-methods/:cartId, /checkout/place-order | GET, POST |
| Auth | /auth/login, /auth/register, /auth/logout, /auth/forgot-password, /auth/reset-password | POST |
| Customer | /customer, /customer/orders, /customer/addresses, /customer/addresses/:addressId | GET, POST, PUT, DELETE |
| Reviews | /reviews/:productId, /reviews/:productId/summary, /reviews | GET, POST |
| Wishlist | /wishlist, /wishlist/items, /wishlist/items/:itemId | GET, POST, DELETE |
| Promotions | /promotions, /promotions/validate | GET, POST |
| Returns | /returns, /returns/:returnId, /returns/:returnId/cancel | GET, POST |
| Countries | /countries, /cities, /locations | GET |
OpenAPI Specification
The module automatically generates an OpenAPI 3.1 specification from route metadata. When enabled, two endpoints become available:
| Endpoint | Description |
|---|---|
/_openapi.json | Raw OpenAPI JSON specification |
/_scalar | Interactive API documentation (Scalar UI) |
All 46 routes include defineRouteMeta with:
- Tags — routes grouped into 13 domains (Store, Catalog, Geography, Auth, Cart, Checkout, Customer, Addresses, Orders, Reviews, Wishlist, Returns, Promotions)
- Descriptions — concise explanation of each endpoint's purpose
- Parameters — query and path parameters documented where applicable
To disable OpenAPI generation:
nuxt.config.ts
export default defineNuxtConfig({
commerce: {
openAPI: false,
},
})
The OpenAPI spec is generated at build time using Nitro's
experimental.openAPI feature. It adds zero overhead to your runtime bundle.Runtime Plugin
The module registers a Nuxt plugin that provides the adapter via $commerce. Access it from any component or composable:
const { $commerce } = useNuxtApp()
const product = await $commerce.getProduct('product-123')
On the server side, the adapter is injected into the event context via a Nitro server plugin:
server/api/custom-route.ts
export default defineEventHandler(async (event) => {
const adapter = event.context.commerce
return adapter.getProducts({ limit: 5 })
})
Type Safety
The module generates type augmentations for full TypeScript support:
// Auto-generated types
declare module '#app' {
interface NuxtApp {
$commerce: CommerceAdapter
}
}
declare module 'vue' {
interface ComponentCustomProperties {
$commerce: CommerceAdapter
}
}