@shopware-pwa/composables-next

shopware/frontends - composables-next

Set of Vue.js composition functions that can be used in any Vue.js project. They provide state management, UI logic and data fetching and are the base for all guides in our building section.

Features

• createShopwareContext method to create a Vue 3 plugin to install
• State management
• Logic for UI
• Communication with Store-API via api-client package

Setup

Install npm packages (composables & api-client):

# Using pnpm
pnpm add @shopware-pwa/composables-next @shopware/api-client @shopware/api-gen

# Using yarn
yarn add @shopware-pwa/composables-next @shopware/api-client @shopware/api-gen

# Using npm
npm i @shopware-pwa/composables-next @shopware/api-client @shopware/api-gen

Now generate your types ysing the CLI:

pnpm shopware-api-gen generate --apiType=store

Initialize the api-client instance:

import { createAPIClient } from "@shopware/api-client";
import type { operations } from "#shopware";

export const apiClient = createAPIClient<operations>({
  baseURL: "https://your-api-instance.com",
  accessToken: "your-sales-channel-access-token",
});

// and then provide it in the Vue app
app.provide("apiClient", apiClient);

Now, we can create a Vue 3 plugin to install a Shopware context in an app:

// app variable in type of App

const shopwareContext = createShopwareContext(app, {
  devStorefrontUrl: "https://your-sales-channel-configured-domain.com",
});
// register a plugin in a Vue instance
app.use(shopwareContext);

The example does not provide the session handling and that means you need to do few additional steps if you need to keep your session after the page reload (see the chapter below with 🍪)

Basic usage

Now you can use any composable function in your setup function:

<script setup>
    import { useUser, useSessionContext } from "@shopware-pwa/composables-next/dist";

    const { login } = useUser();
    const { refreshSessionContext, sessionContext } = useSessionContext();
    refreshSessionContext();
</script>
<template>
    <pre>{{ sessionContext }}</pre>
    <button @click="login({
        username: "some-user",
        password: "secret-passwd"
    })">
        Try to login!
    </button>
</template>

Session persistence with 🍪

By default, the API-Client is stateless, but accepts an optional context token as a parameter while initializing an instance. In order to keep a session, install some cookie parser to work with cookies easier:

# Using pnpm
pnpm add js-cookie

# Using yarn
yarn add js-cookie

# Using npm
npm i js-cookie

Let's get back to the step where the api-client was initialized:

import { createAPIClient } from "@shopware/api-client";
import type { operations } from "#shopware";
import Cookies from "js-cookie";

const shopwareEndpoint = "https://demo-frontends.shopware.store/store-api";

export const apiClient = createAPIClient<operations>({
  baseURL: shopwareEndpoint,
  accessToken: "SWSCBHFSNTVMAWNZDNFKSHLAYW",
  contextToken: Cookies.get("sw-context-token"),
});

apiClient.hook("onContextChanged", (newContextToken) => {
  Cookies.set("sw-context-token", newContextToken, {
    expires: 365, // days
    path: "/",
    sameSite: "lax",
    secure: shopwareEndpoint.startsWith("https://"),
  });
});

Thanks to this, the session will be kept to the corresponding sw-context-token saved in the cookie, so it can be reachable also in the SSR. Check the example to see it in action:

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.

Links

• 📘 Documentation

