Yireo - Developer training

Open main menu

Vue Storefront 1 Fundamentals

Overview of PWA modules

A lesson preview of our Yireo On-Demand training on Vue Storefront 1 Fundamentals

Duration: 07:42 | Last Modified 26 May 2021

This is a preview lesson only

Note that this is a preview lesson. When accessing this lesson as part of the full training, there are a couple of benefits: The materials are available via the Yireo Courseware portal and can be presented as a slideshow, progress can be monitored, additional resources will be available. And obviously, all lessons - instead of just the preview lessons - will be available to you.

Get full access to the Vue Storefront 1 Fundamentals training

Student notes

Overview of PWA modules

The VSF1 API is fully extensible by adding custom written modules to it. Let's see how we can put together a custom module.

Module locations

  • core/modules - Core modules
  • src/modules - Custom modules

See the file src/modules/client.ts for which modules are enabled

There are - as of yet - two locations where modules could be located: Core modules are found in the core/modules folder while custom modules (or third party modules) are found in the src/modules folder. However, with a custom src/modules/client.ts file, we can theoretically add different locations as well. For instance, a VSF1 module installed via NPM could be added here as well.

Registering a module

File src/modules/client.ts:

import { FoobarModule } from '@vue-storefront/src/modules/foobar';

export function registerClientModules () {
  registerModule(FoobarModule);
}

Note that Capybara uses Webpack to rewrite src/modules/client.ts to src/themes/capybara/config/modules.ts

A PWA module is registered within the src/modules/client.ts file, by importing the module file of your choice - in this case, the file src/modules/foobar/index.ts and calling upon the resulting module object using the callback registerModules().

Before 1.11, the registration file used to be src/modules/index.ts

Within Capybara, a little Webpack is applied. The file src/themes/capybara/webpack.config.js creates an alias for src/modules/client so that the registration file becomes src/themes/capybara/config/modules.ts. This prevents any core hack to be made to the original src/modules/client.ts file. However, traditionally, the src/modules/client.ts file is regarded as a file that belongs to you, not to the core. Opinions differ.

Module entry point

File src/modules/foobar/index.ts:

import { StorefrontModule } from '@vue-storefront/core/lib/modules';

export const FoobarModule: StorefrontModule = function (
    app, store, router, moduleConfig, appConfig ) {
    ...
}

Or file src/modules/foobar/index.js:

export const FoobarModule = function (
    app, store, router, moduleConfig, appConfig ) {
    ...
}

When registering a module, we call upon the module entry point file, in this case src/modules/foobar/index.ts. The file can be either a regular JavaScript file (.js) or a TypeScript file (.ts) - it is up to you. And the file should export a callback function that resembles your module. The TypeScript type StorefrontModule (which is discussed in the next slides) documents also what kind of arguments the callback could / should have. In short, if you opt for the TypeScript variation, it makes a little bit easier.

StorefrontModule type (1/2)

type StorefrontModule = (
  options: {
    app: Vue,
    store: Store<RootState>,
    router: VueRouter,
    moduleConfig: any,
    appConfig: any
  }
) => void

The TypeScript type StorefrontModule (exported from core/lib/modules.ts) actually explains what kind of options are available to you within your own module callback.

StorefrontModule type (2/2)

  • app - Vue instance
  • store - Vuex instance
  • router - Router instance
  • moduleConfig - Module config during registration
  • appConfig - VSF PWA config (config/local.json)

The following arguments are available:

  • app: The instance of the Vue app. Note that you can't use app.use() to register new Vue plugins. You really need the global Vue.use() call for that.
  • store: The Vuex instance. The word store is perhaps a bit confusing, because this Vuex instance allows you to define a new Vuex module that has its own store. Likewise, you can add Vuex plugins on top of the existing Vuex store as well.
  • router - A Vue Router instance. The opportunities of routing have been explained in other lessons as well.
  • moduleConfig - A simple configuration passed on as a second argument to registerModule(module: StorefrontModule, config?: any). Actually, I've not found any module registration making use of it.
  • appConfig - A copy of the VSF1 PWA configuration.

Tips when building modules

  • Generate a module via vsf init:module foobar
  • Name your NPM package vsf-*
  • Write your code in TypeScript (so index.ts as starting point)

Some small tips: The command vsf init:module allows you to kickstart a new module. However, it is not more than creating the initial entry file, which could also be accomplished through a simple copy-and-paste from this coursematerial.

If you want to offer your VSF1 module as a reusable package, you can ofcourse. After the installation via yarn add vsf-foobar, the module is not registered yet. But in the near future, this might change. By naming your NPM package to start with vsf-*, you are prepared for that enhancement.

Another tip is to get started with TypeScript. While TypeScript is not that much needed for a theme, as soon as a module is used more than once, it is best to make the code a bit more robust. With a few type hints, you can reduce bugs.

Summary

  • Modules are registed in src/modules/client.ts
  • A custom module is placed in src/modules/foobar/index.ts
  • It is best to use the TypeScript type StorefrontModule to define your module

Extensions

GitHub organizations

Legal information

Other Yireo sites

Get Social

About Yireo