Connecting Vue Storefront to Spree

Rafal Cymerys

October 13, 2021

Night mode

Spree Commerce is a headless, omnichannel eCommerce backend engine complete with functionality for any eCommerce business or use case. Recently the team at Upside delivered an out-of-the-box integration for Vue Storefront, which provides reusable components for building Vue Storefront-based frontends that connect to Spree on the backend. It also comes with a default theme that allows developers to quickly start their implementation of e-commerce storefronts.

Let's take a look at how to integrate it with your Spree (4.2+) instance

Getting Started

Let's start with cloning the integration repository:

git clone https://github.com/vuestorefront/spree

‍

Then, install dependencies:

yarn

‍

And trigger a test build of your project, to make sure everything compiles fine:

yarn build

Configuration

After the repository is set up correctly, you should review the configuration file to make sure the it's correct. Open the packages/theme/middleware.config.js file. You will see the following lines:

module.exports = {
  integrations: {
    spree: {
      location: '@upsidelab/vue-storefront-spree-api/server',
      configuration: {
        backendUrl: process.env.BACKEND_URL,
        spreeFeatures: defaultFeatures.spree43
      }
    }
  }
};

‍

There are two configuration options you may want to update:

backendUrl - pointing to the spree instance that you'd like to connect it to (by default it's taken from BACKEND_URL env variable, if none provided it will fall back to https://demo.spreecommerce.org

spreeFeatures - this is a set of feature flags, pre-configured for specific version of Spree on the backend. If you set it to defaultFeatures.spree42 , Vue Storefront will disable some API calls to be compatible with Spree 4.2

Running development environment

In the main directory, run yarn dev to start the development server. After the compilation finishes, you will be able to access the storefront at http://localhost:3000

Customizing theme

In the theme package, you will find components that were customized by the default Spree integration, compared to stock Vue Storefront implementation. When a project is compiled, they are merged with Vue Storefront's implementation (overriding them) and the resulting set of components ends up in packages/theme/_theme directory.

Let's make some changes to the default theme.

For example, if you'd like to change the links at the top of the page, that are compiled into the theme:

‍

Run yarn dev (this will compile your theme and generate packages/theme/_theme directory, where the customizations from your theme will be bundled together with VSF's stock components
Copy packages/theme/_theme/components/HeaderNavigation.vue to packages/theme/components/HeaderNavigation.vue
Open the newly created file packages/theme/components/HeaderNavigation.vue. As you see, it generates the links based on the categories array:

<SfHeaderNavigationItem
  v-for="(category, index) in categories"
  :key="index"
  class="nav-item"
  v-e2e="`app-header-url_${category}`"
  :label="category"
  :link="localePath(`/c/${category}`)"
/>

setup() {
  const { isMobileMenuOpen, toggleMobileMenu } = useUiState();
  const categories = ['women', 'men'];

  return {
    categories,
    isMobileMenuOpen,
    toggleMobileMenu
  };
}

‍

You can change the categories array to set your own main categories. If you use a different permalink structure, you can also change the way the :link attribute is generated.
Once you save the file, your dev server will pick up changed automatically.

Advanced: Customizing data and API calls

Making changes to api-client module

If your Spree instance modified any of the V2 API endpoints, or adds new ones you will need to adjust the api-client.

Note: Unlike theme package, which is automatically recompiled when a file is saved, you will need to restart your dev server for changes in api-client and composables to be reflected.

To make changes in the existing API methods, take a look at the packages/api-client/src/api directory. It contains separate files for implementation of every Spree API call used by Vue Storefront.

To a new API method, you can follow the same structure. Then, import the new method in packages/api-client/index.server.ts and add it to the createApiClient method definition.

const { createApiClient } = apiClientFactory({
  onCreate,
  api: {
    getProduct,
    getProducts,
    yourNewFunction,
    ...
  }
});

‍

After restarting the server, you'll be able to call it via context.$spree.api.yourNewFunction()

Making changes to composables

Composables are reusable pieces of business logic that can be used by the theme via Vue Composition API. You will find them in packages/composables/src directory.

If needed, you can make changes to the standard composables provided. You can also easily add new composables for your own custom logic. To do that, take a look at the useCountry composable and follow the structure there. You'll also need to export your composable in the composables/src/index.ts file.

Next steps

Keep in mind that Vue Storefront provides a set of basic templates for your e-commerce, that you can fully customize or even replace. Regardless of the changes in the theme, you can always rely on the business logic provided by composables.

After setting up a new Vue Storefront project and connecting it to the backend, you will most likely want to customize the Storefront UI look and feel or build your own set of components that follow your needs.

Happy hacking!

Back to blog