Skip to content

Commit 3576b48

Browse files
bartoszherbabartoszherba
committed
Merge remote-tracking branch 'origin/main' into chore/move-part-of-docs-to-enterprise-repository
2 parents a62a258 + 1916f9f commit 3576b48

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

43 files changed

+2584
-122
lines changed

‎.github/CODEOWNERS

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
1-
* @vuestorefront/integrations-team
1+
* @vuestorefront/application-team
22
actions/check-licenses/* @filrak @rsurowieckivsf
33
docs/**/*.md

‎docs/content/1.index.md

+17-9
Original file line numberDiff line numberDiff line change
@@ -3,29 +3,37 @@ layout: fullscreen
33
hideFromSiteSearch: true
44
---
55

6-
::info
7-
#title
8-
Looking for v2 docs?
9-
#default
10-
These docs are for projects using the Alokai SDK, if you're looking for our Nuxt 2 based solutions, please visit our [v2 docs](https://docs.alokai.com/v2).
11-
::
12-
136
# [Alokai Docs]{.text-4xl.mt-8.block}
147

158

169
Alokai is a Frontend-as-a-Service that provides several tools to help you build performant, scalable, and customizable eCommerce storefronts. From UI libraries and integrations, to deployment and monitoring, we can help you build the ideal headless commerce experience.
1710

18-
::card{title="Getting Started" icon="IconVsf" iconClass="text-primary-500" :coloredIcon="false" }
11+
::grid{:columns='2'}
12+
#section-1
13+
::card{title="Learn the concepts" icon="IconVsf" iconClass="text-primary-500" :coloredIcon="false" class="mb-5"}
1914

2015
#description
21-
Set up a new Alokai project or learn more about our architecture, project principles, and all of the ways that the Alokai ecosystem can help you build better storefronts.
16+
Learn more about our architecture, project principles, and all of the ways that the Alokai ecosystem can help you build better storefronts.
2217

2318
#cta
2419
:::docs-arrow-link{to="/general"}
2520
Learn more
2621
:::
2722
::
2823

24+
#section-2
25+
::card{title="Learn the tools" icon="IconVsf" iconClass="text-primary-500" :coloredIcon="false" }
26+
27+
#description
28+
Learn how to use Alokai hands on from our guides. This is the best place to start if you want to skip the theory and make yoru hands dirty.
29+
30+
#cta
31+
:::docs-arrow-link{to="/guides"}
32+
Learn more
33+
:::
34+
::
35+
36+
::
2937

3038
## Products and Features
3139

‎docs/content/cookbook/1.index.md

+2-6
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,5 @@ navigation:
66

77
# Cookbook
88

