shopware/frontends - composables
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
createShopwareContextmethod 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/composables @shopware/api-client @shopware/api-gen
# Using yarn
yarn add @shopware/composables @shopware/api-client @shopware/api-gen
# Using npm
npm i @shopware/composables @shopware/api-client @shopware/api-genNow generate your types ysing the CLI:
pnpm shopware-api-gen generate --apiType=storeInitialize 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:
import { createShopwareContext } from "@shopware/composables";
// 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);Exclude @shopware/composables package from pre-building process:
// vite.config.js or .ts
...
optimizeDeps: {
exclude: ["@shopware/composables"],
},
...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/composables/dist";
const { login } = useUser();
const { refreshSessionContext, sessionContext } = useSessionContext();
await 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-cookieLet's get back to the step where the api-client was initialized:
import { createAPIClient } from "@shopware/api-client";
import Cookies from "js-cookie";
import type { operations } from "#shopware";
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
👥 Community Discord (
#composable-frontend)
Changelog
Full changelog for stable version is available here
Latest changes: 1.15.0
Minor Changes
#2850
5374dfdThanks @mdanilowicz! - Deprecate API that has no effect, to be removed in the next major release:createShopwareContext: theenableDevtoolsoption and thestateproperty of the returned pluginuseProductAssociations: theassociationContextoption and themethodandsearchParamsparams ofloadAssociations. Bothoptionsand theloadAssociationsparams are now optional, so callloadAssociations()useProductConfigurator().isLoadingOptionsanduseSyncWishlist().isLoading, which are never updatedgetDefaultApiParams, which already logged a deprecation error, now carries the@deprecatedtag as well
Also removes commented-out code and the unused, unexported
registerShopwareDevtoolsanduseCmsElementProductBox, which drops the undeclared@vue/devtools-apiimport. No runtime behaviour changes.#2720
14fb094Thanks @mkucmus! - AddeduseCacheableRead().invokeRead. It uses the cacheable GET route only for a fresh default guest. That GET has nosw-context-token. Other sessions stay POST. Branching onuseShopwareContext().cacheableReadsis deprecated. Keep reads thatinvokeReaddoes not take on POST. NewcreateShopwareContextoption:ssrWithoutUserContext. A category read over GET now sends its listing params as plain query params, solimitis no longer dropped.#2668
2202e1cThanks @mateuszfl! - Support SEO URLs of headless (API type) sales channels. Since shopware/shopware#17991 headless sales channels persist their SEO URLs against thestore-api.*route family (store-api.product.detail,store-api.category.detail,store-api.landing-page.detail).useNavigationSearch().resolvePath()now maps those route names to theirfrontend.*equivalents, so page resolution works unchanged on a headless sales channel. The newgetFrontendRouteNamehelper in@shopware/helpersexposes the same mapping for custom resolvers.
Patch Changes
#2851
43a035fThanks @mdanilowicz! -useListing().filtersToQuery,useCmsMetaand the page counts ofuseListing,useWishlistanduseCustomerOrdersnow use the newgetListingFiltersQuery,getCmsMetaandgetTotalPageshelpers from@shopware/helpers. The only behaviour change: with a limit of0or less, the page count is now0instead ofInfinityorNaN.Deprecated, to be removed in the next major release:
useListing().filtersToQuery: usegetListingFiltersQueryfrom@shopware/helpersuseCmsMeta: usegetCmsMetafrom@shopware/helpers
#2791
4f0f33bThanks @mdanilowicz! - Point the README and JSDoc documentation links at the Frontends Recipes that replaced the redirected guides#2843
eba2d99Thanks @grenzenlos-digital! - SendcheckPromotionas a query parameter when loading order details, so Shopware 6.7.7+ calculatespaymentChangeable. When the order has nopaymentChangeableentry, retry once with the flag in the request body, so Shopware 6.6 and 6.7.0-6.7.6 keep working.#2849
037ffa9Thanks @mdanilowicz! -useWishlist().mergeWishlistProducts()now clears the local (localStorage) wishlist after merging it into the customer's wishlist. Before, it cleared the API wishlist instead: the local items stayed and were merged again on every login, and products the sync store still held from earlier in the session were removed from the customer's wishlist on the server.Updated dependencies [
fa598c8,2202e1c,43a035f,14fb094]:- @shopware/helpers@1.9.0
- @shopware/api-client@1.8.0