From 89bf3c7865361c158bd2fe8142f703b32d37b4d5 Mon Sep 17 00:00:00 2001 From: andrzejewsky Date: Mon, 11 Jan 2021 15:29:12 +0100 Subject: [PATCH 1/2] update docs --- packages/core/docs/.vuepress/config.js | 1 - .../core/docs/commercetools/composables.md | 3 +- .../core/docs/integrate/api-middleware.md | 52 ------------------- .../core/docs/integrate/integration-guide.md | 10 ++-- 4 files changed, 7 insertions(+), 59 deletions(-) delete mode 100644 packages/core/docs/integrate/api-middleware.md diff --git a/packages/core/docs/.vuepress/config.js b/packages/core/docs/.vuepress/config.js index 8e3c9d61c98..70766b91a83 100644 --- a/packages/core/docs/.vuepress/config.js +++ b/packages/core/docs/.vuepress/config.js @@ -186,7 +186,6 @@ module.exports = { children: [ ['/integrate/integration-guide', 'Integration guide'], ['/general/cms', 'CMS'], - ['/integrate/api-middleware', 'API middleware'], ] }, { diff --git a/packages/core/docs/commercetools/composables.md b/packages/core/docs/commercetools/composables.md index 95d1e7c9c85..45b645fc4b1 100644 --- a/packages/core/docs/commercetools/composables.md +++ b/packages/core/docs/commercetools/composables.md @@ -55,7 +55,8 @@ const customQuery = (query, variables) => { variables: newVariables } } -search({ id: '12345' }, customQuery) + +search({ id: '12345', customQuery }) ``` Use it for: `useProduct`, `useCategory`, `useUser`, `useUserOrders` methods. diff --git a/packages/core/docs/integrate/api-middleware.md b/packages/core/docs/integrate/api-middleware.md deleted file mode 100644 index 29ef1f65ba3..00000000000 --- a/packages/core/docs/integrate/api-middleware.md +++ /dev/null @@ -1,52 +0,0 @@ -# API middleware - -Sometimes, due to security reasons, our integrations need to be hidden behind some server middleware which works as a sort of proxy, but it introduces a bit more transparency for the client-side so the app doesn't have to know, how API works itself. - -If some of the integration need to implement such a proxy for Nuxt.js, the core introduces a special function `createMiddleware` which registers provided middleware and gives us the ability to extend it. - -## Nuxt module -As each integration has its own nuxt module, we are able to add a middleware as well. Below is the example: - -```js -import { createMiddleware } from '@vue-storefront/core/server'; - -export default function (moduleOptions) { - const { middleware, extend } = createMiddleware(moduleOptions); - - extend((app) => { - app.get('/add-user', (req, res) => { - res.send({ userAdded: true }); - }); - }) - - this.addServerMiddleware(middleware); -} -``` - -The function `createMiddleware` returns two properties: -- `middleware` - which is the created middleware used directly by `addServerMiddleware` -- `extend` - a function that adds a new endpoint to the middleware. It takes as an argument an express.js instance - -## Nuxt module configuration - -Once we have created our middleware in the integration, `createMiddleware` exposes also config option, called `apiMiddleware`. Inside of this section you can extend your API by using `extend` function, or disable it at all by setting `apiMiddleware` to false - -Extending example: -```js -['@vue-storefront/{PLATFORM}/nuxt', { - apiMiddleware: { - extend: (app) => { - app.get('/add-custom-user', (req, res) => { - res.send({ customizedUser: true }); - }); - } - } -}] -``` - -Disabling middleware example: -```js -['@vue-storefront/{PLATFORM}/nuxt', { - apiMiddleware: false -}] -``` diff --git a/packages/core/docs/integrate/integration-guide.md b/packages/core/docs/integrate/integration-guide.md index fee90f33c60..cc37d06f291 100644 --- a/packages/core/docs/integrate/integration-guide.md +++ b/packages/core/docs/integrate/integration-guide.md @@ -262,12 +262,12 @@ interface LineItem { /* ... */} interface ProductVariant { /* ... */ } const factoryParams: UseCartFactoryParams = { - loadCart: async (context: Context) => { + load: async (context: Context) => { const { data } = await context.$ct.api.getCart(); return data.cart; }, - addToCart: async (context: Context, params) => { + addItem: async (context: Context, params) => { const { currentCart, product, quantity } = params; const { data } = await context.$ct.api.addToCart(loadedCart, product, quantity, customQuery); @@ -304,7 +304,7 @@ const factoryParams: UseUserFactoryParams = { setup() { return useCart(); }, - loadUser: async (context: UserContext) => { + load: async (context: UserContext) => { const { data } = await context.$ct.api.getUser(); context.setCart(data.activeCart); @@ -329,7 +329,7 @@ const useCart = () => { const cart = vsfRef(null, 'my-own-cart') const context = generateContext(); // we do the job for you - const addToCart = async (product) => { + const addToCart = async ({ product }) => { return context.$ownAPI.updateCart(product) } @@ -405,7 +405,7 @@ import { onSSR } from '@vue-storefront/core'; export default { setup () { - const { cart, loadCart } = useCart(); + const { cart, load: loadCart } = useCart(); const items = computed(() => cartGetters.getItems(cart.value)) From 65d70ef0cffd4509a6df534044c97a38b7846ea3 Mon Sep 17 00:00:00 2001 From: andrzejewsky Date: Tue, 12 Jan 2021 17:12:40 +0100 Subject: [PATCH 2/2] update docs --- packages/core/docs/.vuepress/config.js | 10 ++- packages/core/docs/migrate/2.2.0.md | 8 +++ packages/core/docs/migrate/index.md | 68 ------------------ .../core/docs/migrate/integrators-2.2.0.md | 28 ++++++++ packages/core/docs/migrate/projects-2.2.0.md | 45 ++++++++++++ packages/core/docs/migrate/rc1.md | 70 +++++++++++++++++++ 6 files changed, 160 insertions(+), 69 deletions(-) create mode 100644 packages/core/docs/migrate/2.2.0.md create mode 100644 packages/core/docs/migrate/integrators-2.2.0.md create mode 100644 packages/core/docs/migrate/projects-2.2.0.md create mode 100644 packages/core/docs/migrate/rc1.md diff --git a/packages/core/docs/.vuepress/config.js b/packages/core/docs/.vuepress/config.js index 70766b91a83..4c37974d17f 100644 --- a/packages/core/docs/.vuepress/config.js +++ b/packages/core/docs/.vuepress/config.js @@ -17,10 +17,18 @@ module.exports = { { title: 'Migration guide RC.1', children: [ - ['/migrate/', 'Overview'], + ['/migrate/rc1', 'Overview'], ['/migrate/integrators-rc1', 'Integrators'], ['/migrate/projects-rc1', 'Projects'], ] + }, + { + title: 'Migration guide 2.2.0', + children: [ + ['/migrate/2.2.0', 'Overview'], + ['/migrate/integrators-2.2.0', 'Integrators'], + ['/migrate/projects-2.2.0', 'Projects'], + ] } ], '/commercetools/': [ diff --git a/packages/core/docs/migrate/2.2.0.md b/packages/core/docs/migrate/2.2.0.md new file mode 100644 index 00000000000..008ed9405f8 --- /dev/null +++ b/packages/core/docs/migrate/2.2.0.md @@ -0,0 +1,8 @@ +# Migration guide 2.2.0 + +This version introduces many renamings or changes related to the function declarations among of the core. We had to proceed with this in order to keep the convention and unify the naming across whole VSF. + +We changes the composables and our factories according to the following rules: +- each composable return always one field with the response from the api +- each composable function takes one argument wich is an object of given parameters +- each factory param function takes two argumens, first one is context (as it was before) and second one contains a function parmeters along with other options (such as customQuery) diff --git a/packages/core/docs/migrate/index.md b/packages/core/docs/migrate/index.md index c35c9a256b8..f90e64129e0 100644 --- a/packages/core/docs/migrate/index.md +++ b/packages/core/docs/migrate/index.md @@ -1,70 +1,2 @@ # Migration guide -This guide contains a list of changes, in order to upgrade your VSF next to the RC.1 version. - -## The general overview - -In general, besides the smaller changes, we totally have changed the way of accessing configuration or API functions. -Always, instead of using configuration or networking stored in the global objects, we recommend to use context, provided by us. - -Each time you want to access an integration stuff, such as network client, configuration or API functions please use `useVSFContext` - -```js -import { useVSFContext } from '@vue-storefront/core'; - -export default { - setup () { - const { $integrationTag } = useVSFContext(); - } -} - -``` - -For more information, please read the section [Application Context](/general/context) in the general docs. - -## List of changes for certain users - -- [Changes for integrators](/migrate/integrators) -- [Changes for projects](/migrate/projects) - - -## Common problems - -### Composition API already installed - -``` -[vue-composition-api] already installed. Vue.use(VueCompositionAPI) should be called only once. -``` - -**Solution**: Please make sure that you have everywhere the same version of vue composition api as the one we use in the core - -### Using Composition API before is being installed - -``` -Uncaught Error: [vue-composition-api] must call Vue.use(plugin) before using any function. -``` -**Solution**: if you are using compositon API (eg. `ref`) above the component, please make sure that you have `vue-composition-api` installed, or move these calls inside of the `setup` function. - -### Some of our package doesn't work, the context doesn't return anything or has missing data - -**Solution**: Please make sure that you put package in the raw sources section, and if the integration has nuxt module and extend an existing one, should be aded before our core nuxt module and the one with integration - -```js -{ - ['@vue-storefront/some-new-integration/nuxt', {}], // 2 - ['@vue-storefront/nuxt', { - coreDevelopment: true, - useRawSource: { - dev: [ - '@vue-storefront/core' - '@vue-storefront/other-package' // 1 - ], - prod: [ - '@vue-storefront/core', - '@vue-storefront/other-package' // 1 - ] - } - }], - ['@vue-storefront/some-integration/nuxt', {}] -} -``` diff --git a/packages/core/docs/migrate/integrators-2.2.0.md b/packages/core/docs/migrate/integrators-2.2.0.md new file mode 100644 index 00000000000..4842620e108 --- /dev/null +++ b/packages/core/docs/migrate/integrators-2.2.0.md @@ -0,0 +1,28 @@ +# Integrators upgrade notes + +## Factory usage + +We have changes a bit the naming and signatures of core factory functions. Below is the full list of what hs been implemented or changed: + +| Factory | Old method | New method | Old signature | New signature | +|------------|--------|---------------|---------------|---| +| useCartFactory | addToCart | addItem | context, { currentCart: cart.value, product, quantity }, customQuery | context, { currentCart: cart.value, product, quantity, customQuery } | +| useCartFactory | loadCart | load | context: Context, customQuery?: CustomQuery | context: Context, { customQuery?: any } | +| useCartFactory | removeFromCart | removeItem | context: Context, params: { currentCart: CART, product: CART_ITEM }, customQuery?: CustomQuery | context: Context, params: { currentCart: CART, product: CART_ITEM, customQuery?: CustomQuery } | +| useCartFactory | updateQuantity | updateItemQty | context: Context, params: { currentCart: CART, product: CART_ITEM, quantity: number }, customQuery?: CustomQuery | context: Context, params: { currentCart: CART, product: CART_ITEM, customQuery?: CustomQuery } | +| useCartFactory | clearCart | clear | context: Context, prams: { currentCart: CART } | context: Context, params: { currentCart: CART } | +| useCartFactory | applyCoupon | No changes | context: Context, params: { currentCart: CART; couponCode: string }, customQuery?: CustomQuery | context: Context, params: { currentCart: CART, couponCode: string, customQuery?: CustomQuery } | +| useCartFactory | removeCoupon | No changes | context: Context, params: { currentCart: CART; coupon: COUPON }, customQuery?: CustomQuery | context: Context, params: { currentCart: CART; coupon: COUPON, customQuery?: CustomQuery } | +| useCategoryFactory | categorySearch | No changes | context: Context, searchParams: CATEGORY_SEARCH_PARAMS, customQuery: CustomQuery | context: Context, params: CATEGORY_SEARCH_PARAMS & { customQuery?: CustomQuery } | +| useProductFactory | productsSearch | No changes | context: Context, searchParams: PRODUCT_SEARCH_PARAMS, customQuery?: CustomQuery | context: Context, params: PRODUCT_SEARCH_PARAMS & { customQuery?: CustomQuery } | +| useReviewFactory | searchReviews | No changes | context: Context, params: REVIEWS_SEARCH_PARAMS, customQuery?: CustomQuery | context: Context, params: REVIEWS_SEARCH_PARAMS & { customQuery?: CustomQuery } | +| useReviewFactory | addReview | No changes | context: Context, params: REVIEW_ADD_PARAMS, customQuery?: CustomQuery | context: Context, params: REVIEW_ADD_PARAMS & { customQuery?: CustomQuery } | +| useUserBillingFactory | setDefault | setDefaultAddress | context: Context, params: { address: Readonly; shipping: Readonly; }) | No changes | +| useUserShippingFactory | setDefault | setDefaultAddress | context: Context, params: { address: Readonly; shipping: Readonly; }) | No changes | +| useUserFactory | loadUser | load | context: Context, | context: Context, params?: {} | +| useUserOrdersFactory | searchOrders | No changes | context: Context, params: ORDER_SEARCH_PARAMS, customQuery?: CustomQuery | context: Context, params: ORDER_SEARCH_PARAMS & { customQuery?: CustomQuery } | +| useWishlistFactory | addToWishlist | addItem | context, { currentWishlist: WISHLIST, product: PRODUCT }, customQuery | context, { currentWishlist: WISHLIST, product: PRODUCT, customQuery } | +| useWishlistFactory | loadWishlist | load | context: Context, customQuery?: CustomQuery | No changes | +| useWishlistFactory | removeFromWishlist | removeItem | context: Context, params: { currentWishlist: WISHLIST, product: WISHLIST_ITEM }, customQuery?: CustomQuery | context: Context, params: { currentWishlist: WISHLIST, product: WISHLIST_ITEM, customQuery?: CustomQuery } | +| useWishlistFactory | clearWishlist | clear | context: Context, params: { currentWishlist: WISHLIST } | No changes | +| useWishlistFactory | loadWishlist | load | context: Context, customQuery?: CustomQuery | context: Context, { customQuery?: any } | \ No newline at end of file diff --git a/packages/core/docs/migrate/projects-2.2.0.md b/packages/core/docs/migrate/projects-2.2.0.md new file mode 100644 index 00000000000..f2b0351ea16 --- /dev/null +++ b/packages/core/docs/migrate/projects-2.2.0.md @@ -0,0 +1,45 @@ +# Project upgrade notes + +## Composables usage + +We have changes a bit the naming and signatures of composable functions. Below is the full list of what hs been implemented or changed: + +| Composable | Method | Old signature | New signature | +|------------|--------|---------------|---------------| +| useCart | addToCart | (product: PRODUCT, quantity: number, customQuery?: CustomQuery) | ({ product: PRODUCT, quantity: number, customQuery?: CustomQuery }) | +| useCart | removeFromCart | (product: CART_ITEM, customQuery?: CustomQuery) | ({ product: CART_ITEM, customQuery?: CustomQuery }) | +| useCart | updateQuantity | (product: CART_ITEM, quantity?: number, customQuery?: CustomQuery) | ({ product: CART_ITEM, quantity?: number, customQuery?: CustomQuery }) | +| useCart | load | (customQuery?: CustomQuery) | ({ customQuery?: CustomQuery } = {}) | +| useCart | clearCart | () | () | +| useCart | applyCoupon | (couponCode: string, customQuery?: CustomQuery) | ({ couponCode: string, customQuery?: CustomQuery }) | +| useCart | isOnCart | (product: PRODUCT) | ({ product: PRODUCT }) | +| useCart | removeCoupon | (coupon: COUPON, customQuery?: CustomQuery) | ({ coupon: COUPON, customQuery?: CustomQuery }) | +| useCart | setCart | (newCart: CART) | ({ newCart: CART }) | +| useCategory | search | (searchParams: CATEGORY_SEARCH_PARAMS, customQuery?: CustomQuery) | ({ ...searchParams: CATEGORY_SEARCH_PARAMS, customQuery?: CustomQuery }) | +| useContent | search | (params: CONTENT_SEARCH_PARAMS) | No changes | +| useFacet | search | (params?: AgnosticFacetSearchParams) | No changes | +| useProduct | search | (searchParams: PRODUCT_SEARCH_PARAMS, customQuery?: CustomQuery) | ({ ...searchParams: PRODUCT_SEARCH_PARAMS, customQuery?: CustomQuery }) | +| useReview | search | (searchParams: REVIEWS_SEARCH_PARAMS, customQuery?: CustomQuery) | ({ ...searchParams: REVIEWS_SEARCH_PARAMS, customQuery?: CustomQuery }) | +| useReview | addReview | (addParams: REVIEW_ADD_PARAMS, customQuery?: CustomQuery) | ({ ...addParams: REVIEW_ADD_PARAMS, customQuery?: CustomQuery }) | +| useUserBilling | addAddress | (address: USER_BILLING_ITEM) | ({ address: USER_BILLING_ITEM }) | +| useUserBilling | deleteAddress | (address: USER_BILLING_ITEM) | ({ address: USER_BILLING_ITEM }) | +| useUserBilling | updateAddress | (address: USER_BILLING_ITEM) | ({ address: USER_BILLING_ITEM }) | +| useUserBilling | setDefault | (address: USER_BILLING_ITEM) | ({ address: USER_BILLING_ITEM }) | +| useUserBilling | load | () | () | +| useUserShipping | addAddress | (address: USER_SHIPPING_ITEM) | ({ address: USER_SHIPPING_ITEM }) | +| useUserShipping | deleteAddress | (address: USER_SHIPPING_ITEM) | ({ address: USER_SHIPPING_ITEM }) | +| useUserShipping | updateAddress | (address: USER_SHIPPING_ITEM) | ({ address: USER_SHIPPING_ITEM }) | +| useUserShipping | setDefault | (address: USER_SHIPPING_ITEM) | ({ address: USER_SHIPPING_ITEM }) | +| useUserShipping | load | () | () | +| useUser | updateUser | (params: UPDATE_USER_PARAMS) | ({ user: UPDATE_USER_PARAMS }) | +| useUser | register | (registerUserData: REGISTER_USER_PARAMS) | ({ user: REGISTER_USER_PARAMS }) | +| useUser | login | (loginUserData: { username: string; password: string; }) | ({ user: LOGIN_USER_PARAMS }) | +| useUser | logout | () | () | +| useUser | changePassword | (currentPassword: string, newPassword: string) | ({ currentPassword: string, newPassword: string }) | +| useUser | load | () | () | +| useUserOrders | searchOrders | (searchParams: ORDER_SEARCH_PARAMS, customQuery?: CustomQuery) | ({ ...searchParams: ORDER_SEARCH_PARAMS, customQuery?: CustomQuery } = {}) | +| useWishlist | addToWishlist | (product: PRODUCT, customQuery?: CustomQuery) | ({ product: PRODUCT, customQuery?: CustomQuery }) | +| useWishlist | removeFromWishlist | (product: WISHLIST_ITEM, customQuery?: CustomQuery) | ({ product: WISHLIST_ITEM, customQuery?: CustomQuery }) | +| useWishlist | load | (customQuery?: CustomQuery) | ({ customQuery?: CustomQuery } = {}) | +| useWishlist | clearWishlist | () | () | +| useWishlist | isOnWishlist | (product: PRODUCT) | ({ product: PRODUCT }) | \ No newline at end of file diff --git a/packages/core/docs/migrate/rc1.md b/packages/core/docs/migrate/rc1.md new file mode 100644 index 00000000000..c35c9a256b8 --- /dev/null +++ b/packages/core/docs/migrate/rc1.md @@ -0,0 +1,70 @@ +# Migration guide + +This guide contains a list of changes, in order to upgrade your VSF next to the RC.1 version. + +## The general overview + +In general, besides the smaller changes, we totally have changed the way of accessing configuration or API functions. +Always, instead of using configuration or networking stored in the global objects, we recommend to use context, provided by us. + +Each time you want to access an integration stuff, such as network client, configuration or API functions please use `useVSFContext` + +```js +import { useVSFContext } from '@vue-storefront/core'; + +export default { + setup () { + const { $integrationTag } = useVSFContext(); + } +} + +``` + +For more information, please read the section [Application Context](/general/context) in the general docs. + +## List of changes for certain users + +- [Changes for integrators](/migrate/integrators) +- [Changes for projects](/migrate/projects) + + +## Common problems + +### Composition API already installed + +``` +[vue-composition-api] already installed. Vue.use(VueCompositionAPI) should be called only once. +``` + +**Solution**: Please make sure that you have everywhere the same version of vue composition api as the one we use in the core + +### Using Composition API before is being installed + +``` +Uncaught Error: [vue-composition-api] must call Vue.use(plugin) before using any function. +``` +**Solution**: if you are using compositon API (eg. `ref`) above the component, please make sure that you have `vue-composition-api` installed, or move these calls inside of the `setup` function. + +### Some of our package doesn't work, the context doesn't return anything or has missing data + +**Solution**: Please make sure that you put package in the raw sources section, and if the integration has nuxt module and extend an existing one, should be aded before our core nuxt module and the one with integration + +```js +{ + ['@vue-storefront/some-new-integration/nuxt', {}], // 2 + ['@vue-storefront/nuxt', { + coreDevelopment: true, + useRawSource: { + dev: [ + '@vue-storefront/core' + '@vue-storefront/other-package' // 1 + ], + prod: [ + '@vue-storefront/core', + '@vue-storefront/other-package' // 1 + ] + } + }], + ['@vue-storefront/some-integration/nuxt', {}] +} +```