9-
::grid{:columns="3"}
10-
#section-1
11-
:card{to="/cookbook/oss-deployment-guide" title="OSS Deployments" description="Deploy to a linux server" icon="typcn:arrow-up-outline"}
12-
13-
14-
::
9+
:card{to="/cookbook/handling-custom-occ-endpoint" title="Handling Custom OCC Endpoints" description="It is a common task to add support for a custom (non-standard) SAP OCC API endpoint not covered by the Alokai intergration.
10+
This guide will show you how can do it using Alokai." icon="typcn:arrow-up-outline"}

‎docs/content/cookbook/handling-custom-occ-endpoint.md

+90-79
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,36 @@
11
# Handling custom OCC endpoints
22

33
It is a common task to add support for a custom (non-standard) SAP OCC API endpoint not covered by the Alokai intergration.
4-
This guide will show you how can do it using Alokai.
4+
There are two ways how you can do it:
55

6-
## Prerequisites
6+
1. Generate new API client based on OpenAPI (swagger) specification.
7+
2. Add support for a custom endpoint manually.
78

8-
Before we start make sure that you are familiar with [Adding New API Methods](https://docs.alokai.com/storefront/integration-and-setup/storefront-extension#adding-new-api-methods) guide. With that guide, you would be able to
9+
## Generating new API client
10+
11+
Generation of new API client allows you to add support for all custom endpoints at once. You just run a script and all the endpoints will be added to the integration.
12+
13+
How to do this is described in the [Generated API guide](/integrations/sapcc/features/generated-api).
14+
15+
This should be your default approach, because it is the most scalable and maintainable way.
16+
17+
## Adding support for a custom endpoint manually
18+
19+
If you don't want or cannot generate a new API client, you can add support for a custom endpoint manually.
20+
It boils down to adding a new API method to the middleware that calls the custom endpoint. This guide shows how to do it efficiently.
21+
22+
When to use this approach?
23+
24+
- When for some reason you cannot generate a new API client, e.g. OpenAPI specification is not available.
25+
- When you are iterating fast both on the API and the front-end and you don't want to regenerate the API client for each change.
26+
27+
### Prerequisites
28+
29+
Before we start make sure that you are familiar with [Adding New API Methods](/unified-data-layer/integration-and-setup/creating-new-api-methods) guide. With that guide, you would be able to
930
communicate with OCC API but it would require manual retrieval of context parameters (baseSiteId, userId, language,
1031
and currency) and preparation of authorization headers. Read on to see how to streamline that process.
1132

12-
## Communicating with OCC API effectively
33+
### Communicating with OCC API effectively
1334

1435
OCC endpoints have a given structure
1536

@@ -35,74 +56,69 @@ Here's where to find the parameters:
3556

3657
- `baseUrl` - is configured in .env file as `SAPCC_API_URI`. The api client already knows it and prepends each URL with it.
3758
- `baseSiteId` - is defined in the middleware configuration. That configuration is exposed to api method via context.
38-
- `userId` - can be found in the request cookies under [`AUTH_USER_COOKIE_NAME`](https://docs.alokai.com/integrations/sapcc/api/sapcc-api/AUTH_USER_COOKIE_NAME).
39-
- `language` - can be found in the request cookies under [`VSF_LOCALE_COOKIE`](https://docs.alokai.com/storefront/features/internationalization/internatialization-support).
40-
- `currency` - can be found in the request cookies under [`VSF_CURRENCY_COOKIE`](https://docs.alokai.com/storefront/features/internationalization/currency-switching).
41-
- authorization token - can be found in the request cookies under [`AUTH_USER_TOKEN_COOKIE_NAME`](https://docs.alokai.com/integrations/sapcc/api/sapcc-api/AUTH_USER_TOKEN_COOKIE_NAME)
59+
- `userId` - can be found in the request cookies under [`AUTH_USER_COOKIE_NAME`](/integrations/sapcc/api/sapcc-api/AUTH_USER_COOKIE_NAME).
60+
- `language` - can be found in the request cookies under [`VSF_LOCALE_COOKIE`](/storefront/features/internationalization/internatialization-support).
61+
- `currency` - can be found in the request cookies under [`VSF_CURRENCY_COOKIE`](/storefront/features/internationalization/currency-switching).
62+
- authorization token - can be found in the request cookies under [`AUTH_USER_TOKEN_COOKIE_NAME`](/integrations/sapcc/api/sapcc-api/AUTH_USER_TOKEN_COOKIE_NAME)
4263

4364
You don't have to parse the cookies yourself. Alokai provides helper methods for that. Here’s a code example of how to do it:
4465

45-
```typescript
46-
import {
47-
SapccIntegrationContext,
48-
TokenModes,
49-
createRequestOptions,
50-
getUserIdFromRequest,
51-
} from "@vsf-enterprise/sapcc-api";
52-
import { BaseProps, BaseUserId } from "@vsf-enterprise/sapcc-types";
66+
```typescript [apps/storefront-middleware/api/custom-methods/types.ts]
67+
import { BaseProps, BaseUserId } from '@vsf-enterprise/sapcc-types';
5368

54-
export interface CustomEndpointProps extends BaseProps, BaseUserId {
69+
export interface CustomMethodArgs extends BaseProps, BaseUserId {
5570
customField: any;
5671
}
5772

58-
export interface CustomResponse {
73+
export interface CustomMethodResponse {
5974
whatever: any;
6075
}
76+
```
77+
78+
```typescript [apps/storefront-middleware/api/custom-methods/custom.ts]
79+
import { createRequestOptions, getUserIdFromRequest, TokenModes } from '@vsf-enterprise/sapcc-api';
80+
import { type IntegrationContext } from '../../types';
81+
import type { CustomMethodArgs, CustomMethodResponse } from './types';
6182

62-
const callCustomEndpoint = async (
63-
context: SapccIntegrationContext,
64-
props: CustomEndpointProps
65-
): Promise<CustomResponse> => {
83+
export async function exampleCustomMethod(
84+
context: IntegrationContext,
85+
args: CustomMethodArgs,
86+
): Promise<CustomMethodResponse> {
6687
const { config, req, client } = context;
6788

68-
const userId = getUserIdFromRequest({ req, props } as any); // retrieves userID from props or cookies
89+
const userId = getUserIdFromRequest({ context, props: args }); // retrieves userID from props or cookies
6990

7091
const res = await client.get(
71-
`/${config.api.baseSiteId}/users/${userId}/customEndpoint/${props.customField}`,
92+
`/${config.api.baseSiteId}/users/${userId}/customEndpoint/${args.customField}`,
7293
createRequestOptions({
7394
// adds authorization headers and language & currency parameters
7495
context,
75-
props,
96+
props: args,
7697
tokenMode: TokenModes.CUSTOMERORAPPLICATION,
77-
})
98+
}),
7899
);
79100

80101
return res.data;
81-
};
102+
}
103+
82104
```
83105

84106
Read more about the helper methods:
85107

86-
- [getUserIdFromRequest](https://docs.alokai.com/integrations/sapcc/api/sapcc-api/getUserIdFromRequest)
87-
- [createRequestOptions](https://docs.alokai.com/integrations/sapcc/api/sapcc-api/createRequestOptions)
108+
- [getUserIdFromRequest](/integrations/sapcc/api/sapcc-api/getUserIdFromRequest)
109+
- [createRequestOptions](/integrations/sapcc/api/sapcc-api/createRequestOptions)
88110

89-
## Real life example
111+
### Real life example
90112

91-
Here's an example implementation of the product interest feature. This feature is available in OCC API, but not in the middleware and SDK integration.
113+
Here's an example implementation of the product interest feature.
92114
Let's add support for it.
93115

94-
First, you need to add a new API method in the middleware. (For simplicity, this guide shows how to do it in one file, but we recommend splitting it into multiple files to maintain cleaner code.)
116+
First, you need to add a new API method in the middleware.
95117

96-
```typescript [storefront-middleware/middleware.config.ts]
97-
import {
98-
SapccIntegrationContext,
99-
TokenModes,
100-
createRequestOptions,
101-
getUserIdFromRequest,
102-
} from "@vsf-enterprise/sapcc-api";
103-
import { BaseProps, BaseUserId, Product } from "@vsf-enterprise/sapcc-types";
118+
```typescript [apps/storefront-middleware/api/custom-methods/types.ts]
119+
import { BaseProps, BaseUserId, Product } from '@vsf-enterprise/sapcc-types';
104120

105-
export interface GetProductInterestsProps extends BaseProps, BaseUserId {
121+
export interface GetProductInterestsArgs extends BaseProps, BaseUserId {
106122
productCode?: string;
107123
}
108124
export interface ProductInterestEntry {
@@ -118,66 +134,61 @@ export interface UserInterestsResponse {
118134
results: Array<ProductInterestRelation>;
119135
}
120136

121-
const getProductInterests = async (
122-
context: SapccIntegrationContext,
123-
props: GetProductInterestsProps
124-
): Promise<UserInterestsResponse> => {
125-
const { config, req, client } = context;
137+
```
126138

127-
const userId = getUserIdFromRequest({ req, props } as any);
139+
```typescript [apps/storefront-middleware/api/custom-methods/custom.ts]
140+
import { createRequestOptions, getUserIdFromRequest, TokenModes } from '@vsf-enterprise/sapcc-api';
141+
import { type IntegrationContext } from '../../types';
142+
import type { GetProductInterestsArgs, UserInterestsResponse } from './types';
143+
144+
export async function getProductInterests(
145+
context: IntegrationContext,
146+
args: GetProductInterestsArgs,
147+
): Promise<UserInterestsResponse> {
148+
const { config, client } = context;
149+
150+
const userId = getUserIdFromRequest({ context, props: args });
128151

129152
const requestOptions = createRequestOptions({
130153
context,
131-
props,
154+
props: args,
132155
tokenMode: TokenModes.CUSTOMERORAPPLICATION,
133156
});
134157

135-
const res = await client.get(
136-
`/${config.api.baseSiteId}/users/${userId}/productinterests`,
137-
{
138-
...requestOptions,
139-
params: {
140-
...requestOptions.params,
141-
productCode: props.productCode,
142-
},
143-
}
144-
);
158+
const res = await client.get(`/${config.api.baseSiteId}/users/${userId}/productinterests`, {
159+
...requestOptions,
160+
params: {
161+
...requestOptions.params,
162+
productCode: args.productCode,
163+
},
164+
});
145165

146166
return res.data;
147-
};
148-
149-
const apiMethods = methods<typeof normalizers>();
150-
const unifiedApiExtension = createUnifiedExtension<Context, Config>()({
151-
normalizers,
152-
apiMethods: {
153-
...apiMethods,
154-
getProductInterests,
155-
},
156-
config: {
157-
/* ... */
158-
},
159-
});
167+
}
168+
```
169+
170+
```typescript [apps/storefront-middleware/api/custom-methods/index.ts]
171+
export { getProductInterests } from './custom';
172+
export * from './types';
160173
```
161174

162175
Then, in your frontend application, you need to add a custom hook to retrieve the product interests on the front end.
163176

164177
```typescript [storefront-unified-nextjs/hooks/useProductInterests/useProductInterests.ts]
165-
import { useQuery } from "@tanstack/react-query";
166-
import { InferSdkArgs, useSdk } from "~/sdk";
178+
import { useQuery } from '@tanstack/react-query';
167179

168-
export type GetProductInterestsArgs = InferSdkArgs<"getProductInterests">;
180+
import { useSdk } from '@/sdk/alokai-context';
169181

170-
export function useProductInterests({ productCode }: GetProductInterestsArgs) {
182+
export function useProductInterests({ productCode }: { productCode: string }) {
171183
const sdk = useSdk();
172184

173185
return useQuery({
174-
queryKey: ["product interests", productCode],
175186
queryFn: () =>
176-
sdk.unified.getProductInterests({
187+
sdk.customExtension.getProductInterests({
177188
productCode,
178189
}),
179-
refetchOnMount: false,
180-
refetchOnWindowFocus: false,
190+
queryKey: ['product interests', productCode],
181191
});
182192
}
193+
183194
```

‎docs/content/guides/1.index.md

+37-11
Original file line numberDiff line numberDiff line change
@@ -9,26 +9,52 @@ Welcome to the guides section of the documentation. Here you will find a collect
99

1010
At **Alokai**, we are committed to providing the best possible experience for our users. We are constantly working on improving our documentation and adding new guides to help you get the most out of the platform.
1111

12-
## Getting Help
13-
If you have any questions or need help with anything, please don't hesitate to get in touch with us in our [Discord](https://discord.vuestorefront.io/). We are always happy to help.
1412

15-
## Alokai Guides
1613

14+
## Learn Alokai
1715

18-
::grid{:columns='3'}
16+
Follow this path to understand how to use Alokai and start building your Alokai application following performance best practices.
17+
::steps
1918

20-
#section-1
21-
:card{to="/guides/alokai-essentials" title="Alokai Essentials" description="Learn how to build Alokai Application: From 0 to Hero. Understand how different parts of our stack will help you to build your Alokai application." icon="tabler:123"}
19+
#step-1
20+
::card{title="Alokai Essentials" to="/guides/alokai-essentials" class="mb-5 !h-auto"}
21+
#description
22+
Learn how to build Alokai Application: From 0 to Hero. Understand how different parts of our stack will help you to build your Alokai application.
23+
::
24+
25+
#step-2
26+
::card{title="Customization" to="/guides/customization-next-js" class="mb-5 !h-auto"}
27+
#description
28+
Alokai is not a cookie-cutter solution, it is meant to be able to handle even the most complex use cases. This guide will take you through the most common customization scenarios.
29+
::
2230

23-
#section-2
24-
:card{to="/guides/performance" title="Performance" description="Improve your website's user experience and increase conversions by optimizing your website's performance." icon="gg:performance"}
31+
#step-3
32+
::card{title="Multistore" to="/guides/multistore" class="mb-5 !h-auto"}
33+
#description
34+
Learn how to create efficient and unified multigeo/multibrand/multivendor setups with Alokai.
35+
::
36+
37+
::
2538

26-
#section-3
27-
:card{to="/guides/customization-next-js" title="Customization" description="Alokai is not a cookie-cutter solution, it is meant to be able to handle even the most complex use cases. This guide will take you through the most common customization scenarios." icon="tabler:tool"}
39+
## Advanced
2840

41+
::card{title="Kubernetes Probes" to="/guides/kubernetes-probe" class="mb-5" icon="tabler:heart-rate-monitor"}
42+
#description
43+
Learn how to implement health check endpoints for your Alokai Cloud applications running on Kubernetes. This guide covers liveness and readiness probes implementation to ensure proper application monitoring and reliability.
2944
::
3045

46+
## Best Practices
47+
48+
::card{title="Performance" to="/guides/best-practices/performance" class="mb-5" icon="tabler:rosette-discount-check"}
49+
#description
50+
Every 100ms added to loading time costed Amazon 1% less sales. Don't let the poor performance to ruin your sales. Learn how to optimize your store for speed.
51+
::
52+
53+
::card{title="Data Fetching" icon="tabler:mobiledata" to="/guides/best-practices/data-fetching" }
54+
#description
55+
Learn how to optimize your data fetching strategy to improve performance and avoid caching errors.
56+
::
3157

3258
::info
3359
Can't find what you're looking for? Check out our [cookbook](/cookbook) for more guides and tutorials.
34-
::
60+
::

‎docs/content/guides/3.performance/_dir.yml

-5
This file was deleted.

0 commit comments

Comments
 (0)