From 5c5c6cc6b83c04b5fe8c37f6532fb97c54302d5f Mon Sep 17 00:00:00 2001 From: Filip Drozd Date: Tue, 3 Jan 2023 14:58:11 +0100 Subject: [PATCH] feat: update docs --- app.json | 4 +- docs/.vuepress/config.js | 2 +- docs/guide/configuration.md | 57 +++++++++++++++---- .../{multi-currency.md => feature-support.md} | 53 +++++++++-------- docs/guide/getting-started.md | 48 +++++++++------- docs/index.md | 13 +++++ 6 files changed, 117 insertions(+), 60 deletions(-) rename docs/guide/{multi-currency.md => feature-support.md} (53%) diff --git a/app.json b/app.json index 0c0d6727..e05baf11 100644 --- a/app.json +++ b/app.json @@ -11,8 +11,8 @@ "value": "https://demo.spreecommerce.org" }, "SPREE_VERSION": { - "description": "Spree version of the backend. Either \"spree42\" or \"spree43\".", - "value": "spree42" + "description": "Spree version of the backend. Either \"spree43\", \"spree44\" or \"spree45\".", + "value": "spree45" } }, "buildpacks": [ diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 5854efbf..96424456 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -48,7 +48,7 @@ module.exports = { ['/', 'Introduction'], ['/guide/getting-started', 'Getting started'], ['/guide/configuration', 'Configuration'], - ['/guide/multi-currency', 'Mult-currency support'], + ['/guide/feature-support', 'Feature support'], ['/guide/about', 'About'], ] }, diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md index 7e482b68..3a180958 100644 --- a/docs/guide/configuration.md +++ b/docs/guide/configuration.md @@ -1,8 +1,8 @@ # Configuration -The integration is configured via `middleware.config.js` file. +The integration is configured via `middleware.config.js` file: -``` +```js module.exports = { integrations: { spree: { @@ -10,33 +10,61 @@ module.exports = { configuration: { backendUrl: process.env.BACKEND_URL, assetsUrl: process.env.ASSETS_URL, - spreeFeatures: defaultFeatures.spree43 + spreeFeatures: { + ...defaultFeatures[process.env.SPREE_VERSION || 'spree45'], + wishlist: 'disabled' + } } } } }; ``` -## Backend URL +## Environment variables +All the settings can be specified by using the environment variables as long as you don't need to make custom changes to [Spree Features](#spree-features) configuration. + +A recommended way of setting the variables is via `.env.development` and `.env.production` files: +```sh +BACKEND_URL=http://localhost:4000 +ASSETS_URL=... +SPREE_VERSION=... +``` + +### Backend URL + +By default, the Vue Storefront application will connect to the API at https://demo.spreecommerce.org. You can change it by setting the `BACKEND_URL` env variable. -By default the integration will use the `BACKEND_URL` environment variable. If it's not present, it will fallback to `https://demo.spreecommerce.org`. +### Assets URL +The `ASSETS_URL` indicates the main url for images, css. If it's not present, it will fallback to `BACKEND_URL`. -## Assets URL -The `ASSETS_URL` indicate the main url for images, css. f it's not present, it will fallback to `BACKEND_URL`. +### Spree version (presets) +Specify the version of Spree that you are using (if not provided, it will fallback to `spree45`). Using a dedicated preset will ensure that Vue Storefront only uses the [features](#spree-features) compatible with your version of Spree. + +The supported options are: `spree43`, `spree44`, `spree45`. ## Spree Features -Spree features is an object containing features flags to be enabled. -This is done to achieve backwards compatibility, as some of the features require Spree 4.3+. They can be disabled, to provide slightly degraded experience, but you may do it if you'd like to experiment with Vue Storefront without upgrading 4.2 to 4.3. +Spree features is an object containing features flags to be enabled. This is done to achieve backwards compatibility with various Spree versions. + +Also some features that are either provided by Spree's extensions or that are only available in newer versions, need to be manually enabled in the configuration file (for example wishlists). You can also use it to overwrite the chosen [preset](#spree-version-presets)'s feature configuration. ```js spreeFeatures: { - associateGuestCart: true, - fetchPrimaryVariant: true, - wishlist: 'disabled' + ... + // Associate guest cart after the customer logs in. Requires Spree 4.3+ + associateGuestCart: false, + // Fetch basic information about products from the `primary_variant` relationship. Requires Spree 4.3+ + fetchPrimaryVariant: false, + // Wishlist for authenticated users. + // Accepted values: 'enabled' (Spree 4.4+), 'legacy' (Spree with `spree_wishlist` gem), 'disabled'. + wishlist: 'disabled' } ``` +:::tip +Some of the features that require Spree 4.3+ can be disabled, to provide slightly degraded experience, but you may do it if you'd like to experiment with Vue Storefront without upgrading 4.2 to 4.3. +::: + ### associateGuestCart Defines whether a guest cart should be associated with user after sign in. This requires `/api/v2/storefront/cart/associate` endpoint, available in Spree 4.3+. @@ -54,3 +82,8 @@ Accepted `wishlist` values: - `'enabled'` (Spree 4.4+) - `'legacy'` (Spree older than 4.4 with `spree_wishlist` gem installed) - `'disabled'` (Spree older than 4.4 without `spree_wishlist` gem) + +## Spree configuration + +### Password reset functionality +In order for the password reset feature to work properly, you need to change the URL of password reset emails to point to: `/resetPassword?token=...` \ No newline at end of file diff --git a/docs/guide/multi-currency.md b/docs/guide/feature-support.md similarity index 53% rename from docs/guide/multi-currency.md rename to docs/guide/feature-support.md index 8d5370c0..4ca80331 100644 --- a/docs/guide/multi-currency.md +++ b/docs/guide/feature-support.md @@ -1,4 +1,22 @@ -# Multi-currency support +# Feature support + +| Feature | Status | Notes | +| --- | --- | --- | +| Sign in | Available | | +| Sign up | Available | | +| Product catalog | Available | Default implementation uses /v2/storefront/products endpoint for filtering, it's advisable to use ElasticSearch for best performance | Product details page | Available | | +| Account | Partial | Requires Spree 4.2 | +| Account - saved addresses | Available | Requires Spree 4.2 | +| Account - reset password | Available | URL from password reset emails should point to: `/resetPassword?token=...` | +| Account - order history | Available | | +| Cart | Available | Associating guest orders upon login requires Spree 4.3 and needs to be enable via configuration | +| Checkout | Available | | +| Checkout - Shipping methods | Available | | +| Checkout - Payment methods | Available | Cash and Stripe Elements gateways supported out of the box. | +| Wishlists | Available | Available only for logged in users. By default, this feature is disabled and can be enabled in `middleware.config.js` | +| Multi-currency support | Available | Requires Spree 4.2 or spree_multi_currency extension | + +## Multi-currency support Since 1.3.0, Spree + Vue Storefront integration supports multiple currencies natively. @@ -8,7 +26,7 @@ This means that if your store is available in English and German, and supports U To use multiple currencies, you'll need to set up available currencies both in Spree and in Vue Storefront. -## Enabling multiple currencies in Spree admin panel +### Enabling multiple currencies in Spree admin panel As the first step, you'll need to configure available currencies in Spree's backend. @@ -21,35 +39,20 @@ Then, you'll need to set prices in these currencies for products. When editing a When the customer chooses a given currency, they'll only see products that have a price set in that currency. -## Configuring available currencies in Vue Storefront +### Configuring available currencies in Vue Storefront Next, you'll need to set up the currency in Vue Storefront's configuration. Open `packages/theme/nuxt.config.js` and find the following definition: ```js -vueI18n: { - silentTranslationWarn: true, - fallbackLocale: 'en', - numberFormats: { - en: { - currency: { - style: 'currency', - currency: 'USD', - currencyDisplay: 'symbol', - currencyDefault: 'USD' - } - }, - de: { - currency: { - style: 'currency', - currency: 'EUR', - currencyDisplay: 'symbol', - currencyDefault: 'EUR' - } - } - }, -}, +publicRuntimeConfig: { + ... + currencies: [ + { code: 'USD', label: 'Dollar' }, + { code: 'EUR', label: 'Euro' } + ] +} ``` To add a new currency, you'll need to add its definition to the dictionary. After that, it will be visible in the currency switcher and available to the customer to use. diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index 9fc7204f..3c91c15f 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -2,31 +2,39 @@ ## Requirements -- Spree 4.2 or later (4.3 preferred for full feature support) +- Node 14.15+ +- Spree-based store with V2 API available (4.5 preferred for full feature support). Some API endpoints used by the integration are only available in Spree 4.2+, so you may need to either upgrade the store or backport these features to your backend. - Spree Gateway 3.9.4+ -- Node 14 -## Connecting integration to Spree +## Quick setup -By default, the Vue Storefront application will connect to the API at https://demo.spreecommerce.org. -To change it, open `middleware.config.js` and update it with your own API url. +Clone the Spree integration repository and install required dependencies: +```sh +git clone https://github.com/vuestorefront/spree.git -If you're using Spree 4.2, you'll also need to change the configuration used for `spreeFeatures` to `defaultFeatures.spree42`. +yarn install +``` -```js -module.exports = { - integrations: { - spree: { - location: '@vue-storefront/spree-api/server', - configuration: { - backendUrl: process.env.BACKEND_URL, - assetsUrl: process.env.ASSETS_URL, - spreeFeatures: defaultFeatures.spree43 - } - } - } -}; +### Connecting integration to Spree +By default, the Vue Storefront application will connect to the API at https://demo.spreecommerce.org. You can change it by setting the `BACKEND_URL` env variable: +```sh +export BACKEND_URL=https://demo.spreecommerce.org +``` +Alternatively via `.env.development` file: +``` +BACKEND_URL=https://demo.spreecommerce.org +``` + +### Running the application + +Now you can build all three projects: +```sh +yarn build +``` +If everything built properly, you can start working on your new frontend with: +```sh +yarn dev ``` -In order for the password reset feature to work properly, you need to change the URL of password reset emails to point to: `/resetPassword?token=...` \ No newline at end of file +Changing some parts of the code (notably the `api-client`) will trigger a re-build but the change will not be hot-reloaded. To ensure that the app sees you changes, re-run either `yarn build` or `yarn dev`. diff --git a/docs/index.md b/docs/index.md index 86f2e4a2..659937ed 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,3 +8,16 @@ This project is a Spree integration for Vue Storefront 2. This integration is currently stable and ready for production usage. If you'd like to report a bug or contribute to the codebase, please see the [repository issues page](https://github.com/vuestorefront/spree/issues). + +## Project structure + +The monorepo contains three submodules: +- api-client - low level backend API connector, utilizing Spree's v2 Storefront API +- composables - reusable business logic +- theme - Nuxt.js-based frontend application + +For more details, refer to the official [project structure](https://docs.vuestorefront.io/v2/getting-started/project-structure.html). + +## Spree backend + +Before setting up the Vue Storefront application you will need to have a Spree instance running. The easiest way to start is by using the [Spree CLI](https://dev-docs.spreecommerce.org/getting-started/spree-cli) tool. Once you have the backend running you can follow along with this guide to set up and configure the VSF integration with it. \ No newline at end of file