Alokai•14mo ago

New Storefront SDK integration + Middleware rewrite from old (Nuxt) v2 composables - getting started

Hello VSF people I'm starting to explore the new Storefront SDK and Middleware, and will have to reimplement our v2 composable implementation we have and translate it to the new SDK one! Note i don't need an UI/theme or Storefront UI implementation yet. Looking at the documentation i'm a bit lost... https://docs.vuestorefront.io/sdk/getting-started says npm install @vue-storefront/sdk but later on on initializing import { initSDK, buildModule } from '@vsf-enterprise/sdk';... what is the difference between @vue-storefront/sdk and @vsf-enterprise/sdk? Is https://docs.vuestorefront.io/middleware the starting point for the new middleware, aka. old api-client and composables or https://docs.vuestorefront.io/integrations/custom/quick-start is more relevant? https://github.com/vuestorefront/integration-boilerplate is the right boilerplate generator for the new SDK stuff? What happened to the community magento SDK initiative, where can the repo be found (lost it with the Discord reorg)? Also https://github.com/vuestorefront/storefront-next13-boilerplate and https://github.com/vuestorefront/storefront-nuxt3-boilerplate are the relevant new boilerplates for the SDK implemenation or there are some other ones? p.s where do I report in one place all the issues in the docs and github readmes... there are quite a lot of broken or wring links?

Vue Storefront Docs

Getting Started

If you're setting your Vue Storefront application from scratch, you'll need to configure the SDK Core to create a type-safe SDK that communicates with your Server Middleware.

Vue Storefront Docs

Overview

Vue Storefront's Server Middleware is an Express.js application that provides a single place for you to connect to the multiple services that you need to run your storefront.

Vue Storefront Docs

Creating a Custom Integration

If you're looking to create a custom integration for Vue Storefront, you're in the right place. This guide will walk you through the process of creating a custom integration from scratch.

GitHub

GitHub - vuestorefront/integration-boilerplate: Framework Independe...

Framework Independent boilerplate containing SDK and API Client starters. - GitHub - vuestorefront/integration-boilerplate: Framework Independent boilerplate containing SDK and API Client starters.

GitHub

GitHub - vuestorefront/storefront-next13-boilerplate: Vue Storefron...

Vue Storefront Next 13 Boilerplate. Contribute to vuestorefront/storefront-next13-boilerplate development by creating an account on GitHub.

30 Replies

Darren R•14mo ago

Hi @bokjo I'm also about to start this journey. I'm currently using the magento-api integration so I will be looking to replace this with the magento-sdk. This is a starting pint that I'm currnetly using for ideas: https://github.com/TidycodeIT/nuxt3-magento-sdk-storefront

GitHub

GitHub - TidycodeIT/nuxt3-magento-sdk-storefront: A boilerplate sto...

A boilerplate storefront build with the Vue Storefront Magento 2 Integration and Storefront UI - GitHub - TidycodeIT/nuxt3-magento-sdk-storefront: A boilerplate storefront build with the Vue Storef...

bokjo•14mo ago

Hey @Darren R thanks for the reply, i'll take a look! Wasn't this repo in the vuestorefront github, or I'm mistaken, will have to go and watch the videos again 😅 Also is this one https://github.com/vuestorefront/magento2 somehow related?

GitHub

GitHub - vuestorefront/magento2: Vue Storefront 2 integration for M...

Vue Storefront 2 integration for Magento 2. Contribute to vuestorefront/magento2 development by creating an account on GitHub.

Darren R•14mo ago

@bokjo That repo you have posted above is for the Middleware and the SDK. The one I linked to is VSF using those to start building out a Nuxt Boilerplate (Like the VSF2). They don't seem to have gotten too far with it though. I installed it locally today and got it up and running. Ideally, I would want to 'upgrade' our current VSF2 project to use the new SDK setup and Nuxt 3. I'm not sure how feasible this is though right now.

bokjo•14mo ago

Ok perfect, thanks Will have a look at that one too, i'll need to build only integration now i guess. Still don't know all the new stuff and how everything works

skirianov•14mo ago

@bokjo Oh damn, I think there's an error in the documentation! Sorry for that! The correct package is @vue-storefront/sdk - we will fix it asap

skirianov•14mo ago

https://docs.vuestorefront.io/middleware this one is more of a general guide on middleware and the https://docs.vuestorefront.io/integrations/custom/quick-start is the guide to create your own new middleware based on the integration boilerplate

