diff --git a/packages/commercetools/theme/package.json b/packages/commercetools/theme/package.json index f121317dcf9..5cba85f35a6 100644 --- a/packages/commercetools/theme/package.json +++ b/packages/commercetools/theme/package.json @@ -16,7 +16,6 @@ }, "dependencies": { "@nuxtjs/pwa": "^3.2.2", - "@nuxtjs/style-resources": "^1.0.0", "@storefront-ui/vue": "0.9.2", "@vue-storefront/commercetools": "^1.0.1-rc.1", "@vue-storefront/nuxt": "^2.1.1-rc.1", @@ -30,7 +29,6 @@ }, "devDependencies": { "@nuxt/types": "^0.7.9", - "@nuxt/typescript-build": "^2.0.0", "@vue/test-utils": "^1.0.0-beta.27", "babel-jest": "^24.1.0", "jest": "^24.1.0", diff --git a/packages/core/docs/.vuepress/config.js b/packages/core/docs/.vuepress/config.js index afb911925fc..9c9af35faaa 100644 --- a/packages/core/docs/.vuepress/config.js +++ b/packages/core/docs/.vuepress/config.js @@ -126,18 +126,32 @@ module.exports = { ], '/': [ { - title: 'General', + title: 'In a nutshell', collapsable: false, children: [ ['/general/getting-started', 'Getting started'], ['/general/key-concepts', 'Key concepts'], + ] + }, + { + title: 'General', + collapsable: false, + children: [ ['/general/architecture', 'Architecture'], - ['/general/i18n', 'i18n'], ['/general/logging', 'Logging'], ['/general/performance', 'Performance'], ['/general/context', 'Application Context'] ] - }, + }, + { + title: 'Guide [WIP]', + collapsable: false, + children: [ + ['/guide/theme', 'Theme'], + ['/guide/internationalization', 'Internationalization'], + + ] + }, { title: 'Composables', collapsable: false, @@ -184,7 +198,6 @@ module.exports = { ['/contributing/themes', 'Working with themes'], ['/contributing/server-side-rendering', 'Server-side rendering'], ['/contributing/changelog', 'Core Changelog'], - ['/contributing/migration-to-2', 'Migration from X to 2'] ] }, ], diff --git a/packages/core/docs/README.md b/packages/core/docs/README.md index c9eb6747fc9..1a684d10b7c 100644 --- a/packages/core/docs/README.md +++ b/packages/core/docs/README.md @@ -1,5 +1,7 @@ # What is Vue Storefront? +[[toc]] + _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. @@ -18,14 +20,16 @@ We mean by - __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. -Give me 7 minutes and you will grab : - -[[toc]] - ## 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. +### 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 polishments 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.** @@ -36,6 +40,7 @@ No matter how great your products are slow and unresponsive shop will make your - 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 are downloading only the code that drives the UI. Because of this the page renders much faster and is much lighter 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. @@ -50,7 +55,7 @@ How painful was it when you had to meticulously fix tremendous amount of changes 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** 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 frotnend perspective. We just made use of that fact and came up with abstractians that will make your migrations painless and almost instantaneous. +**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 frotnend perspective. We just made use of that fact and came up with abstractions that will make your migrations painless and almost instantaneous. ### Lack of platform-specific competences @@ -65,32 +70,14 @@ Do you recall the frustration when implementing your dream design is not possibl **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. - - ## eCommerce Integrations _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. - Commercetools +- Magento 2 +- Shopware (as Shopware PWA) - Shopify (Developers Preview) - About You Cloud (Developers Preview) - Salesforce Commerce Cloud (WIP) @@ -103,7 +90,7 @@ We will walk you with details of each integration in its dedicated guide. - Ability to work with any eCommerce platform, CMS, ERP, PIM **under common, agnostic API** - Server Side Rendereing - Progressive Web App features -- Huge flexibility in changing third-party services thanks to agnostic data formats +- Limitless flexibility in changing third-party services thanks to agnostic data formats ## Tech stack - [Vue.js](https://vuejs.org/v2/guide/) @@ -111,3 +98,9 @@ We will walk you with details of each integration in its dedicated guide. - SCSS - [Storefront UI](https://www.storefrontui.io/) (optional) - [TypeScript](https://www.typescriptlang.org/docs/home) (optional) + + +## What's next? + +If you're already convinced to use Vue Storefront check the [installation guide](./general/getting-started). +If you want to learn more check the [key concepts](./general/key-concepts) behind Vue Storefront to understand how it works. diff --git a/packages/core/docs/commercetools/README.md b/packages/core/docs/commercetools/README.md index 0b0a2e0d309..2f1603e0b01 100644 --- a/packages/core/docs/commercetools/README.md +++ b/packages/core/docs/commercetools/README.md @@ -2,4 +2,6 @@ This is a documentation for Vue Storefront integration with Commercetools. -This integration is currently a **work in progress** and not ready for production usage. \ No newline at end of file +This Open Source integration is currently a **work in progress** and not ready for production usage. + +If you'd like to use Vue Storefront in production we suggest using the Enterprise version that is production-ready and supported by the core team. [Contact us](https://www.vuestorefront.io/contact/sales) to learn more \ No newline at end of file diff --git a/packages/core/docs/composables/use-content.md b/packages/core/docs/composables/use-content.md index 3e484747cd3..42e6518f3d7 100644 --- a/packages/core/docs/composables/use-content.md +++ b/packages/core/docs/composables/use-content.md @@ -2,7 +2,8 @@ `useContent` is typically a composable used for a CMS integration and is user together with `` component. -You can use them to +## When to use it? + - fetch a single CMS content entity or a list - render Vue Components from your project based on the fetched content diff --git a/packages/core/docs/general/getting-started.md b/packages/core/docs/general/getting-started.md index 46a2d122c89..37849320f6d 100644 --- a/packages/core/docs/general/getting-started.md +++ b/packages/core/docs/general/getting-started.md @@ -4,9 +4,21 @@ If you want to get started with Vue Storefront the easiest way to do this is to To make use of Vue Storefront CLI simply install it globally through NPM: + + + + +```bash +yarn global add @vue-storefront/cli@next +``` + + + ```bash npm i -g @vue-storefront/cli@next ``` + + Once installed you can use the CLI to set up the project with: diff --git a/packages/core/docs/general/i18n.md b/packages/core/docs/general/i18n.md deleted file mode 100644 index 09540221e98..00000000000 --- a/packages/core/docs/general/i18n.md +++ /dev/null @@ -1,51 +0,0 @@ -# Internationalization - -By default we are using `nuxt-i18n` module for handling internationalization, but it's not mandatory to use it even if you are using nuxt. - -In order to provide unify way of configure i18n across the application, we have introduced field `i18n` in the nuxt.config.js file that has same format as `nuxt-i18n` options. Clearly, it's possible to add there any configuration if there is a necessity. - - -## Integration modules - -Other modules such as integration ones, will consume this section as the single source of truth for i18n. -Additionally to tell the modules to use that section we always should set `useNuxtI18nModule` to true under the `i18n` key. - -```js -['@vue-storefront/commercetools/nuxt', { - api: { - uri: 'https://yourshop.com/some-key/graphql', - }, - i18n: { - useNuxtI18nModule: true - } -}] -``` - -## Custom configuration -In case when you set this flag to false, you are always able to provide your own i18n configuration just for this module. - -```js -['@vue-storefront/commercetools/nuxt', { - api: { - uri: 'https://yourshop.com/some-key/graphql', - }, - i18n: { - useNuxtI18nModule: false, - locales: [ - { - code: 'en', - label: 'English', - file: 'en.js', - iso: 'en' - }, - { - code: 'de', - label: 'German', - file: 'de.js', - iso: 'de' - } - ], - defaultLocale: 'en' - } -}] -``` diff --git a/packages/core/docs/general/key-concepts.md b/packages/core/docs/general/key-concepts.md index bdabc25767c..e37000c5804 100644 --- a/packages/core/docs/general/key-concepts.md +++ b/packages/core/docs/general/key-concepts.md @@ -27,34 +27,37 @@ const { search, product, loading, error } = useProduct() Vue Storefront integrations are exposing following composables: -```js -// product catalog -useProduct() -useCategory() -useFacet() -useReview() - -// user profile and authorization -useUser() -useUserShipping() -useUserBilling() -useUserOrders() -useInventory() // WIP - -// shopping cart -useCart() - -// wishlist/favourite -useWishlist() - -// CMS content -useContent() // usually external CMS - -// checkout forms and placing orders -useCheckout() -``` -In a real-world application these composables will most likely use different backend services under the hood yet still leverage the same frontend API. For instance within the same application `useProduct` and `useCategory` could use `commercetools`, `useCart` some ERP system, `usefacet` - Algolia etc. +#### Product Catalog + +- [useProduct](/composables/use-product) for managing a single product with variants (or a list) +- [useCategory](/composables/use-category) for managing category lists (but not category products) +- [useFacet](/composables/use-facet) for complex catalog search with filtering +- [useReview](/composables/use-review) for product reviews +- **useInventory** + +#### User Profile and Authorization +- [useUser](/composables/use-user) for managing user sessions, credentials and registration +- [useUserShipping](/composables/use-user-shipping) for managing shipping addresses +- [useUserBilling](/composables/use-user-billing) for managing billing addresses +- **useUserOrders** for managing past and active user orders + +#### Shopping Cart +- [useCart](/composables/use-cart) for loading the cart, adding/removing products and discounts + +#### Wishlist/Favourite +- [useWishlist](/composables/use-wishlist) for loading the wishlist, adding/removing products + +#### CMS Content +- [useContent](/composables/use-content) for fetching the CMS content. It is usually used in combination with ``component + +#### Checkout +- **useCheckout** for saving the shipping and billing address for a current order, choosing shipping method, making payments and placing the order + +#### Other +- [useVSFContext](/general/context) for accessing the integration API methods and client instances + +In a real-world application these composables will most likely use different backend services under the hood yet still leverage the same frontend API. For instance within the same application `useProduct` and `useCategory` could use `commercetools`, `useCart` some ERP system, `useFacet` - Algolia etc. ## Routing @@ -62,7 +65,15 @@ Routes are injected via `@vue-storefront/nuxt-theme` module. Use [`extendRoutes` ## Internationalization -By default we're using `nuxt-i18n` module for internationalization. You can read more about i18n in Vue Storefront [here](./i18n). +By default we're using `nuxt-i18n` module for internationalization. You can read more about i18n in Vue Storefront [here](guide/internationalization). \ No newline at end of file +--> + +## App Context + +Sometimes the only thing you need is to fetch some data without the overlap of a Composable. You will use an API Client that is accessible through `useVSFContext` composable for that. You can read about it [here](./context) + +## Integrations + +Even though high-level APIs are the same for all Vue Storefront integrations they're different on the low level (data formats, search params). Check the docs of a specific platform on the left side under "eCommerce integrations" tab to learn about them. \ No newline at end of file diff --git a/packages/core/docs/guide/internationalization.md b/packages/core/docs/guide/internationalization.md new file mode 100644 index 00000000000..e76caafd1c8 --- /dev/null +++ b/packages/core/docs/guide/internationalization.md @@ -0,0 +1,49 @@ +# Internationalization + +By default we are using `nuxt-i18n` module for handling internationalization, but it's not mandatory to use it even if you are using Nuxt. + +In order to provide unified way of configuring i18n across the application for different modules and integrations, we have introduced field `i18n` in each modules configuration that has same format as `nuxt-i18n` options. Clearly, it's possible to add there any configuration if there is a necessity and it will be propagated to all other Vue Storefront modules. + +By default all Vue Storefront modules have `useNuxtI18nModule` property set to `true`. It means that they will use the same configuration as you provided for `nuxt-i18n` in `i18n` field of your `nuxt.config.js` + +```js +// nuxt.config.js +['@vue-storefront/{INTEGRATION}/nuxt', { + api: { + // api client configuration + }, + i18n: { + useNuxtI18nModule: true + } +}] +``` + +## Custom configuration + +You are always able to provide your own i18n configuration just for a specific module by setting `useNuxtI18nModule` to false. + +```js +['@vue-storefront/{INTEGRATION}/nuxt', { + api: { + // api client configuration + }, + i18n: { + useNuxtI18nModule: false, + locales: [ + { + code: 'en', + label: 'English', + file: 'en.js', + iso: 'en' + }, + { + code: 'de', + label: 'German', + file: 'de.js', + iso: 'de' + } + ], + defaultLocale: 'en' + } +}] +``` diff --git a/packages/core/docs/guide/theme.md b/packages/core/docs/guide/theme.md new file mode 100644 index 00000000000..63cb3b22173 --- /dev/null +++ b/packages/core/docs/guide/theme.md @@ -0,0 +1,59 @@ +# 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. + +## Directory structure + +If you're familiar with Nuxt you will quickly notice that the directory structure is almost identical as 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 +``` + +## Storefront UI + +::: 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. +::: + +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 it. The library works great for multi-tenancy model as a shared UI library that can be customized differently for each tenant. + +To learn more about Storefront UI please check: +- [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 + +## Preinstalled modules and libraries + +Below you can find a list of the most important Nuxt Modules and libraries that are preinstalled with the default theme: + +### Nuxt Modules + +- `@nuxtjs/pwa` +- `nuxt-i18n` +- `@vue-storefront/nuxt` + - `@nuxtjs/composition-api` + - `@nuxt/typescript-build` + - `@nuxtjs/style-resources` + - `nuxt-purgecss` +- `@vue-storefront/nuxt-theme` + +### Libraries +- [`@storefront-ui/vue`](https://storefrontui.io) +- [`wee-validate`](https://vee-validate.logaretm.com/v3) \ No newline at end of file