• 👥 Community Slack (#shopware-frontends & #shopware-pwa channel)

Changelog

Full changelog for stable version is available here

Latest changes: 0.0.0-canary-20240625122123

Major Changes

• #871 1566f7a Thanks @patzick! - Read more about new major release: https://github.com/shopware/frontends/discussions/965

• #1056 c729e70 Thanks @patzick! - Removed deprecations from the composables:

  • createShopwareContext is no longer accpting apiInstance option. Use apiClient instead.
  • useCart - getProductItemsSeoUrlsData is removed. Use product related methods to fetch an item's URL instead.
  • useCartItem - getProductItemSeoUrlData is removed
  • apiInstance is not exposing apiInstance anymore. Use apiClient instead.

• #452 e2c225f Thanks @patzick! - Created Nuxt layer for composables and cms-base. This way overriding any part of that is now possible.

• #978 479357c Thanks @patzick! - useCustomerPassword and loadCustomerAddresses inside useAddress are now throwing api errors on invocation. The errors object has been removed from the composable to make consistent error handling across the composables. This change is breaking and requires you to update your implementation of the composables.

  Example of error handling for resseting password:

  const {
    resetPassword,
    // errors --> removed from the API
  } = useCustomerPassword();
  
  const errors = ref([]);
  
  const invokeRecover = async (): Promise<void> => {
    try {
      errors.value = [];
      const emailSent = await resetPassword(formData.value);
  
      if (emailSent.success) {
        // here we know that email was sent
      }
    } catch (error) {
      console.error("[AccountRecoverPassword]", error);
      if (error instanceof ApiClientError) {
        errors.value = error.details?.errors || [];
      }
    }
  };
  

Minor Changes

• #991 38a3853 Thanks @patzick! - Few changes in composables API to access data returned from the backend:

  • useAddress - loadCustomerAddresses returns addresses now
  • useCart - removeItem returns updated cart
  • useCartItem - removeItem returns updated cart, similar to useCart
  • fetchCountries - returns countries with the response
  • useNewsletter - getNewsletterStatus returns full response from the API
  • useOrderDetails - loadOrderDetails returns order details now, cancel returns order state, changePaymentMethod returns success response info
  • changePaymentMethod - changePaymentMethod returns success response info now
  • useProductReviews - loadProductReviews returns reviews response now
  • useSalutations - fetchSalutations returns salutations response now
  • useUser - refreshUser returns customer data. logout, loadCountry and loadSalutation returns data from the API

• #840 823aa9b Thanks @mdanilowicz! - Return componentNameToResolve in resolveCmsComponent function

• #529 4dce006 Thanks @mdanilowicz! - BREAKING: Use product ID instead of whole product object in useProductWishlist composable

• #535 bebae42 Thanks @mdanilowicz! - Fix country ID in session context Add salesChannelCountryId that represent sales channel default city ID

• #986 013a1d6 Thanks @mdanilowicz! - Added tests to achieve coverage > 80%

• #933 04ac2ad Thanks @mdanilowicz! - - Added checkPromotion attribute to the orderAssociations

  • Added statusTechnicalName property to the useOrderDetails composable
  • Added getPaymentMethods method that allows change payment for existed order
  • Added stateMachineState association for loading orders

• #1027 05ca5b6 Thanks @mdanilowicz! - Added useCategorySearch and useCmsElementProductBox tests

• #703 7a3a92c Thanks @mdanilowicz! - Add B2b quote management composable

Patch Changes

• #569 f1b2a30 Thanks @itscark! - Fix only available shipping methods

• #880 2ade07a Thanks @mdanilowicz! - Adjust types in useProductSearch composable

• #915 fc262dd Thanks @mdanilowicz! - Handle using categoryId as a alternative for category context

• #1042 53e7177 Thanks @patzick! - Completely removed dependency to the deprecated @shopware-pwa/types package

• #873 99ad5e9 Thanks @mkucmus! - Add isStackable and isDigital computed properties

• #705 8f0b468 Thanks @mdanilowicz! - Add missing addressId to the updateCustomerAddress method

• #524 6b54268 Thanks @BrocksiNet! - Added new composables (previously internal helpers of the cms-base package): useCmsTranslations, useUrlResolver, useUrlResolver

• Updated dependencies [2343012, 1566f7a, 782ef4d, 9643e56, 1583a7a, 97d2859, 864616f, d60d062, a92941e, 487d991, c729e70, 89a97a4, c729e70, 864616f, 97b5949, 6664aa2, 6b54268]:

  • @shopware/api-client@0.0.0-canary-20240625122123
  • @shopware-pwa/helpers-next@0.0.0-canary-20240625122123