Vue Storefront Docs

Overview

Vue Storefront's Server Middleware is an Express.js application that provides a single place for you to connect to the multiple services that you need to run your storefront.

Vue Storefront Docs

Creating a Custom Integration

If you're looking to create a custom integration for Vue Storefront, you're in the right place. This guide will walk you through the process of creating a custom integration from scratch.

skirianov•14mo ago

https://github.com/vuestorefront/integration-boilerplate - correct, this is a package and CLI to create new integration absed on our new architeture SDK + middleware

GitHub

GitHub - vuestorefront/integration-boilerplate: Framework Independe...

Framework Independent boilerplate containing SDK and API Client starters. - GitHub - vuestorefront/integration-boilerplate: Framework Independent boilerplate containing SDK and API Client starters.

bokjo•14mo ago

Hey @skirianov thanks for the reply, much appreciated. I've started with https://docs.vuestorefront.io/integrations/custom/quick-start ... the scaffold is there and starts fine. But there is also ./packages/demo middleware, which is not mentioned in the page above and i guess is just a demo middleware to make everything work. Essentially we need to create a concrete middleware for our api as well? Can this be done in the same (mono) repo of the custom integration or it should be its own separate repo? The integration should expose just the SDK? like lets say @my-company/storefront-sdk, or it is fine exposing one more package like @my-company/storefront-middleware? Also with the example integration boilerplate app there is ./playground/middleware which is essentially the same as ./packages/demo one, what is the deal with both of those? The Nuxt/Next playground app has to be deployed with baked in middleware server running, or it can be external server running somewhere else (as mentioned in some video/diagram i saw?)

Vue Storefront Docs

Creating a Custom Integration

If you're looking to create a custom integration for Vue Storefront, you're in the right place. This guide will walk you through the process of creating a custom integration from scratch.

bokjo•14mo ago

p.s i see recomendations to use yarn everywhere almost, is there some special reason for it? some issues with npm?

rohrig•14mo ago

Hi @bokjo 👋 , thank you so much for bringing up all of these issues 😄 . It helps us to make things better. - The demo directory will be removed. It's an overlooked relic. Please ignore it and thanks for pointing it out. - Yarn was preferred in previous versions, but npm is fine to use now as well. I'll update the docs to make the more clear. - Regarding what to expose. This is already set up. The SDK is exposed so it can be installed into fronend apps. And the API Client is exposed so it may be installed in a middleware application. Please let me know if that cleared things up for you. 😄

bokjo•14mo ago

Hey @rohrig , thanks for the response. Still figguring out things, rewatched some of your videos and plan to go thhrough your fresh couse as well soon. I'm gatering some stuff as i go allong, there are some issues in the docs, like links and some references to @vsf-enterprise/sdk, some hardcoded package versions in the boilerplate like "@vue-storefront/middleware": "3.0.0-rc.2", for example that need updating and making sure it works with the latest version ok. npx @vue-storefront/cli add endpoint exampleChe works but it doesn't report all the stuff it is doing.

npx @vue-storefront/cli add endpoint exampleChe

┌  Endpoint exampleChe has been created
│
◇  Files created:
│
◇  - packages/api-client/src/api/exampleChe
│
◇  - packages/sdk/src/methods/exampleChe
│
◇  Files updated:
│
◇  - packages/api-client/src/api/index.ts
│
◇  - packages/sdk/src/methods/index.ts
│
◇  - packages/api-client/src/types/api/endpoints.ts
│
◇  Run build command to build the project and dev command to start the playground again

npx @vue-storefront/cli add endpoint exampleChe

┌  Endpoint exampleChe has been created
│
◇  Files created:
│
◇  - packages/api-client/src/api/exampleChe
│
◇  - packages/sdk/src/methods/exampleChe
│
◇  Files updated:
│
◇  - packages/api-client/src/api/index.ts
│
◇  - packages/sdk/src/methods/index.ts
│
◇  - packages/api-client/src/types/api/endpoints.ts
│
◇  Run build command to build the project and dev command to start the playground again

it also creates a exampleChe.vue page but in the wrong location... goes to playground/app/pages/exampleChe.vue instead of to playground/app/pages/methods/exampleChe.vue also the template is hardcoded to const { data } = await sdk.boilerplate.exampleChe('test'); it seems, it doesn't respect the custom module you are building that is named lets say my_example and it is already present in the sdk.config.ts sdkConfig object. should become const { data } = await sdk.my_example.exampleChe('test'); Will try to gather as much as possible things like this and compile them in one place!

