diff --git a/packages/core/docs/.vuepress/components/IntegrationTile.vue b/packages/core/docs/.vuepress/components/IntegrationTile.vue index f5b38efd433..e1f236fc85a 100644 --- a/packages/core/docs/.vuepress/components/IntegrationTile.vue +++ b/packages/core/docs/.vuepress/components/IntegrationTile.vue @@ -3,7 +3,7 @@
Enterprise - In prorgess + In progress Beta From Core Team
diff --git a/packages/core/docs/.vuepress/config.js b/packages/core/docs/.vuepress/config.js index d67e11f069f..9cf2f7c7e6b 100644 --- a/packages/core/docs/.vuepress/config.js +++ b/packages/core/docs/.vuepress/config.js @@ -23,7 +23,6 @@ module.exports = { themeConfig: { logo: 'https://camo.githubusercontent.com/48c886ac0703e3a46bc0ec963e20f126337229fc/68747470733a2f2f643968687267346d6e767a6f772e636c6f756466726f6e742e6e65742f7777772e76756573746f726566726f6e742e696f2f32383062313964302d6c6f676f2d76735f3062793032633062793032633030303030302e6a7067', nav: [ - { text: 'Home', link: '/' }, { text: 'Demo', link: 'https://vsf-next-demo.storefrontcloud.io' }, { text: 'Integrations', link: '/integrations/' }, { text: 'Migration guide', link: '/migrate/' }, @@ -169,16 +168,17 @@ module.exports = { ], '/': [ { - title: 'In a nutshell', + title: 'Getting started', collapsable: false, children: [ - ['/general/getting-started', 'Getting started'], + ['/', 'Introduction'], + ['/general/installation', 'Installation'], ['/general/key-concepts', 'Key concepts'], ['/general/enterprise', 'Enterprise'] ] }, { - title: 'Guide [WIP]', + title: 'Guides', collapsable: false, children: [ ['/guide/theme', 'Theme'], @@ -192,7 +192,7 @@ module.exports = { ] }, { - title: 'Advanced [WIP]', + title: 'Advanced', collapsable: false, children: [ ['/advanced/architecture', 'Architecture'], @@ -206,7 +206,7 @@ module.exports = { ] }, { - title: 'Build integration', + title: 'Building integration', collapsable: true, children: [ ['/integrate/integration-guide', 'eCommerce'], diff --git a/packages/core/docs/README.md b/packages/core/docs/README.md index c7e9207d0e4..124047b3588 100644 --- a/packages/core/docs/README.md +++ b/packages/core/docs/README.md @@ -1,106 +1,97 @@ -# What is Vue Storefront? +# Introduction [[toc]] +## What is Vue Storefront? -_Vue Storefront_ is a ___platform-agnostic headless e-commerce PWA frontend framework___ that may work with __any__ backend that you are already using via its API regardless of the platform, be it e-commerce, CMS, ERP, PIM, or anything else. - - +_Vue Storefront_ is a ___platform-agnostic e-commerce PWA frontend framework___ that can work with any e-commerce backend API. Additionally, thanks to _low coupling and high cohesion_, it can connect to other services, giving you the freedom to work with the technologies you know and love, be it CMS, ERP, PIM, or anything else.
+That's a mouthful, so let's break it down: + - __platform-agnostic__ - we made it possible to work with any platform and service you already use, as long as it has an API like REST or GraphQL. + - __e-commerce__ - today's shops are much more than just products and carts. That's why we made it easy to integrate other types of services, such as helper service for ERP, versatile search features for PIM, portable checkout for 3rd party payment kiosk, and more. + - __PWA__ - it's the technology of the future, designed to give the best performance on any device, with native-like features to satisfy your customer's needs. + - __frontend framework__ - _Vue Storefront_ is a set of modular features, glued together using _interfaces_ and _factories_ and powered by [Nuxt.js](https://nuxtjs.org/). +## Problems Vue Storefront solves -We mean by - - __platform-agnostic__ : _Vue Storefront_ will work with any platform and service that you're using as long as it's exposing some kind of REST or GraphQL API. - - __headless__ : Your e-commerce platform as a whole system can be built on top of a set of different technologies. No mandatory combination for the platform is required. Manifestation of _low coupling and high cohesion_ is here and will stay with us until the end. - - __e-commerce__ : Essentially _Vue Storefront_ was born as the e-commerce framework. By the nature of headless and microservice, however, you might connect it to whatever you set it to, say, a helper service for ERP, or versatile search features for PIM, and portable checkout for 3rd party payment kiosk, and so on. Limit is your imagination. - - __PWA__ : _PWA_ is the thing of future, it is designed to give best performance even on laggy mobile devices with native-like features from the beginning in order to satisfy your customers who are curious, rich, and impatient. - - __framework__ : Even though _Vue Storefront_ is a set of atomic features, they should be guided as one by the conductor. We do so by gluing them through _interfaces_ and _factories_. We will dig this further later, but one thing to take away, they are quite flexible glues. - -## Problems Vue Storefront will solve for you - -The main purpose of any software is to solve problems. Vue Storefront is no different. We're doing our best to find common issues in eCommerce space (and in our software!) and find viable solutions to them. Below you can find just a few of the issues Vue Storefront will solve for you. +The main purpose of any software is to solve problems and Vue Storefront is no different. We're doing our best to find common issues in the eCommerce space and find viable and scalable solutions. Below you can find just a few. ### Long time to market Headless eCommerce frontends are complex and developing them can take a lot of time. -**Solution** With Vue Storefront you're getting a working headless frontend connected to eCommerce, CMS and other third-party services of your choice out of the box along with a hundreds of ready-to-use Vue Storefront and Nuxt modules for all common functionalities! Because of that you're saving hundreds (or even thousands) of working hours so you can focus more on details and polishing while leaving the heavy lifting to us! +**Solution** + +With Vue Storefront you're getting a performant frontend connected to headless e-commerce, CMS, and other third-party platforms of your choice, along with hundreds of ready-to-use Vue Storefront and Nuxt.js modules for all common functionalities. Thanks to them, you will save hundreds (or even thousands) of working hours, so you can focus on creating value for your product while leaving the heavy lifting to us! ### Slow, unresponsive online shop -No matter how great your products are slow and unresponsive shop will make your conversion significantly lower . **Some estimates say up to 1% users will leave your website for every 100ms delay in page load time.** +By some estimates, up to 1% of users will leave your website for every 100ms of delay in page load time. No matter how great your products are, a slow and unresponsive shop will make your conversion significantly lower. -**Solution** _Vue Storefront_ solves slow, unresponsive online shop problems as follows : +**Solution** -- The page load time is reduced significantly on average thanks to small bundle size, code splitting, lazy loading and a bunch of other web performance techniques that we used to make sure your shop will load as fast as possible. -- Pages that were already visited are cached so next time user enters them they will load instantly. -- Resources that might be needed in the future are precached so when the user clicks the link it loads immediately. -- When network connectivity is slow or temporarily lost you can stil browse the product catalog. In many cases its unnoticeable for the user. -- Majority of JavaScript code is hosted and executed on the server side so your users download only the code that drives the UI. Because of this the page renders much faster and is much lighter compared to traditional SPA. +We solved these issues by: +- using modern technologies for small bundle sizes and performance; +- using code splitting, lazy loading, and lazy hydration to load only what's needed at the moment; +- caching the resources, so the already visited pages are loaded instantly; +- preloading resources that might be needed in the future; +- hosting and executing as much as possible on the server, so the part served to the users is much lighter and faster compared to traditional SPA; -Not only page load time but also __responsiveness as a whole from the page is almost instant and seamless__ just as you would expect from a native app, if not better. +### Unwieldy architectural decisions +It can be incredibly hard to add or remove simple features when the code doesn't follow industry standard patterns and conventions. Even a simple bugfix or security update can be a very time-consuming task. -### Unwieldy architectural decisions +**Solution** -How painful was it when you had to meticulously fix tremendous amount of changes without patterns while you just want to add/remove a simple feature, or upgrade the framework as they claim security risk is at stake? +We are promoting good architectural decisions by providing an opinionated way of building eCommerce frontends based on years of experience. Whatever issues you could run into, we made sure that our modular and flexible architecture will handle them. -**Solution** Vue Storefront is promoting good architectural decisions by design. We're providing an opinionated way of building eCommerce frontends based on years of experience. Whatever troubles you could run into we made sure that our architecture and flexibility will got you covered. +### Painful or impossible migrations -### Painful migrations +It can be frustrating when the technology you choose turned out to not fit your business needs, be it feature- or cost-wise. It can be even worse if you can't change it at all or the cost outweighs the benefits. -How frustrated was it when you learned the other backend platform you didn't choose turned out better solution for your business, a lot better on many levels, but the cost of switching is even greater than the benefit of it you just learned? You were literally locked-in by tentative choices you made while you were naive. +**Solution** -**Solution** Vue Storefront is backend-agnostic which means all eCommerce backends are integrated on the frontend under common interfaces. All these technologies are completely different on the backend but they're very similar from the frontend perspective. We just made use of that fact and came up with abstractions that will make your migrations painless and almost instantaneous. +From the very beginning, Vue Storefront was designed to be backend-agnostic. This means that all eCommerce backends are integrated on the frontend under common interfaces and can be replaced without having to rewrite the frontend from scratch. Most technologies are completely different on the backend but are very similar from the frontend perspective, so we made abstractions that will make your migrations painless. -### Lack of platform-specific competences +### Lack of platform-specific competencies -So your Magento department is not doing very well but the commercetools one is growing like crazy? If only could you move developers from one department to another... +So your Magento department is not doing well, but the commercetools one is growing like crazy? If only you could move developers from one department to another... -**Solution** ...wait! With Vue Storefront you can! We have the same interfaces for all integrations of the same type (eCommerce, CMS, Loyalty etc) so once a developer learns Vue Storefront he/she can be confident with any tech stack that works with it. +**Solution** + +With Vue Storefront you can! We have common interfaces for all integrations of the same type (eCommerce, CMS, Loyalty, etc.), so once a developer learns Vue Storefront they can be confident with any tech stack that works with it. ### Lack of flexibility -Do you recall the frustration when implementing your dream design is not possible within your backend platform, adding a single modal window takes 2 days or adding some specific feature is just not possible with the framework you're using? +Do you recall the frustration when it wasn't possible to implement your dream design or feature within your backend platform, or adding a single modal window took few days? -**Solution** You will forget about these issues with Vue Storefront! For the best experience when it comes to maintaining the framework, we divided the system into the smallest chunks until it's not meaningful to do so. ___Technically all parts are wrapped in as individual `npm` packages so switching from one version to another should be as easy as any `npm` command.___ In short, it has been built on the firm ground of _Mircroservice_ architecture. Each of these packages is independent and optional so its up to you how much of the framework you want to utilize. Moreover **there are absolutely no limitations in terms of UI customization**. Your theme is just a regular Nuxt.js project which you can customize to any degree. +**Solution** -## eCommerce Integrations +You will forget about these issues with Vue Storefront! For the best experience, we divided the system into small and modular chunks. All parts are individual `npm` packages, so switching from one version to another should be as easy as any package installation. +Vue Storefront was built on the firm ground of _microservice_ architecture. Each of these packages is independent and optional, so you decide how much of the framework you want to utilize. Moreover **there are absolutely no limitations in terms of UI customization**. Your theme is just a regular Nuxt.js project, which you can customize to any degree. -_Vue Storefront_ is a frontend framework undoubtedly. It needs an e-commerce backend to fully function in its glory. -Here is the list of e-commerce platform integrations already out in the field. +## eCommerce Integrations -- Commercetools -- Magento 2 -- Shopware (as Shopware PWA) -- Shopify (Developers Preview) -- About You Cloud (Developers Preview) -- Salesforce Commerce Cloud (WIP) -- BigCommerce (WIP) +Vue Storefront is a frontend framework, so it needs an e-commerce backend. You can see the list of supported e-commerce platforms on the [integrations page](./integrations). -We will walk you with details of each integration in its dedicated guide. +## Tech stack -## Benefits you take -- Blazingly fast frontend -- Ability to work with any eCommerce platform, CMS, ERP, PIM **under common, agnostic API** -- Server Side Rendereing -- Progressive Web App features -- Unlimited flexibility in changing third-party services thanks to agnostic data formats +The speed and flexibility of Vue Storefront wouldn't be possible without the great technologies that power it: -## Tech stack - [Vue.js](https://vuejs.org/v2/guide/) - [Nuxt.js](https://nuxtjs.org/guide) -- SCSS +- [SCSS](https://sass-lang.com/) - [Storefront UI](https://www.storefrontui.io/) (optional) - [TypeScript](https://www.typescriptlang.org/docs/home) (optional) - +- [Cypress](https://www.cypress.io/) (optional) ## What's next? -If you're already convinced to use Vue Storefront check the [installation guide](./general/getting-started.html). -If you want to learn more check the [key concepts](./general/key-concepts.html) behind Vue Storefront to understand how it works. +If you're already convinced to use Vue Storefront, check the [Installation guide](./general/installation.html). + +If you want to learn more, check the [Key concepts](./general/key-concepts.html) behind Vue Storefront. diff --git a/packages/core/docs/commercetools/composables/use-facet.md b/packages/core/docs/commercetools/composables/use-facet.md index 5efbe6382fa..3f52bf78e55 100644 --- a/packages/core/docs/commercetools/composables/use-facet.md +++ b/packages/core/docs/commercetools/composables/use-facet.md @@ -169,25 +169,62 @@ type ProductVariant = { ## Configuration -::: warning -Configuration can be changed only for th Enterprise version of this package. +::: tip +Configuration can be changed only for the Enterprise version of this package. ::: -Faceting configuration can be modified to change available sorting options, filters, etc. +Faceting configuration can be modified to change available sorting options, filters, etc. It must be passed to: +- `@vsf-enterprise/ct-faceting/nuxt` module in `nuxt.config.js`. +- `@vsf-enterprise/ct-faceting/server` integration in `middleware.config.js`. -If the explicit configuration is not provided, the following defaults will be used: +::: warning Keep your configuration synchronized +Parts of the configuration marked as `` must be identical in both files. +::: + +```javascript +// nuxt.config.js +export default { + buildModules: [ + ['@vsf-enterprise/ct-faceting/nuxt', { + // + }], + ] +}; + +// middleware.config.js +module.exports = { + integrations: { + ctf: { + location: '@vsf-enterprise/ct-faceting/server', + configuration: { + api: { + authHost: "", + projectKey: "", + clientId: "", + clientSecret: "", + scopes: [ + "" + ], + }, + faceting: { + host: "" + }, + // + } + } + } +}; +``` + +If the explicit configuration is not provided in place of ``, the following defaults will be used: ```javascript { - pageOptions: [ - 20, - 50, - 100 - ], + pageOptions: [20, 50, 100], subcategoriesLimit: 100, availableFacets: [ - { facet: 'categories.id', type: 'string', option: 'subtree("*")', name: 'category' }, - { facet: 'variants.attributes.size', type: 'number', option: '', name: 'size' }, + { facet: 'categories.id', type: 'string', option: 'subtree("*")', name: 'category', filteringStrategy: 'query' }, // Don't change the "name" of this facet + { facet: 'variants.attributes.size', type: 'string', option: '', name: 'size' }, { facet: 'variants.attributes.color.key', type: 'string', option: '', name: 'color' } ], sortingOptions: [ @@ -200,9 +237,20 @@ If the explicit configuration is not provided, the following defaults will be us } ``` -Configuration can be modified by passing identical configuration to: -- `@vsf-enterprise/ct-faceting/nuxt` module in `nuxt.config.js`. -- `@vsf-enterprise/ct-faceting/server` integration in `middleware.config.js`. +- `pageOptions` - an array of number of elements displayed per page. +- `subcategoriesLimit` - the maximum number of subcategories displayed for any given category. +- `availableFacets` - an array of filters available to the user. + - `facet` - facet expressions described on [this page](https://docs.commercetools.com/api/projects/products-search#termfacetexpression). + - `type` - `facet` data type. Valid values are `string`, `date`, `time`, `datetime`, `boolean` or `number`. + - `option` - filtering options described on [this page](https://docs.commercetools.com/api/projects/products-search#filters). + - `name` - facet alias described on [this page](https://docs.commercetools.com/api/projects/products-search#alias). `category` alias for the first facet shown above is a constant and shouldn't be changed. + - `filteringStrategy` - scope applied to this specific filter. Possible values are `filter`, `query` or `facets`. For more information refer to [this page](https://docs.commercetools.com/api/projects/products-search#filters). +- `sortingOptions` - an array of sorting options available to the user. + - `id` - unique `identifier` for the option. + - `name` - label for the option. + - `facet` - the name of the field to sort by. For more information refer to [this page](https://docs.commercetools.com/api/projects/products-search#sorting). + - `direction` - sorting direction. Valid values are `asc` or `desc`. +- `filteringStrategy` - fallback scope applied to the facets that don't have strategy defined. Possible values are `filter`, `query` or `facets`. For more information refer to [this page](https://docs.commercetools.com/api/projects/products-search#filters). ## Example diff --git a/packages/core/docs/core/api-client.md b/packages/core/docs/core/api-client.md deleted file mode 100644 index 22cec517212..00000000000 --- a/packages/core/docs/core/api-client.md +++ /dev/null @@ -1,20 +0,0 @@ -# API Client - -[[toc]] - ----- -::: tip Installation -If you want to learn how to install the API Client check our [Getting Started guide](/getting-started.html) -::: - -API Client is a data layer of your eCommerce integration. It provides a friendly abstraction layer over network calls to your eCommerce platform. - -It expresses each network request as a declarative method like `getProduct` or `getCategory`. By having this additional layer we can hide implementation details of **how** we get the data which gives you freedom of introducing major changes in this layer without influencing other parts of the app. - -API Client by itself is a Vanilla JavaScript application and it doesn't require any frontend framework to run. It's usually not used directly in the UI and is responsible only for providing data to Composition Functions. - -## Configuration -::: danger storing credentials - **Never** pass fragile data like API Client secrets as plain strings. -::: - diff --git a/packages/core/docs/general/enterprise.md b/packages/core/docs/general/enterprise.md index dc5345e696c..7c27912b45e 100644 --- a/packages/core/docs/general/enterprise.md +++ b/packages/core/docs/general/enterprise.md @@ -1,30 +1,31 @@ # What is Vue Storefront Enterprise -Vue Storefront Enterprise is a commercial offering from Vue Storefront core team built on top of the Open Source product. Our goal is to give you all the tools that you could need to launch your Vue Storefront shop and provide you with ready-to-use integrations that will drastically speed up your development process. +> Vue Storefront Enterprise is currently available only for commercetools -- Vue Storefront Cloud -- Integrations with third-parties -- Extended integration with Commercetools +Vue Storefront Enterprise is a commercial offering from the Vue Storefront core team built on top of the Open Source product. Its goal is to give you all the tools you need to launch your shop and provide you with ready-to-use integrations that will reduce the development time and cost of your project. -You can learn more about our commercial offering [here](https://www.vuestorefront.io/enterprise). +## What are the differences between Open Source and Enterprise versions? -This document will walk you through the installation and usage of the latter part. +In Enterprise Edition you're getting everything that's in our Open Source. On top of that we also provide: -# How to use Vue Storefront Enterprise +- access to [Vue Storefront Cloud](https://www.vuestorefront.io/cloud); +- additional integrations with third-party services; +- extended integration with eCommerce platform with advanced features. -Vue Storefront Enterprise packages are part of our private npm registry. +Everything with badge in the documentation is only available for our Enterprise customers. -To make use of it create a `.npmrc` file in the root of your project with the following content: +You can learn more about our commercial offering on the [Enterprise](https://www.vuestorefront.io/enterprise) page. + +## How to use Vue Storefront Enterprise + +Enterprise packages within `@vsf-enterprise` scope are part of our private registry. To make use of them, create a `.npmrc` file in the root of your project with the following content: ``` @vsf-enterprise:registry=https://registrynpm.storefrontcloud.io ``` -Then log into your account on Vue Storefront registry: +Then log into your account with your Vue Storefront Enterprise credentials: + ```bash npm adduser --registry https://registrynpm.storefrontcloud.io ``` - -From there you will use Vue Storefront registry for all packages within `@vsf-enterprise` scope. Other ones will be proxied to NPM. - - diff --git a/packages/core/docs/general/getting-started.md b/packages/core/docs/general/installation.md similarity index 97% rename from packages/core/docs/general/getting-started.md rename to packages/core/docs/general/installation.md index b4093c02a4f..426219c8d4e 100644 --- a/packages/core/docs/general/getting-started.md +++ b/packages/core/docs/general/installation.md @@ -1,4 +1,6 @@ -# Getting started +# Installation + +## Using CLI If you want to get started with Vue Storefront, the easiest way to do this is to set up your project through our CLI tool. It can be installed globally through NPM: diff --git a/packages/core/docs/general/key-concepts.md b/packages/core/docs/general/key-concepts.md index 40ab2d5f1f9..a6d9b057db0 100644 --- a/packages/core/docs/general/key-concepts.md +++ b/packages/core/docs/general/key-concepts.md @@ -1,64 +1,136 @@ -# Key Concepts +# Key concepts -This document will walk you through the most important concepts of Vue Storefront. Once you'll grab the ideas behind the software it should be fairly straightforward for you to use it in the right way. +This document will walk you through the most important concepts of Vue Storefront, help you understand the ideas behind it and how to use them in the right way. ## Configuration -The first thing you usually want to do after setting up a new project is some configuration. No matter if you want to change your backend API credentials, change routes or add a custom logger, there is always a single place to do all these things - Vue Storefront Modules configuration in `nuxt.config.js`. +There are two types of configuration in Vue Storefront: -If you're using our boilerplate, you will find 3 Vue Storefront modules in your configuration: +- `nuxt.config.js` to control your Nuxt App and frontend-related features of Vue Storefront; +- `middleware.config.js` to add, configure and extend your integrations; -- `@vue-storefront/nuxt` - Our core Nuxt module. Its main responsibility is to extend Nuxt configuration. -- `@vue-storefront/nuxt-theme`- This module adds routing and theme-specific configuration for Nuxt. -- `@vue-storefront/` - This is a module of your eCommerce integration. All configuration related to the specific eCommerce platform like setting up API credentials has to happen through this module. Such module usually provides some additional functionalities like setting up the cookies. - -You can read more about configuration [here](/guide/configuration.html) +You can read more about it on the [Configuration](/guide/configuration.html) page. ## Composables ::: tip Composables? Is this a French meal? -Composable is a function that uses [Vue.js Composition API](https://v3.vuejs.org/guide/composition-api-introduction.html) under the hood. It's commonly named with a `use` prefix (eg. `useProduct`, `useCart`). This convention comes from the React community where we can find a very similar pattern - [Hooks](https://reactjs.org/docs/hooks-intro.html), which inspired Vue.js core team to introduce the Composition API. If you are not familiar with this concept, we strongly recommend checking the basics of it [here](https://v3.vuejs.org/guide/composition-api-introduction.html) +Composable is a function that uses [Vue.js Composition API](https://v3.vuejs.org/guide/composition-api-introduction.html) under the hood. It's commonly named with a `use` prefix (eg. `useProduct`, `useCart`). This convention comes from the React community which has a similar pattern called [Hooks](https://reactjs.org/docs/hooks-intro.html), which inspired Vue.js core team to introduce the Composition API. If you are not familiar with this concept, we strongly recommend checking the basics in the official [Vue.js documentation](https://v3.vuejs.org/guide/composition-api-introduction.html). ::: **Composables are the main public API of Vue Storefront** and in many cases the only API except configuration you'll work with. -You can treat each composable as an independent micro-application. They manage their own state, handle SSR and in most cases don't interact with each other (`useUser` and `useCart` are exceptions). +You can treat each composable as an independent micro-application. They manage their state, handle SSR and in most cases don't interact with each other (`useUser` and `useCart` are the exceptions). ```js const { search, product, loading, error } = useProduct(); ``` -You can read more about Vue Storefront composables [here](/guide/composables.html) + +You can read more about them on the [Composables](/guide/composables.html) page. ## Routing -Routes are injected via `@vue-storefront/nuxt-theme` module. Use [extendRoutes](https://nuxtjs.org/guides/configuration-glossary/configuration-router#extendroutes) from `nuxt.config.js` to modify them. +Out of the box, some routes are injected via `@vue-storefront/nuxt-theme` module: + +- Home Page (`/`); +- Category Page (`/c/:slug_1/:slug_2?/:slug_3?/:slug_4?/:slug_5?`); +- Product Page (`/p/:id/:slug/`); +- User Profile Page (`/my-account/:pageName?`); +- Checkout (`/checkout`): + - Shipping (`/checkout/shipping`); + - Billing (`/checkout/billing`); + - Payment (`/checkout/payment`); + - Thank You page (`/checkout/thank-you`); +- Custom 404 page; + +Some [integrations](/integrations) may register additional routes. For example, CMS integrations often override Home Page and add custom, dynamic pages. + +To override existing routes or adding your own, use [extendRoutes](https://nuxtjs.org/guides/configuration-glossary/configuration-router#extendroutes) in `nuxt.config.js`. Additionally, Nuxt.js automatically registers components created in the `pages` folder as new routes. You can read more about this on the [File System Routing](https://nuxtjs.org/docs/2.x/features/file-system-routing/) page. ## Internationalization -By default, we're using `nuxt-i18n` module for internationalization. +By default, Vue Storefront uses `nuxt-i18n` module for internationalization. + +You can read more about it on the [Internationalization](/advanced/internationalization) page. -You can read more about i18n in Vue Storefront [here](/advanced/internationalization). +## Server Middleware -## App Context +Vue Storefront uses middleware as a bridge between the frontend and the backends (eCommerce or 3rd party services). The frontend always calls middleware that forwards requests to corresponding destinations. It allows developers to implement custom logic, inject into the lifecycle of the requests or even create custom API endpoints if needed. -Sometimes the only thing you need is to fetch some data from integrations API Client without the overlap of a composable. You should use an API Client that is accessible through `useVSFContext` composable for that. +Middleware by default is a part of your Nuxt application, but it can be detached and used as a separate node application. + +You can read more about Vue Storefront Middleware on the [Server Middleware](/advanced/server-middleware) page. + +## Integrations and extendibility + +All 3rd party integrations (eCommerce, CMS, Search, etc.) can be added and configured in `middleware.config.js`: ```js -import { useVSFContext } from '@vue-storefront/core' -// for each integration you can access it's tag - eg $ct for commercetools -const { $ct } = useVSFContext() +//middleware.config.js +module.exports = { + integrations: { + // ... + } +} ``` -You can read more about Vue Storefront Context [here](/advanced/context) +Each integration has an `extensions` field. You can use extensions to: +- override existing API methods of a certain integration; +- add new API methods; +- change method parameters before they are called; +- react to a method being called; +```js +{ + name: 'my-extension', + extendApiMethods: { + // will override default getProduct + getProduct: async () => { /* ... */ } + // will add new method to the integration + doSomethingMore: async () => { /* ... */} + }, + hooks: (req, res) => { + return { + beforeCreate: ({ configuration }) => configuration, + afterCreate: ({ configuration }) => configuration, + beforeCall: ({ configuration, callName, args }) => args, + afterCall: ({ configuration, callName, args, response }) => response + } + } +} +``` -## Middleware +Sometimes you just need to call a specific API client method without using a composable. Luckily you have access to all API methods of the registered integrations through `useVSFContext` composable. -When it comes to the networking layer, Vue Storefront uses a middleware that is a bridge between front-end and other backends (eCommerce or 3rd party services). The front-end always calls middleware that is redirecting requests to correlated destinations. It allows developers to implement custom logic to inject into the lifecycle of the requests or even create custom API endpoints if needed. +The composable returns a list of tags representing your integrations (it's usually either a name of the integration like `$storyblok` or an acronym for longer names like `$ct` for commercetools). -You can read more about Vue Storefront Middleware on the [Server Middleware](/advanced/server-middleware) page. +```js +const { $ct } = useVsfContext() +``` +You have access to all methods through the `api` field of each integration -## Integrations +```js +const products = $ct.api.getProducts(params) +``` + +## Backend-agnostic + +Whatever backend services you're using, they are handled more or less the same way on the frontend. No matter what eCommerce platform, CMS, or search platform you're using, you will always use the same getters and composables. This makes it easy to work with VSF projects on different tech stacks or try new services without making heavy investments. + +Some things are different for each platform though. The main data object of each composable (like `products` in `useProduct`) is **always** a plain response from your platform. If you use getters on this object they will always return agnostic data format + +```js +const { search, products } = useProduct() -Even though high-level APIs are the same for all Vue Storefront integrations, they are different on the low level (data formats, search params). Check the documentation for a specific platform to learn more. +console.log(products) // type: CommerceToolsProduct[] + +console.log(productGetters.getAttributes(products.value)) // type: AgnosticProductAttribute[] +``` + +Parameters of functions returned by composables are different for each platform + +```js +const { search, products } = useProduct() + +search(params) // `params` are different depending on backend platform +``` diff --git a/packages/core/docs/guide/checkout.md b/packages/core/docs/guide/checkout.md index b481f2dda7d..f3ea394f761 100644 --- a/packages/core/docs/guide/checkout.md +++ b/packages/core/docs/guide/checkout.md @@ -342,9 +342,9 @@ You can pass asynchronous functions to the `VsfPaymentProvider` component to hoo Because every payment provider is different, not all of them are present in every integration. Always refer to the documentation of a specific provider to learn which hooks are available. - **beforeLoad** `(config => config)` - Called before loading payment methods. -- **afterLoad** `(shippingMethodsResponse => shippingMethodsResponse.shippingMethods)` - Called after loading payment methods. -- **beforeSelect** `(shippingMethod => shippingMethod)` - Called before selecting payment method. -- **afterSelect** `(selectedShippingMethod => void)` - Called after selecting payment method. +- **afterLoad** `(paymentMethodsResponse => paymentMethodsResponse.paymentMethods)` - Called after loading payment methods. +- **beforeSelect** `(paymentMethod => paymentMethod)` - Called before selecting payment method. +- **afterSelect** `(selectedPaymentMethod => void)` - Called after selecting payment method. - **beforePay** `(paymentDetails => paymentDetails)` - Called before pay. - **afterPay** `(paymentResponse => void)` - Called after pay. - **beforeSelectedDetailsChange** `(details => details)` - Called before modifying currently picked payment method, e.g. changing credit card's details. diff --git a/packages/core/docs/guide/composables.md b/packages/core/docs/guide/composables.md index 681efa96a98..3cf9f21b978 100644 --- a/packages/core/docs/guide/composables.md +++ b/packages/core/docs/guide/composables.md @@ -294,9 +294,9 @@ Vue Storefront integrations are exposing the following composables: #### Checkout - `useShipping` - Saving the shipping address for a current order. -- `useShippingProvider` - Choosing a shipping method for a current order. +- `useShippingProvider` - Choosing a shipping method for a current order. Shares data with `VsfShippingProvider` component. - `useBilling` - Saving the billing address for a current order. -- `usePaymentProvider` - Choosing a payment method for a current order. +- `usePaymentProvider` - Choosing a payment method for a current order. Shares data with `VsfPaymentProvider` component - `useMakeOrder` - Placing the order. #### Other diff --git a/packages/core/docs/guide/configuration.md b/packages/core/docs/guide/configuration.md index a20dd9a976a..f26d16b2ba5 100644 --- a/packages/core/docs/guide/configuration.md +++ b/packages/core/docs/guide/configuration.md @@ -31,14 +31,6 @@ Sometimes integrations also expose a Nuxt module to configure frontend-related p }] ``` -Below you can find links to the setup instructions and config references of the official eCommerce integrations: - - - - ## Configuring Nuxt We try to use the most common modules from Nuxt Community whenever it's possible. For internationalization we are using `nuxt-i18n`, for PWA capabilities `@nuxtjs/pwa` etc. You can find a list of the Nuxt modules used in the default theme [here](theme.html#preinstalled-modules-and-libraries). Each of them is configured in a way that works best for the majority of users. @@ -85,10 +77,21 @@ It's unsafe and not recommended to remove `@vue-storefront/nuxt` from your proje ## Configuring Middleware +There are certain things related to Integration Middleware that are not tied to any specific integration like setting custom GraphQL queries you can configure. You can read more about the Middleware and its configuration [here](/v2/advanced/server-middleware). + +## Integration References + + +### Setting up official eCommerce integrations + -There are certain things related to Integration Middleware that are not tied to any specific integration like setting custom GraphQL queries you can configure. You can read more about the Middleware and its configuration [here](/v2/advanced/server-middleware). +### Configuration references of official eCommerce integrations + \ No newline at end of file diff --git a/packages/core/docs/guide/theme.md b/packages/core/docs/guide/theme.md index 8a3da1f7bf4..c471ee17cbc 100644 --- a/packages/core/docs/guide/theme.md +++ b/packages/core/docs/guide/theme.md @@ -1,77 +1,40 @@ # Theme -If you [use our CLI to set up your project](./general/getting-started) you will end up with a fully functional eCommerce theme connected to your eCommerce backend and a bunch of other services based on [Nuxt.js](https://nuxtjs.org/) - -## High-level overview - -Your theme out of the box will have following features: - -**Pages** - -- Home Page -- Product Listing Page -- Product Details Page -- Mini Cart -- Mini Wishlist -- User Authentication -- User Profile -- Checkout -- Custom 404 page - -**Integrations** +## Directory structure -- eCommerce full scope / eCommerce basic scope -- CMS integration - - Home Page - - Custom CMS Page - - Header - - Footer -- Payment integration +If you followed our [Installation guide](/general/installation), you should have a fully functional e-commerce application. As mentioned in previous documents, Vue Storefront is based on Nuxt.js, so the structure of both applications is similar. Most directories come from Nuxt.js and you can read more about them on their [Directory Structure](https://nuxtjs.org/docs/2.x/get-started/directory-structure) page. -**Other** +* [.nuxt](https://nuxtjs.org/docs/2.x/directory-structure/nuxt); +* [components](https://nuxtjs.org/docs/2.x/directory-structure/components); +* `composables` - contains custom composables that override your integration or are not part of the Vue Storefront core. It may include composables specific to your theme; +* `helpers` - contains helper functions. This is a good place to store methods used in the multiples places of the application; +* `lang` - contains translations for your application. Available locales are configured in the `nuxt.config.js` file; +* [layouts](https://nuxtjs.org/docs/2.x/directory-structure/layouts); +* [middleware](https://nuxtjs.org/docs/2.x/directory-structure/middleware); +* [pages](https://nuxtjs.org/docs/2.x/directory-structure/pages); +* [static](https://nuxtjs.org/docs/2.x/directory-structure/static); +* `middleware.config.js` - configuration file for the [Server Middleware](/advanced/server-middleware); +* [nuxt.config.js](https://nuxtjs.org/docs/2.x/directory-structure/nuxt-config); -- Progressive Web App features -- internationalization +## Storefront UI -A full list of features (for Enterprise version) can be found [here](/enterprise/feature-list.html). + -## Directory structure +Almost every component in our default theme contains other components whose names start with `Sf`. These come from [Storefront UI](http://storefrontui.io/) - a design system and library of Vue.js components dedicated to e-commerce, maintained by the Vue Storefront core team. The library is fully customizable, so it can be used in different contexts and with different designs. -If you're familiar with Nuxt.js, you will quickly notice that the directory structure is almost identical to the standard Nuxt.js project. Since you can read about the Nuxt project folder structure in [Nuxt docs](https://nuxtjs.org/docs/2.x/get-started/directory-structure), we will cover mostly the directories specific to Vue Storefront. - -```js -. -├─ components/ -├─ composables/ // place for custom composition API functions -│ └─ useUiHelpers/ // theme-specific composition API functions -├─ helpers/ // utility functions -│ ├─ category/ // getting category search params to/from url -│ └─ filters/ // getting filters to/from url -├─ lang/ // i18n translation keys -├─ layouts/ -├─ middleware/ -│ └─ checkout.js // prevents users from entering checkout steps if certain information is missing -├─ pages/ -├─ static/ -└─ nuxt.config.js -``` +With Storefront UI you're getting [Vue.js components](<(https://storybook.storefrontui.io/)>), [Figma designs](figma.com/file/N0Ct95cSAoODNv7zYS01ng/Storefront-UI-%7C-Design-System?node-id=0%3A1) and [Storybook](https://storybook.storefrontui.io/) to test them. The library works great for the multi-tenancy model as a shared UI library that can be customized differently for each tenant. -## Storefront UI +To learn more about Storefront UI please check its [Documentation](https://docs.storefrontui.io/). ::: tip Want to use another UI library? No problem! -If you don't want to use Storefront UI feel free to remove it from your project - it's just a UI layer and the project can work with any other UI library or a custom code. +If you don't want to use Storefront UI feel free to remove it from your project. It's just a UI layer and the project can work with any other UI library or a custom code. ::: -Our default theme is based on [Storefront UI](http://storefrontui.io/) - a design system and library of Vue.js components dedicated to eCommerce maintained by Vue Storefront core team. The library is fully customizable on multiple levels to make sure that it can be used in different contexts and with different designs. - - - -With Storefront UI you're getting both [Vue.js components](<(https://storybook.storefrontui.io/)>) and [Figma designs](figma.com/file/N0Ct95cSAoODNv7zYS01ng/Storefront-UI-%7C-Design-System?node-id=0%3A1) that match them so it's straightforward for your design team to customize them. The library works great for the multi-tenancy model as a shared UI library that can be customized differently for each tenant. - -To learn more about Storefront UI please check: +## Custoziming the theme -- [Storybook](https://storybook.storefrontui.io/) where you can find a list of all it's available components -- [Documentation](https://docs.storefrontui.io/) where you can find the information about customization possibilities and setup +TODO: +* Vue devtools +* styles (and preventing duplicates) ## Preinstalled modules and libraries @@ -81,16 +44,18 @@ Below you can find a list of the most important Nuxt Modules and libraries that ### Nuxt Modules -- `@nuxtjs/pwa` -- `nuxt-i18n` -- `@vue-storefront/nuxt` - - `@nuxtjs/composition-api` - - `@nuxt/typescript-build` - - `@nuxtjs/style-resources` - - `nuxt-purgecss` -- `@vue-storefront/nuxt-theme` +- `@nuxtjs/pwa`; +- `nuxt-i18n`; +- `@vue-storefront/nuxt`; + - `@nuxtjs/composition-api`; + - `@nuxt/typescript-build`; + - `@nuxtjs/style-resources`; + - `nuxt-purgecss`; +- `@vue-storefront/nuxt-theme`; + - `vue-lazy-hydration`; ### Libraries -- [`@storefront-ui/vue`](https://storefrontui.io) -- [`wee-validate`](https://vee-validate.logaretm.com/v3) +- [`@storefront-ui/vue`](https://storefrontui.io); +- [`wee-validate`](https://vee-validate.logaretm.com/v3); +- [`lodash`](https://lodash.com/); diff --git a/packages/core/docs/guide/user-profile.md b/packages/core/docs/guide/user-profile.md index 73c53a83850..df946f1df10 100644 --- a/packages/core/docs/guide/user-profile.md +++ b/packages/core/docs/guide/user-profile.md @@ -265,7 +265,7 @@ export default { ] } ``` -## Integration references +## Integration References ### `useUser`