New major release changes

[patzick]

After extensive testing and feedback, we're in the final stage of the major release. This is the updated content of #471, and now we're in the polishing stage, which will be a major bump for most of the packages.

In the down below, we're heaving the set of features:

Overriding composables

Composables are one of the main features of the Composable Frontends. They are responsible for the logic of the application. We're introducing a new way of extending and overriding composables. With the new changes, you can:

• extending core composable replaces every usage of that composable in the application, including between other core composables. Example - extending useCart will replace useCart in useAddToCart composable. This gives maximum flexibility but also the responsibility - you can make things and break things, so be careful.
• composables are now supporting YOUR instance Entities. This means that you can use your own Product type in useProduct composable and across the whole application. This is a big step towards customisation and flexibility.

Steps for migration

1. remove direct imports from @shopware-pwa/composables-next → search for it in code and remove
   1. for type imports like Notification BoxLayout DisplayMode etc., update imports in the following pattern: example import type { BoxLayout, DisplayMode } from "@shopware-pwa/composables-next";
2. package.json - change package "@shopware-pwa/api-client" to new API client "@shopware/api-client". Remove the old package.
3. nuxt.config.ts in nuxt config shopwareEndpoint now needs to point exactly to the store API. Thanks to this whole URL could also be available behind a proxy. Example change: shopwareEndpoint: "https://demo-frontends.shopware.store/", → shopwareEndpoint: "https://demo-frontends.shopware.store/store-api/",
4. nuxt.config.ts - remove @shopware-pwa/cms-base from modules array
5. nuxt.config.ts - add nuxt layers of composables and cms - add line extends: ["@shopware-pwa/composables-next/nuxt-layer", "@shopware-pwa/cms-base"],

Adaptation of the new API Client

The new API Client package is in the updated shape. All usages of the old client has been replaced.

With the new package, you can:

• use types specific to your instance based on the OpenAPI specification
• have full type support and immediate feedback from your IDE when there's something wrong with API parameters
• composables also have your types, so you're developing with more confidence

Steps for migration

1. find all imports of @shopware-pwa/api-client in your code
2. change apiInstance to apiClient from useShopwareContext. Example: const { apiInstance } = useShopwareContext(); → const { apiClient } = useShopwareContext();
3. replace methods imported from @shopware-pwa/api-client. With the code auto-completion, it should be very straightforward:

so for example, fetching wishlist products from

const result = await getProducts(
  {
    ids: itemIds || items.value,
  },
  apiInstance,
);

becomes:

const result = await apiClient.invoke("readProduct post /product", {
  body: { ids: itemIds || items.value},
});

4. Remove the whole import from @shopware-pwa/api-client

Another examples

Newsletter confirmation:

import { newsletterConfirmation } from "@shopware-pwa/api-client";

const route = useRoute();
const { apiInstance } = useShopwareContext();
const error = ref(false);

try {
  await newsletterConfirmation(
    {
      em: route.query.em as string,
      hash: route.query.hash as string,
    },
    apiInstance,
  );
} catch (e) {
  error.value = true;
}

into:

const route = useRoute();
const { apiClient } = useShopwareContext();
const error = ref(false);

try {
  await apiClient.invoke("confirmNewsletter post /newsletter/confirm", {
    body: {
      em: route.query.em as string,
      hash: route.query.hash as string,
    }
  });
} catch (e) {
  error.value = true;
}

Handwritten requests via invokeGet example:

import { invokeGet } from "@shopware-pwa/api-client";
import type { CustomerGroup } from "@shopware-pwa/types";

const props = defineProps<{
  navigationId: string;
}>();

const { apiInstance } = useShopwareContext();

const { data: registrationResponse } = await useAsyncData(
  "cmsNavigation" + props.navigationId,
  async () => {
    const response = await invokeGet<CustomerGroup>(
      {
        address: `/store-api/customer-group-registration/config/${props.navigationId}`,
      },
      apiInstance,
    );
    return response?.data || {};
  },
);

into

const props = defineProps<{
  navigationId: string;
}>();

const { apiClient } = useShopwareContext();

