@shopware/nuxt-module 0.0.0-canary-20250116171244

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022-2023 Shopware
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,142 @@
+# shopware/frontends - nuxt-module
+
+[![](https://img.shields.io/npm/v/@shopware/nuxt-module?color=blue&logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTIiIGhlaWdodD0iMTIiIHZpZXdCb3g9IjAgMCA0ODggNTUzIiBmaWxsPSJub25lIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPgo8cGF0aCBkPSJNNDM5LjA0MSAxMjkuNTkzTDI1OC43NjkgMzEuMzA3NkMyNDQuOTE1IDIzLjc1NDEgMjI4LjExNiAyNC4wMDkzIDIxNC40OTcgMzEuOTgwMkw0Ny4yNjkgMTI5Ljg1OEMzMy40NzYzIDEzNy45MzEgMjUgMTUyLjcxMyAyNSAxNjguNjk1VjM4OC40NjZDMjUgNDA0LjczMiAzMy43Nzg1IDQxOS43MzIgNDcuOTYwMiA0MjcuNjk5TDIxNS4xNzggNTIxLjYzNkMyMjguNDUxIDUyOS4wOTIgMjQ0LjU5MyA1MjkuMzMyIDI1OC4wODIgNTIyLjI3NEw0MzguMzY0IDQyNy45MzRDNDUzLjIwMSA0MjAuMTcgNDYyLjUgNDA0LjgwOSA0NjIuNSAzODguMDYzVjE2OS4xMDJDNDYyLjUgMTUyLjYzMiA0NTMuNTAyIDEzNy40NzcgNDM5LjA0MSAxMjkuNTkzWiIgc3Ryb2tlPSJ1cmwoI3BhaW50MF9saW5lYXJfMTUzXzY5MjY1KSIgc3Ryb2tlLXdpZHRoPSI1MCIgc3Ryb2tlLWxpbmVqb2luPSJyb3VuZCIvPgo8ZGVmcz4KPGxpbmVhckdyYWRpZW50IGlkPSJwYWludDBfbGluZWFyXzE1M182OTI2NSIgeDE9Ii0xNi4yOTg5IiB5MT0iMTY1LjM0OSIgeDI9IjI3Ni40MTIiIHkyPSItODkuMzIzNCIgZ3JhZGllbnRVbml0cz0idXNlclNwYWNlT25Vc2UiPgo8c3RvcCBzdG9wLWNvbG9yPSIjMDA4NUZGIi8+CjxzdG9wIG9mZnNldD0iMSIgc3RvcC1jb2xvcj0iI0MwRTJGNSIvPgo8L2xpbmVhckdyYWRpZW50Pgo8L2RlZnM+Cjwvc3ZnPg==)](https://npmjs.com/package/@shopware/nuxt-module)
+[![](https://img.shields.io/github/package-json/v/shopware/frontends?color=blue&filename=packages%2Fnuxt-module%2Fpackage.json&label=nuxt-module%40monorepo&logo=github)](https://github.com/shopware/frontends/tree/main/packages/nuxt-module)
+[![](https://img.shields.io/github/issues/shopware/frontends/nuxt-module?label=nuxt-module%20issues&logo=github)](https://github.com/shopware/frontends/issues?q=is%3Aopen+is%3Aissue+label%3Anuxt-module)
+[![](https://img.shields.io/github/license/shopware/frontends?color=blue)](#)
+
+Nuxt [module](https://nuxt.com/docs/guide/going-further/modules) that allows you to set up a Nuxt 3 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](https://frontends.shopware.com/getting-started/templates/custom-vue-project.html) for using Shopware Frontends in a custom project.
+
+## Features
+
+- Business logic covered by [Composables](https://npmjs.com/package/@shopware/composables) package. Registering all composable functions globally. [See the reference](https://frontends.shopware.com/packages/composables.html).
+- Shopware context shared in Nuxt application.
+- Configured [API Client](https://npmjs.com/package/@shopware/api-client) package.
+
+## Setup
+
+Install npm package:
+
+```bash
+# 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):
+
+```js
+/* 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",
+    accessToken: "SWSCBHFSNTVMAWNZDNFKSHLAYW",
+  },
+  // or directly in the runtime config
+  // this config will override the base one
+  runtimeConfig: {
+    public: {
+      shopware: {
+        endpoint: "https://demo-frontends.shopware.store",
+        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:
+
+```html
+<script setup>
+  const { login } = useUser();
+  const { refreshSessionContext } = useSessionContext();
+  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`:
+
+```html
+<script>
+  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](https://npmjs.com/package/@shopware/api-client) and [Composables](https://npmjs.com/package/@shopware/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](https://nuxt.com/docs/getting-started/configuration).
+
+> **_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](https://nuxt.com/docs/getting-started/configuration#environment-variables-and-private-tokens)
+
+```json
+{
+  "runtimeConfig": {
+    "public": {
+      "apiClientConfig": {
+        "headers": {
+          "global-heder-example": "global-header-example-value"
+        }
+      }
+    },
+    "apiClientConfig": {
+      "headers": {
+        "ssr-heder-example": "ssr-header-example-value"
+      }
+    }
+  }
+}
+```
+
+## Links
+
+- [📘 Documentation](https://frontends.shopware.com)
+
+- [👥 Community](https://shopwarecommunity.slack.com) (`#composable-frontends`)
+<!-- AUTO GENERATED CHANGELOG -->
+
+## Changelog
+
+Full changelog for stable version is available [here](https://github.com/shopware/frontends/blob/main/packages/nuxt-module/CHANGELOG.md)
+
+### Latest changes: 0.0.0-canary-20250116171244
+
+### Minor Changes
+
+- [#1602](https://github.com/shopware/frontends/pull/1602) [`bb7d1cb`](https://github.com/shopware/frontends/commit/bb7d1cbc4204ff1d48f77416f94f550bc235e5ed) Thanks [@patzick](https://github.com/patzick)! - Package `@shopware-pwa/nuxt3-module` is deprecated. Use [@shopware/nuxt-module](https://www.npmjs.com/package/@shopware/nuxt-module) instead.
+
+- [#1602](https://github.com/shopware/frontends/pull/1602) [`bb7d1cb`](https://github.com/shopware/frontends/commit/bb7d1cbc4204ff1d48f77416f94f550bc235e5ed) Thanks [@patzick](https://github.com/patzick)! - Switch from `@shopware-pwa/helpers-next` to `@shopware/helpers` package.
+
+- [#1602](https://github.com/shopware/frontends/pull/1602) [`bb7d1cb`](https://github.com/shopware/frontends/commit/bb7d1cbc4204ff1d48f77416f94f550bc235e5ed) Thanks [@patzick](https://github.com/patzick)! - Switch from `@shopware-pwa/cms-base` to `@shopware/cms-base-layer` package.
+
+### Patch Changes
+
+- Updated dependencies [[`bb7d1cb`](https://github.com/shopware/frontends/commit/bb7d1cbc4204ff1d48f77416f94f550bc235e5ed), [`bb7d1cb`](https://github.com/shopware/frontends/commit/bb7d1cbc4204ff1d48f77416f94f550bc235e5ed)]:
+  - @shopware/composables@0.0.0-canary-20250116171244
+  - @shopware/helpers@0.0.0-canary-20250116171244

package/dist/index.d.mts

@@ -0,0 +1,49 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+declare const _default: _nuxt_schema.NuxtModule<ShopwareNuxtOptions, ShopwareNuxtOptions, false>;
+
+type ShopwareNuxtOptions = {
+    /**
+     * Endpoint for your shopware backend.
+     *
+     * Default demo store: "https://demo-frontends.swstage.store/"
+     */
+    endpoint?: string;
+    shopwareEndpoint?: string;
+    accessToken?: string;
+    shopwareAccessToken?: string;
+    devStorefrontUrl?: string;
+    apiClientConfig?: {
+        timeout?: number | string;
+    };
+    /**
+     * Use user context in SSR mode. Warning: with wrong edge caching it can cause serving another user's data.
+     * Use when edge caching is configured properly.
+     *
+     * @default false
+     */
+    useUserContextInSSR?: boolean;
+};
+declare module "@nuxt/schema" {
+    interface NuxtConfig {
+        shopware?: ShopwareNuxtOptions;
+    }
+    interface NuxtOptions {
+        shopware?: ShopwareNuxtOptions;
+    }
+    interface ApiClientConfig {
+        headers?: {
+            [key: string]: string;
+        };
+    }
+    interface RuntimeConfig {
+        shopware?: Pick<ShopwareNuxtOptions, "endpoint" | "shopwareEndpoint" | "useUserContextInSSR">;
+        apiClientConfig?: ApiClientConfig;
+    }
+    interface PublicRuntimeConfig {
+        shopware: ShopwareNuxtOptions;
+        apiClientConfig?: ApiClientConfig;
+    }
+}
+
+export { type ShopwareNuxtOptions, _default as default };

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+declare const _default: _nuxt_schema.NuxtModule<ShopwareNuxtOptions, ShopwareNuxtOptions, false>;
+
+type ShopwareNuxtOptions = {
+    /**
+     * Endpoint for your shopware backend.
+     *
+     * Default demo store: "https://demo-frontends.swstage.store/"
+     */
+    endpoint?: string;
+    shopwareEndpoint?: string;
+    accessToken?: string;
+    shopwareAccessToken?: string;
+    devStorefrontUrl?: string;
+    apiClientConfig?: {
+        timeout?: number | string;
+    };
+    /**
+     * Use user context in SSR mode. Warning: with wrong edge caching it can cause serving another user's data.
+     * Use when edge caching is configured properly.
+     *
+     * @default false
+     */
+    useUserContextInSSR?: boolean;
+};
+declare module "@nuxt/schema" {
+    interface NuxtConfig {
+        shopware?: ShopwareNuxtOptions;
+    }
+    interface NuxtOptions {
+        shopware?: ShopwareNuxtOptions;
+    }
+    interface ApiClientConfig {
+        headers?: {
+            [key: string]: string;
+        };
+    }
+    interface RuntimeConfig {
+        shopware?: Pick<ShopwareNuxtOptions, "endpoint" | "shopwareEndpoint" | "useUserContextInSSR">;
+        apiClientConfig?: ApiClientConfig;
+    }
+    interface PublicRuntimeConfig {
+        shopware: ShopwareNuxtOptions;
+        apiClientConfig?: ApiClientConfig;
+    }
+}
+
+export { type ShopwareNuxtOptions, _default as default };

package/dist/index.mjs

@@ -0,0 +1,56 @@
+import { addCustomTab } from '@nuxt/devtools-kit';
+import { defineNuxtModule, useLogger, createResolver, addPlugin } from '@nuxt/kit';
+import { defu } from 'defu';
+import 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const distDir = dirname(fileURLToPath(import.meta.url));
+const pkgDir = resolve(distDir, "..");
+resolve(pkgDir, "./node_modules");
+function isConfigDeprecated(config) {
+  return Boolean(config?.shopwareEndpoint || config?.shopwareAccessToken);
+}
+
+const MODULE_ID = "@shopware/nuxt3";
+const index = defineNuxtModule({
+  meta: {
+    name: MODULE_ID,
+    configKey: "shopware"
+  },
+  async setup(options, nuxt) {
+    const logger = useLogger(MODULE_ID);
+    const resolver = createResolver(import.meta.url);
+    nuxt.options.runtimeConfig.public.shopware = defu(
+      nuxt.options.runtimeConfig.public.shopware || {},
+      options || {}
+    );
+    if (isConfigDeprecated(nuxt.options?.runtimeConfig?.public?.shopware)) {
+      logger.warn(
+        "You are using deprecated configuration (shopwareEndpoint or shopwareAccessToken). 'shopware' prefix is not needed anymore. Please update your _nuxt.config.ts_ "
+      );
+    }
+    if (nuxt.options?.runtimeConfig?.shopware?.endpoint) {
+      logger.info(
+        `You are using SSR Shopware API endpoint: ${nuxt.options.runtimeConfig.shopware.endpoint}`
+      );
+    }
+    logger.info(
+      `CSR Shopware API endpoint: ${nuxt.options.runtimeConfig.public?.shopware?.endpoint ?? nuxt.options.runtimeConfig.public?.shopware?.shopwareEndpoint}`
+    );
+    addPlugin({
+      src: resolver.resolve("../plugin.ts")
+    });
+    addCustomTab({
+      name: "shopware-frontends",
+      title: "Shopware Frontends",
+      icon: "fa6-brands:shopware",
+      view: {
+        type: "iframe",
+        src: "https://frontends.shopware.com/"
+      }
+    });
+  }
+});
+
+export { index as default };

package/index.cjs

@@ -0,0 +1,6 @@
+// CommonJS proxy to bypass jiti transforms from nuxt 2 and using native ESM
+module.exports = function (...args) {
+  return import("./dist/index.mjs").then((m) => m.default.call(this, ...args));
+};
+
+module.exports.meta = require("./package.json");

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@shopware/nuxt-module",
+  "version": "0.0.0-canary-20250116171244",
+  "description": "Nuxt 3 module for Shopware Frontends",
+  "author": "Shopware",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shopware/frontends.git"
+  },
+  "homepage": "https://frontends.shopware.com/framework/internal-structure.html#nuxt-module",
+  "keywords": [
+    "Nuxt",
+    "Shopware",
+    "Vue"
+  ],
+  "bugs": {
+    "url": "https://github.com/shopware/frontends/issues"
+  },
+  "license": "MIT",
+  "main": "./index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "plugin.ts",
+    "shopware.d.ts",
+    "index.cjs"
+  ],
+  "dependencies": {
+    "@nuxt/kit": "3.14.1592",
+    "defu": "6.1.4",
+    "js-cookie": "3.0.5",
+    "@shopware/composables": "0.0.0-canary-20250116171244",
+    "@shopware/helpers": "0.0.0-canary-20250116171244",
+    "@shopware/api-client": "1.2.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "1.8.3",
+    "@nuxt/schema": "3.14.1592",
+    "nuxt": "3.14.1592",
+    "typescript": "5.6.3",
+    "unbuild": "2.0.0",
+    "tsconfig": "0.0.0"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "dev": "unbuild --stub",
+    "lint": "biome check .",
+    "lint:fix": "biome check . --write && pnpm run typecheck",
+    "typecheck": "tsc --noEmit",
+    "test": "echo \"Warn: no test specified yet\""
+  }
+}

package/plugin.ts

@@ -0,0 +1,111 @@
+import { createAPIClient } from "@shopware/api-client";
+import { isMaintenanceMode } from "@shopware/helpers";
+import { defu } from "defu";
+import { getCookie } from "h3";
+import Cookies from "js-cookie";
+import { ref } from "vue";
+import {
+  createShopwareContext,
+  defineNuxtPlugin,
+  showError,
+  useRuntimeConfig,
+  useState,
+} from "#imports";
+import type { ApiClient } from "#shopware";
+
+declare module "#app" {
+  interface NuxtApp {
+    $shopwareApiClient: ApiClient;
+  }
+}
+
+declare module "vue" {
+  interface ComponentCustomProperties {
+    $shopwareApiClient: ApiClient;
+  }
+}
+
+export default defineNuxtPlugin((NuxtApp) => {
+  const runtimeConfig = useRuntimeConfig();
+  const shopwareEndpointCSR =
+    runtimeConfig.public?.shopware?.endpoint ??
+    runtimeConfig.public?.shopware?.shopwareEndpoint;
+
+  const shopwareEndpointSSR =
+    runtimeConfig.shopware?.endpoint ?? shopwareEndpointCSR;
+
+  const shopwareEndpoint = import.meta.server
+    ? shopwareEndpointSSR
+    : shopwareEndpointCSR;
+
+  const shopwareAccessToken =
+    runtimeConfig.public?.shopware?.accessToken ??
+    runtimeConfig.public?.shopware?.shopwareAccessToken;
+
+  if (!shopwareEndpoint || !shopwareAccessToken) {
+    throw new Error(
+      "Make sure that endpoint and accessToken are settled in the configuration",
+    );
+  }
+
+  const shouldUseSessionContextInServerRender =
+    !NuxtApp.ssrContext ||
+    !!runtimeConfig.public?.shopware?.useUserContextInSSR ||
+    !!runtimeConfig?.shopware?.useUserContextInSSR;
+
+  const contextTokenFromCookie = NuxtApp.ssrContext
+    ? getCookie(NuxtApp.ssrContext?.event, "sw-context-token")
+    : Cookies.get("sw-context-token");
+
+  const apiClient = createAPIClient({
+    baseURL: shopwareEndpoint,
+    accessToken: shopwareAccessToken,
+    contextToken: shouldUseSessionContextInServerRender
+      ? contextTokenFromCookie
+      : "",
+    defaultHeaders: defu(
+      runtimeConfig.apiClientConfig?.headers,
+      runtimeConfig.public?.apiClientConfig?.headers,
+    ),
+  });
+
+  apiClient.hook("onContextChanged", (newContextToken) => {
+    Cookies.set("sw-context-token", newContextToken, {
+      expires: 365, // days
+      path: "/",
+      sameSite: "lax",
+      secure: shopwareEndpoint.startsWith("https://"),
+    });
+  });
+
+  apiClient.hook("onResponseError", (response) => {
+    // @ts-expect-error TODO: check maintenance mode and fix typongs here
+    const error = isMaintenanceMode(response._data?.errors ?? []);
+    if (error) {
+      throw showError({
+        statusCode: 503,
+        statusMessage: "MAINTENANCE_MODE",
+      });
+    }
+  });
+
+  NuxtApp.vueApp.provide("apiClient", apiClient);
+  // Shopware context
+  const shopwareContext = createShopwareContext(NuxtApp.vueApp, {
+    enableDevtools: true,
+    devStorefrontUrl: runtimeConfig.public.shopware?.devStorefrontUrl || null,
+  });
+  NuxtApp.vueApp.provide("shopware", shopwareContext);
+
+  // Session Context
+  const sessionContextData = ref();
+  NuxtApp.vueApp.provide("swSessionContext", sessionContextData);
+  // in case someone tries to use it in nuxt specific code like middleware
+  useState("swSessionContext", () => sessionContextData);
+
+  return {
+    provide: {
+      shopwareApiClient: apiClient as ApiClient,
+    },
+  };
+});

package/shopware.d.ts

@@ -0,0 +1,19 @@
+declare module "#shopware" {
+  import type { createAPIClient } from "@shopware/api-client";
+
+  // for default types
+  export type operations =
+    import("@shopware/api-client/store-api-types").operations;
+  // or for locally generated types
+  // export type operations = import("./api-types/storeApiTypes").operations;
+
+  // for default types
+  export type Schemas =
+    import("@shopware/api-client/store-api-types").components["schemas"];
+  // or for locally generated types
+  // export type Schemas =
+  //   import("./api-types/storeApiTypes").components["schemas"];
+
+  // we're exporting our own Api Client definition as it depends on our own instance
+  export type ApiClient = ReturnType<typeof createAPIClient<operations>>;
+}