# Theme

# Directory structure

If you followed our Installation guide, you should have a fully functional e-commerce application. As mentioned in previous documents, Vue Storefront extends 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 (opens new window) page.

# Storefront UI

Almost every component in our default theme uses components whose names start with Sf. These come from Storefront UI (opens new window) - a design system and library of Vue.js components dedicated to e-commerce, maintained by the Vue Storefront core team. It comes with Storybook (opens new window) to help you customize and test the components.

The library is fully customizable. It can be used in different contexts and with different designs. It's excellent 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 its Documentation (opens new window).

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.

# Customizing the theme

# Learn Nuxt.js

Before starting to customize the base theme, we highly recommend getting familiar with Nuxt.js (opens new window) because the majority of UI functionalities in Vue Storefront are handled by it. It will help you understand the mechanisms behind the framework and how to extend it efficiently.

# Install Vue.js Devtools

We also recommend installing Vue.js Devtools (opens new window) in your browser. It's an excellent tool for viewing component structure and their current state, inspecting events and routes, and much more.

# Changing existing pages, components, and layouts

To update the existing components, you need to identify them first. Vue.js Devtools helps us in that. Open the tool and click on the Select button above the component tree, then click on the DOM element you want to update. One of the components in the tree should get highlighted. You can look for the component with the same name in the layout, pages, or components directories and update it to your needs. However, there are few exceptions to this rule.

# Sf components

If the name of the component starts with Sf (indicating that it comes from Storefront UI), you should refer to the direct parent component. The behavior and look of such components can be changed by passing different properties and using slots. Refer to the StorefrontUI documentation linked above for more information.

# LazyHydrate and Anonymous Component components

These two components come from the vue-lazy-hydration library and are wrappers around other components. In Vue Storefront they are used to improve the performance by deferring the hydration process (when components become interactive) and don't affect the look of other components.

If you encounter one of these components, you should refer to the direct child component.

# Adding new page

To add a new page, create a new component in the pages folder and name it the same as your route using PascalCase.

As an example, let's create the AboutUs.vue component. This by itself creates a new route named /aboutus (thanks to File System Routing (opens new window) in Nuxt.js) and in some cases might be enough. However, to follow the convention of using kebab-case in URLs, let's use extendRoutes (opens new window) in nuxt.config.js to have more control over the route.

Add following configuration to nuxt.config.js to create new route /about-us:

// nuxt.config.js

export default {
  router: {
    extendRoutes(routes, resolve) {
      routes.push({
        name: 'AboutUs',
        path: '/about-us',
        component: resolve(__dirname, 'pages/AboutUs.vue')
      });
    }
  }
};

For more information about routes we provide out of the box, refer to Routing section.

# Updating styles

There are few ways of updating the default styles. Below we describe the most optimal ways for the most common cases.

# Adding global styleheet

To add global styles applied to all pages, use the css property (opens new window) in nuxt.config.js.

# Adding stylesheet to specific layout, page, or component

To add a stylesheet to a specific component, use @import regardless if you are using CSS, SCSS, or LESS.

<style>
@import "@/assets/stylesheet.css";
</style>

# Using variables, mixins, and function in components

Usually, to access style variables, mixins, and functions, we have to import them in every component separately. Thanks to @nuxtjs/style-resources (opens new window) module, we can register them in nuxt.config.js and access them without extra @import statements.

Be careful

Stylesheets in styleResources should only contain variables, mixins, and functions. During the build process, the components import these stylesheets. Any styles declared in them are added to every component, which can significantly hurt the performance and application size.

We use this approach to have access to StorefrontUI helpers in all components:

// nuxt.config.js
export default {
  styleResources: {
    scss: [require.resolve('@storefront-ui/shared/styles/_helpers.scss', { paths: [process.cwd()] })]
  },
};

# Preinstalled modules and libraries

Below you can find a list of the most important Nuxt Modules and libraries that come preinstalled with the default theme:

# Nuxt.js modules

  • @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