rohrig•14mo ago

It would be great if you open up issues on github for these. 😄 It will make things easier to track.

bokjo•14mo ago

p.s when it updates packages/api-client/src/types/api/endpoints.ts it uses BoilerplateIntegrationContext which is hardcoded and becomes exampleChe(context: BoilerplateIntegrationContext, params: TODO): Promise<TODO>; even tho you have updated the context type above... it is not a big deal you can change it easilly, but it is strange to see the build fail right away 🙂 also one more remark for now 😅 , see the examples and also over on the magento2 sdk implemetation all the methods ali something like addXYZCart, removeXYZCart , productXYZ , products etc. etc which is becomes really cumbersome and not that visible really fast, and also you end up with a lot of routes on the middleware like /boilerplate/addXYZCart . Is this due to the integrations interface of sorts? and it is recommended to go that route? It would be nice if i can put everything related to a business scope in a separate folder like products, cart etc. and end up on middleware side with something like /boilerplate/products/xyz, boilerplate/cart/xyz... hope you get my point

rohrig•14mo ago

you're right, if the boilerplate name is updated subsequent template creations don't respect the name change. I'll create some tickets for these issues in the GitHub Repo

bokjo•14mo ago

perfect, sorry cannot create those right away... i'm trying to update packages one by one, few of them have new major versions and have no idea what might break (wether due to update or Node v20 I'm using). for example rollup-plugin-terser for @rollup/plugin-terser and rollup-plugin-typescript2 for @rollup/plugin-typescript which doesn't support objectHashIgnoreUnknownHack: false. I see quite a lot of the same or similar inplementation with the old boilerplate for Nuxt v2 (which was sort of stuck to Node v16). But really hate working with old or not that maintained packages...
p.s there are some missing packages and build fails for the playground app... @vue-storefront/sdk is missing as package but it is imported in playground/app/sdk.config.ts... Strange thing is that with lerna -> "npmClient": "yarn" it was working ok (guess due to the workspaces and resolution, but with "npmClient": "npm" it fails to build.

bokjo•14mo ago

Hey @rohrig created https://github.com/vuestorefront/integration-boilerplate/issues/21 and https://github.com/vuestorefront/integration-boilerplate/issues/20 for now will add more if needed 🙂 p.s successfully update all packages to latest and run on NodeJS v20

GitHub

Update packages to latest and align on NodeJS v18 and v20 and add m...

Describe the feature Some packages in the boilerplate are hardcoded to an exact version that should be the case! @vue-storefront/middleware => https://github.com/vuestorefront/integration-boiler...

GitHub

Missmatch style (css/html) between the boilerplate exampleMethod.vu...

Environment MacOs NodeJS v20 npm rollup? Reproduction npx @vue-storefront/cli add endpoint exampleChe Describe the bug generated exampleChe.vue page in the playground app has a different styling an...

rohrig•14mo ago

Cool, thanks for letting me know. I'm working on moving integration-specific cli logic to the boilerplate so the integrators, such as yourself, have complete control and can customize it to their needs.

rohrig•14mo ago

It's a work in progress: https://github.com/vuestorefront/integration-boilerplate/pull/22

GitHub

feat/cli by rohrig · Pull Request #22 · vuestorefront/integration-b...

🔗 Linked issue ❓ Type of change 📖 Documentation (updates to the documentation, readme or JSDoc annotations) 🐞 Bug fix (a non-breaking change that fixes an issue) 👌 Enhancement (improving an e...

bokjo•14mo ago

Hey thanks for letting me know! I've started porting stuff... still missing bunch of GQL boilerplate setup and testing to do. Managed to have it in a updated but stable enough state for now (not really happy with the setup, but will improve/change it accordingly later on), but kind of constrained on time until next week. Will report extra stuff if they come up later, let me know if I can help somehow otherwise in the meantime.

rohrig•14mo ago

@bokjo feel free to make a pull request any time you think a change would benefit everyone. 😄

bokjo•14mo ago

@rohrig yeah it is not big of a deal, like small issues here and there... but i'm more concerned about the overall architecture and options regarding GQL backends/APIs. Who is the best person to speak to about general ideas and possibilities?
It feels like the middleware is more suitable for REST apis, with GQL ones I'm loosing the general idea of GQL to fetch what is needed from the backend and just do over-fetching aka. fetch everything what the GQL API offers for that query/mutation... which defies the purpose of GQL. I would rather build some kind of query builder on SDK side where the user will specify what it needs from that query/mutation and pass that to the backend/API... but that would be a bit more involved. I'm looking at the Magento2 GQL implementation and borrowing some ideas (where I have to report some issues just looking at the code btw...), guess there the implementation makes sense because the gql api seems to be monolithic and without federation. The custom query part is nice but a bit cumbersome and for advanced users. Also if I opt to build out integration as the one before it will be too opinionated and people will just start overwriting stuff with custom queries...

Filip Rakowski•14mo ago

Hey @bokjo! For a GraphQL API's one trick that I recommended to other integrator is to "just" have one endpoint called /api (or a few more when needed eg. one for queries, one for mutations, one for auth depending on your preference) and pass Queries/mutations directly from the frontend. The initial reason why we wanted to have the GQL integrations split by methods was based on assumptions that are no longer the case so if you're making a new integration I'd go this way. Then on the frontend you basically only do

import {productQuery} from '@/queries'

const result = await sdk.yourintegration.query({
    customQuery: productQuery
});

import {productQuery} from '@/queries'

const result = await sdk.yourintegration.query({
    customQuery: productQuery
});

leonardomuniz1094•14mo ago

I really enjoy this way of implement sdk @Filip Rakowski . But it will show our queries in browser right ?

bokjo•14mo ago

Hey @Filip Rakowski thanks for the suggestion, much appreciated! Guess the one endpoint makes sense for executing arbitrary custom queries, and leave the frontend implementor to deal with "implementation". The problem again here is that the provided/suggested productQuery is static and will most likely contain all the data from product, which might be fine when you are building something like ProductDetail page but certainly is not needed for some other random place where lets say just sku, name, image and inventory is needed. My idea was on the lines of leave the productDetail endpoint as is and provide an opinionated query to begin with, if you don't like it or need something extra then override and provide custom query... but you will have to be constrained on the product gql contract (and not provide 6 other nested queries along the way), i might explore something like graphql-zeus that builds the typescript types and provides you with autocomplete query builder of sorts (similar experience like writing the query in a playground....) . Is there some concrete contract/interface that the SDK should follow? Especially in what it can export as additional helper functions? (like the customQueryBuilder from above) Speaking of contract/interfaces, is there some plugin mechanism and/or middleware that the custom implementation SDK can provide? Things like Authn/Authz , login, JWT, OAuth2 flow handling, payment provider webhook handlers... like plugin marketplace that can be used with config? Or everything is left open to the integration builder to handle it as it fits? Hey @rohrig is there some validation options in place for the middleware integration settings to fail starting if some mandatory field like apiUrl or apiKey is not provided? p.s is it intentional to return generic 500 error from the sdk (or whenever this error is comming from, cannot find it in any repo...) in the app like ServerError: Response not successful. Please, check server logs for more details. even tho the middleware returned something like ServerError: Response not successful: Received status code 401 ?... would expect to be just propagated as is

rohrig•14mo ago

Hi @bokjo 👋 , propagating the error makes sense to me as well. I'll look into it. Please open up new posts when you have new issues. Otherwise it makes it difficult to know when something as been resolved and it increases the likelihood that we overlook something.

bokjo•14mo ago

i'll open up a github issues it is not a problem, but where? vsf sdk/middleware repo or boilerplate? (no idea where the error is comming from)

rohrig•14mo ago

This sounds like the middleware to me. 😄 Thank you for opening the issue.

bokjo•14mo ago

https://github.com/vuestorefront/vue-storefront/issues/6970 done... p.s will see what happens if i handle explicitly the error in the api-client package

GitHub

@vue-storefront/middleware doesn't propagate 4xx errors and returns...

Environment MacOS Node v20 @vue-storefront/middleware: 3.5.1 @vue-storefront/sdk: 1.1.2 Reproduction From the frontend app implementation call a SDK endpoint through the middleware that calls exter...

rohrig•14mo ago

Thanks 😄

bokjo•14mo ago

NP, i'll create improvement/FR task for this one i guess

Gaming

Programming

New Storefront SDK integration + Middleware rewrite from old (Nuxt) v2 composables - getting started