Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: add pass headers guide #6960

Open
wants to merge 12 commits into
base: main
Choose a base branch
from
Prev Previous commit
Next Next commit
fix: steps not rendering - use plain text
  • Loading branch information
rohrig committed Dec 20, 2023
commit cf6a36bb53dcb64698c19d17efb4353d71f41ee1
Original file line number Diff line number Diff line change
Expand Up @@ -18,27 +18,27 @@ This guide uses the integrations boilerplate with the nuxt option. The same basi
All SDK modules export a client instance of axios. This is the axios instance that is used to make requests to the Server Middleware. You can access this instance by importing the `client` from the SDK.

## Steps
::steps
#step-1
**Import Required Modules**

step 1.
### **Import Required Modules**

```javascript
import { initSDK, buildModule } from '@vue-storefront/sdk';
import { client, boilerplateModule, BoilerplateModuleType } from '../../packages/sdk/src';
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it proper path?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't understand, where is the client coming from, is it exposed by every SDK module? Is it coordinated with the unified team, do they expose it as well the same way?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This import path should be less ambigious. But long story short: the client is coming from an SDK module (e.g. sapcc-sdk), every module exports the client. Not sure this is going to be the case in a few weeks/months (considering the ongoing discussion initiated by @bartoszherba) but, for now, that's the state of things.

Copy link
Contributor

@michaelKurowski michaelKurowski Dec 20, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I really think this doc should be agreed upon with unified. Consider how confused a customer on unified storefront would be after seeing these docs if unified module doesn't expose this (and honestly they probably couldn't know before that they should).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This guide sat on the back burner for a while. Given the change in landscape since it's inception I agree there should be a consensus and standard way of doing this. RE: comments about ootb, I think it would be sensible for for the Unified team to implement the boilerplate to allow passing custom headers and allow the end dev to use a one-liner, if possible, to add headers to requests. The guide for an ootb solution would be a separate guide though.

we still have two scenarios:

  1. Projects using Unified: for those we can have an ootb solution and a separate guide
  2. Non-Unified: this sort of guide will still be necessary.

import useHeaders from 'path-to-useHeaders-file'; // Replace with the correct path to the `useHeaders` composable.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we provide it for our storefronts?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah it's below

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably we should make it more clear

Copy link
Contributor

@michaelKurowski michaelKurowski Dec 20, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't understand, who does provide the useHeaders, it's our product we should know the path to the composable if we provide it πŸ€”

Copy link
Contributor

@michaelKurowski michaelKurowski Dec 20, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It also feels like it's strictly vue specific since it mentions composables, is this what we want? I don't see any references to vue in the path of this file so it seems like you provide the general advice

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see that the customer is responsible for creation of the composable, but my question regarding the vue-centric docs remain.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree, if we can create a solution that framework agnostic that would be ideal. But I think given the differences in how Next and Nuxt handle ssr/state, I'm not sure that's possible. I'm not familiar enough with Next to know.

For context, the guide was made in response to an integrator's query that was using Nuxt. This started as general enablement and turned into a guide when several more folks asked the same question and all were using Nuxt.

If it's not possible to provide a framework agnostic solution, we can at least add examples in both support frameworks.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm ok for both frameworks! :) Just including nuxt only solution felt a bit off

```

#step-2
**Define the SDK Configuration**
step 2.
### **Define the SDK Configuration**
```javascript
const sdkConfig = {
boilerplate: buildModule<BoilerplateModuleType>(boilerplateModule, {
apiUrl: 'http://localhost:8181/boilerplate',
}),
};
```
#step-3
**Fetch Headers with the useHeaders Composable**
step 3.
### **Fetch Headers with the useHeaders Composable**

Use the `useHeaders` composable to fetch the necessary headers. This composable manages both server-side and client-side headers for you.

Expand All @@ -47,8 +47,8 @@ const { addHeadersToState, headerData } = useHeaders();
addHeadersToState();
```

#step-4
**Setting Up Axios Interceptor**
step 4.
### **Setting Up Axios Interceptor**

Before making requests using axios, establish an interceptor to automatically append the desired headers.

Expand Down Expand Up @@ -88,17 +88,17 @@ interceptorId = client.interceptors.request.use(
);
```

#step-4
**Initialize and Export the SDK**
step 5.
### **Initialize and Export the SDK**

Finally, initialize the SDK with your configuration and export it.

```javascript
return initSDK<typeof sdkConfig>(sdkConfig);
```

#step-5
**sdk.config.ts** all together
step 6.
### **sdk.config.ts** all together

```javascript
import { initSDK, buildModule } from '@vue-storefront/sdk';
Expand Down Expand Up @@ -150,7 +150,7 @@ export const useSdk = () => {
This guide uses a `useHeaders` composable. This composable manages both server-side and client-side headers for you. This is just an example, you can use any method you want to fetch the headers.
::

#step-6
step 7.
**Create a Composable to Handle Headers**

```javascript
Expand Down Expand Up @@ -201,15 +201,13 @@ export default function () {

You've now set up an interceptor to append custom headers to requests using the axios client in the Vue Storefront SDK. This ensures that all outgoing requests contain the headers you've defined and the Server Middleware will be able to access them through the request object.

::

## Passing Headers from API Client to external services

Now that you're passing headers from the Vue Storefront SDK client to the Server Middleware, you may want to pass them further to external services (e.g. SAP OCC API). To achieve that, you're going to create a Server Middleware extension which reads the headers from the request object and appends them as defaults to the Server Middleware client.

## Steps
::steps
#step-1
step 8.
### Creat server middleware extension

Create a new Server Middleware extension in the `middleware.config.ts` file. In the extension, utilize the `afterCreate` hook which fires after the Server Middleware client had been created.

Expand Down Expand Up @@ -260,4 +258,3 @@ You can verify the extension is loading by checking the console output when you
If everything is working correctly, you should now be able to see the custom header in your external service.

You can verify this by logging the headers in your external service, or by using a tool like HTTP Toolkit to inspect the requests.
::
Loading