const { data: registrationResponse } = await useAsyncData(
  "cmsNavigation" + props.navigationId,
  async () => {
    const {data} = await apiClient.invoke(
      "getCustomerGroupRegistrationInfo get /customer-group-registration/config/{customerGroupId}",
      {
        pathParams: {
          customerGroupId: props.navigationId,
        }
      },
    );
    return data || {};
  },
);

remember - we always have your back with type support

also with all the parameters required (and optional) in request

Error handling

With the new API client Error handling is also improved. You can log errors with descriptive messages and also see more informational Errors.

The old way of handling API client errors was similar to this:

} catch (err) {
	const error = err as ClientApiError;
  state.error = error.messages[0].detail;
}

the new way checks the instance of the error and helps you with the types

} catch (error) {
  if (error instanceof ApiClientError) {
    state.error = error.details.errors?.[0]?.detail;
  }
}

you can also console that error while developing so you’d get a clear error message. More info → https://www.npmjs.com/package/@shopware/api-client#error-handling

Overriding types

In order to have full control over your types we provided a possibility to override them. This is especially useful when you want to add some custom fields to the schema, change the type of the field, or there is some error in the OpenAPI schema, and you need to make a quick fix.

in the root of your project, add shopware.d.ts file:

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>>;
}

Read on how to write custom types in the documentation of showpare/api-gen package.

Server routes changes

In vue-demo store, we added a sitemap builder. This also requires adjustments for the new API client.

1. change apiBuilder.ts from

import { createInstance } from "@shopware-pwa/api-client";
const runtimeConfig = useRuntimeConfig();

const apiContext = createInstance({
  endpoint: runtimeConfig.public.shopware.shopwareEndpoint,
  accessToken: runtimeConfig.public.shopware.shopwareAccessToken,
});

export default apiContext;

into

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

const runtimeConfig = useRuntimeConfig();

const apiClient = createAPIClient<operations>({
  accessToken: runtimeConfig.public.shopware.shopwareAccessToken,
  baseURL: runtimeConfig.public.shopware.shopwareEndpoint,
});

export default apiClient;

1. and then you’re changing server routes like any other endpoint change, for example

const response = await getSitemap(apiContext);

into

const response = await apiClient.invoke("readSitemap get /sitemap");

Remove dependency from @shopware-pwa/types

Types are becoming yours to have. For specific versions, overrides. Current types are changed under the hood and deprecated. It should all still work for your project, but these are the recommended steps of migration:

1. track all imports of @shopware-pwa/types
2. change imported types to use import type { Schemas } from "#shopware"; and then replace used entity. Example transitions:

import type { Product } from "@shopware-pwa/types";
const products = ref<Product[]>([]);
// into
import type { Schemas } from "#shopware";
const products = ref<Schemas["Product"][]>([]);

you have full auto-completion for all the schema types from your API instance:

Pure Vite application

This step is for someone who uses pure Vite application, without Nuxt modules, etc.

1. Change dependency in package.json from @shopware-pwa/api-client to @shopware/api-client
2. create apiClient.ts file with your API client definition, for example

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://"),
  });
});

3. provide ApiClient in the main.ts file

app.provide("apiClient", apiClient);

4. add the imports.d.ts file with content

export * from "@shopware-pwa/composables-next";

7. add shopware.d.ts file with content from ## Overriding types

8. edit the vite config file, add resolve.alias config:

"#imports": fileURLToPath(new URL("./imports.d.ts", import.meta.url)),

9. in tsconfig.json file add compilerOptions.paths:

"paths": {
    "#imports": ["./imports.d.ts"],
    "#shopware": ["./shopware.d.ts"]
  }

Troubleshooting

apiClient has any type

when facing this problem, your IDE probably didn’t refresh the types properly. You can help a bit by restarting TypeScript and Vue Server. Just hit cmd+shift+p in VS code and pick the Restart TS Server option.

apiClient is not completing my types

do the same as apiClient has any type
if that didn’t help - add shopware.d.ts file and restart ts server again

no type support and code completion

If previous steps didn't work - in tsconfig.json, check that moduleResolution is set to node (before it was bundler). This can cause a problem with the exported Types (see) for the new API Client. We'll investigate this topic more in the future

What's next?

Track the release progress in the milestone as it will be updated in upcoming days with the polishing PRs.