shopware/frontends - nuxt-module

Nuxt module that allows you to set up a Nuxt project with Shopware Frontends. It provides the composables and api-client packages.

If you want to use these packages with a different Vue.js framework, see the guide for using Shopware Frontends in a custom project.

Features

• Business logic covered by Composables package. Registering all composable functions globally. See the reference.
• Shopware context shared in Nuxt application.
• Configured API Client package.

Setup

Install npm package:

# Using pnpm
pnpm add -D @shopware/nuxt-module

# Using yarn
yarn add --dev @shopware/nuxt-module

# Using npm
npm i @shopware/nuxt-module --save-dev

Then, register the module by editing nuxt.config.js or (.ts) file (by extending modules array):

/* nuxt.config.ts */

export default defineNuxtConfig({
  /* ... */
  modules: [, /* ... */ "@shopware/nuxt-module"],
  // set the module config
  shopware: {
    // connect to your Shopware 6 API instance
    endpoint: "https://demo-frontends.shopware.store/store-api/",
    accessToken: "SWSCBHFSNTVMAWNZDNFKSHLAYW",
  },
  // or directly in the runtime config
  // this config will override the base one
  runtimeConfig: {
    public: {
      shopware: {
        endpoint: "https://demo-frontends.shopware.store/store-api/",
        accessToken: "SWSCBHFSNTVMAWNZDNFKSHLAYW",
      },
    },
  },
});

Set up your own API instance under shopware key or by extending public runtimeConfiguration in the same file. The nuxt module (and vue plugin) will use those values (runtimeConfig will always override the base ones).

Basic usage

Now you can use any composable function you need without extra import:

<script setup>
  const { login } = useUser();
  const { refreshSessionContext } = useSessionContext();
  await refreshSessionContext();
</script>

The information about the session is kept in a cookie (sw-context-token) and used in every request made by any composable or directly, invoked by api instance:

<script setup>
  const { apiClient } = useShopwareContext();
  const apiResponse = await apiClient.invoke(/** params omitted */);
</script>

TypeScript support

All composable functions are fully typed with TypeScript and they are registed globally in Nuxt.js application, so the type hinting will help you to work with all of them.

📦 Advanced packaging

Internally, the module uses API Client and Composables packages, configured together to make everything working well. If you need to check how it's working on a different version of one of them, install a package locally in your project (to be installed and available in project's package.json file), then the Nuxt module will use yours. Keep in mind that the different configuration may lead to unexpected behavior.

API Default Headers

You can use Nuxt config to set the default API call headers. More about Nuxt configuration can be found HERE.

NOTE: By default, the values in runtimeConfig are only available on the server-side. However, keys within runtimeConfig.public are also accessible on the client-side. MORE

{
  "runtimeConfig": {
    "public": {
      "apiClientConfig": {
        "headers": {
          "global-heder-example": "global-header-example-value"
        }
      }
    },
    "apiClientConfig": {
      "headers": {
        "ssr-heder-example": "ssr-header-example-value"
      }
    }
  }
}

API Client timeout

apiClientConfig.timeout aborts a Store API request when its response headers do not arrive within the given number of milliseconds. Unset by default.

It guards against a request that hangs before the server answers. The timer starts before the connection is opened, so a DNS lookup, TCP connect or TLS handshake that hangs is aborted too. A response that stalls after its headers arrived is not aborted, because the timer is cleared once the headers land. A call that passes its own signal is the exception: the combined timer keeps running, so a stalled body is aborted too.

{
  "runtimeConfig": {
    "public": {
      "apiClientConfig": {
        "timeout": 10000
      }
    }
  }
}

Only a positive number of milliseconds arms it, and a numeric string is coerced, so "5000" works. Leaving it out is silent. Setting it to anything else is ignored and logged once as a warning naming the config path the value came from.

shopware: { apiClientConfig: { timeout } } still works as a deprecated fallback, read only when neither runtimeConfig path holds a valid value. Nuxt warns at build time when a timeout is set there. Move it to runtimeConfig.apiClientConfig; it goes away in the next major.

Once set:

• The error carries no HTTP status and is not an ApiClientError. Detect it with isTimeoutError() from @shopware/api-client.
• A timed-out GET uses up its one automatic retry without reaching the server again.
• Your own signal on a single call is combined with the timeout, so whichever fires first aborts the request.
• NUXT_API_CLIENT_CONFIG_TIMEOUT and NUXT_PUBLIC_API_CLIENT_CONFIG_TIMEOUT only apply if the key is already in nuxt.config.

Register custom API types (tailored for your Shopware instance)

To use custom API types generated by the api-gen package, create a shopware.d.ts file in your project and register the types for the #shopware module. This enables type-safe usage of your custom API types throughout your Nuxt application.

Example of using a local type definitions:

// shopware.d.ts
declare module "#shopware" {
  import type { createAPIClient } from "@shopware/api-client";

  // Use default Shopware types:
  // export type operations =
  //  import("@shopware/api-client/store-api-types").operations;
  // export type Schemas =
  // import("@shopware/api-client/store-api-types").components["schemas"];

  // Or use your locally generated types (placed in ./api-types folder):
  export type operations = import("./api-types/storeApiTypes").operations;
  export type Schemas =
    import("./api-types/storeApiTypes").components["schemas"];

  // Export your own Api Client definition:
  export type ApiClient = ReturnType<typeof createAPIClient<operations>>;
}

Import your custom types from local files and export them as shown above. This approach keeps your types local, allows merging or overriding defaults, and ensures full type safety for API operations and schemas.

Apply custom types for @shopware/api-client

The API Client instance is aware of your custom API types thanks to declaring #shopware module from the step above. So now, whenever apiClient instance is used, the proper types are registered.

Links

• 📘 Documentation

• 📦 API Gen - Types Generator for Shopware 6 OpenAPI Schema

• 📦 API Client - REST API Client for Shopware 6

• 👥 Community (#composable-frontend)

Changelog

Full changelog for stable version is available here

Latest changes: 1.5.2

Patch Changes

• #2598 204c8f4 Thanks @dependabot! - Fix Nuxt plugin injection typing for Nuxt 4.5 and maintenance mode error handling.

• Updated dependencies [2ddf156, 204c8f4, 7020545, 183c183, 458494e, 183c183, 183c183, 8913956, 458494e]:

  • @shopware/helpers@1.8.0
  • @shopware/composables@1.13.0
  • @shopware/api-client@1.6.0