2023-December - New changes approaching for overriding composables, full types control and new API Client integration

[patzick]

We're delighted to introduce you to some features coming to Composable Frontends in the next release.

IMPORTANT: Currently, this announcement is for canary releases only. After your feedback and broader testing, we'll release it as the latest stable version. Please provide your feedback and questions!

Key takeaways:

• composables can be extended and overwritten
• A new API Client is replacing the old one, which gives us a type of support for your specific Shopware instance
• both composables and cms-base packages are now Nuxt layers, improving overriding possibilities and giving us a better developer experience.
• better type support - suited for your instance, with the ability to override as well

Read more about specific points and migration steps you'll need to take to upgrade your project. We tried to make it as easy as possible, but it still requires some work. We hope you'll like the new features and the new API Client.

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 previous release introduced our new API Client package. At this point, we're integrating this package into our packages, and we're removing the old one.

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 autocompletion, 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", {
  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", {
    em: route.query.em as string,
    hash: route.query.hash as string,
  });
} catch (e) {
  error.value = true;
}

Hand written 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 response = await apiClient.invoke(
      "getCustomerGroupRegistrationInfo get /customer-group-registration/config/{customerGroupId}",
      {
        customerGroupId: props.navigationId,
      },
    );
    return response || {};
  },
);

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";
  import type {
    operationPaths as defaultOperationPaths,
    operations as defaultOperations,
    components as defaultComponents,
  } from "@shopware/api-client/api-types";
  import type {
    RequestParameters as DefaultRequestParameters,
    RequestReturnType as DefaultRequestReturnType,
  } from "@shopware/api-client";

  type changedComponents = defaultComponents;
  // example how to extend Cart schema:
  // type changedComponents = components & {
  //   schemas: {
  //     Cart: defaultComponents["schemas"]["Cart"] & {
  //       myspecialfield: "hello field";
  //     };
  //   };
  // };

  export type operations = defaultOperations<changedComponents>;
  export type operationPaths = defaultOperationPaths;
  export type Schemas = changedComponents["schemas"];

  //We're exporting our own Api Client definition as it depends on our own instance
  export type ApiClient = ReturnType<
    typeof createAPIClient<operations, operationPaths>
  >;
  export type RequestParameters<T extends keyof operations> =
    DefaultRequestParameters<T, operations>;

  export type RequestReturnType<T extends keyof operations> =
    DefaultRequestReturnType<T, operations>;
}

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 { operationPaths, operations } from "#shopware";

const runtimeConfig = useRuntimeConfig();

const apiClient = createAPIClient<operations, operationPaths>({
  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 { operationPaths, operations } from "#shopware";
import Cookies from "js-cookie";

export const apiClient = createAPIClient<operations, operationPaths>({
  baseURL: "https://demo-frontends.shopware.store/store-api",
  accessToken: "SWSCBHFSNTVMAWNZDNFKSHLAYW",
  contextToken: Cookies.get("sw-context-token"),
  onContextChanged(newContextToken) {
    Cookies.set("sw-context-token", newContextToken, {
      expires: 365, // days
      path: "/",
      sameSite: "lax",
    });
  },
});

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?

We'd like to stabilize the API and release 1.0 version of the packages, in the meantime we're updating OpenAPI schemas to make them better and remove inconsistencies. This will also include some naming changes like removing usage of @shopware-pwa npm package in names or the next suffix. This shouldn't be anything that will make a migration hard, and we'll provide necessary migration steps. Keep an eye on our Github Discussions for more information and updates.