# Storefront Framework

(opens new window) (opens new window)

Webpack (opens new window) based tool to develop and build JAMstack (opens new window) & PWA (opens new window) e-commerce templates with E-Com Plus APIs (opens new window)

CHANGELOG (opens new window)

# Starter template

storefront-framework is a JS tool to create new templates faster and with better development experience, but if you don't want to start the entire template from scratch, we also provide the storefront (opens new window), which is built with this framework and is also open source 😉

Storefront is a complete e-commerce template with few dependencies, you may change what you need to customize and setup your own theme and scripts.

# Getting started

First things first, install the module as dev dependency:

npm i --save-dev @ecomplus/storefront-framework

Note: while you can install and run storefront-pack globally, we recommend installing it locally.

# Commands

storefront-pack serve: Starts Webpack development server on port 9100 (http://localhost:9100);
storefront-pack build: Compile assets bundles for production and prerender e-commerce pages;

# Optional arguments

--port=8080: Change the dev server port number, you may replace 8080 by what you want;
--verbose: Detailed output of Webpack compilation process;
--analyze: Open Webpack Bundle Analyzer (opens new window) with dev server;
--sw: Force setup manifest and Service Worker on dev server;
--prerender=index,app/index: List URLs to be prerendered (defaults to all);
--prerender-limit=50: Limit number of random URLs to be prerendered;
--no-bundler: Disable Webback compilation to run views renderization only;

# NPM scripts

NPM package.json scripts are a convenient and useful means to run locally installed binaries without having to be concerned about their full paths. Simply define a script as such:

{
  "scripts": {
    "serve": "storefront-pack serve",
    "build": "storefront-pack build"
  }
}

And run the following in your terminal/console:

npm run serve

Building for production:

npm run build

# Pages CMS

You should use a CMS for the store pages, we recommend Netlify CMS (opens new window) and provide an starter config.yml (opens new window) file.

All content must be JSON, saved on content folder.

# Renderization

We use EJS (opens new window) to prerender views with following template data:

data = {
  _: {
    // Boolean development mode
    devMode,
    // Parsed object from `content/settings.json`
    settings,
    // Function to get CMS JSON content by filepath
    cms,
    // Function to get `content/dictionary/${lang}` object
    dictionary,
    // MarkdownIt instance to parse MD markup
    md,
    // Store ID number
    storeId,
    // Language code string
    lang,
    // Brand colors RGB
    primaryColor,
    secondaryColor,
    // Preloaded data from E-Com Plus APIs
    store,
    categories,
    grids,
    items,
    // Contextual route object
    route,
    // Async resolve current route and get context object
    resolveRoute,
    // Lodash utility library
    // https://lodash.com/docs/
    lodash,
    // Utility functions for e-commerce
    // https://developers.e-com.plus/ecomplus-utils/
    ecomUtils,
    // E-Com Plus APIs client
    // https://developers.e-com.plus/ecomplus-client/
    ecomClient,
    // Search engine constructor
    // https://developers.e-com.plus/search-engine/
    EcomSearch,
    // Detect local images dimensions
    // https://github.com/image-size/image-size
    tryImageSize,
    imageSize
  }
}

EJS is configured with support for asyc/await and includes.

Note that all parameters are inside the parent _ (global), we use it to make easy to pass the original template parameters with EJS includes.

# Examples

You can code examples of EJS these views in our storefront-template (opens new window) repo.

# Loading JSON content

You may load CMS content by calling the cms function with the filename (without extension) as param, eg.:

<% const page = _.cms('pages/about-us') %>
<%= page.title %>

# Parsing markdown content

Some of your CMS content may be saved as markdown, on EJS views you can render it to HTML by using md.render function, eg.:

<%= _.md.render(pages.home.md_content) %>

# Handling slugs and routes

Template parameters will have a route property, it'll be an object varying by type of view:

Store resource (products, categories, brands, collections):

route = { path, resource, _id }

You should use route._id to get the body of respective resource document with ecomClient;

CMS folder collection (eg.: blog or pages):

route = { path, collection, slug }

You should use route.slug to get the parsed CMS content with cms function;

In other cases, such as for index.ejs:

route = { path }

You may use route.path to know the current context on included EJS partials;

# Context object

With resolveRoute function you can get context object with resource body or CMS collection content:

<%
const context = _.resolveRoute()
if (_.route.resource) {
  // store resource
  // context = { resource, body }
} else if (_.route.collection) {
  // cms folder collection
  // context = { collection, slug, content }
} else {
  // context = {}
}
%>

# Includes with absolute path

Passing absolute path (posix) you can import EJS files directly from @ecomplus/storefront-template (or other configured with STOREFRONT_TEMPLATE env) template/pages:

<%- await include('/@/views/home', { _ }) %>

# Project structure

To work with this framework, your template project must have the following file structure:

# Basic directory tree

├── content
└── template
    ├── assets
    ├── js
    ├── pages
    ├── public
    │   ├── admin
    │   └── img
    │       └── uploads
    └── scss

# `/content`

Root directory for Netlify CMS (or any other headless CMS) collections (opens new window) JSON content. You may create and/or edit content here to preset some content for examples or defaults.

settings.json (opens new window) is required and must have at least the properties preseted as default.

# `/template`

Source template files. All JS, SCSS, images and other assets files should be placed here.

# `/template/assets`

Predefined template assets (such as images, videos, sounds...) that should be imported inside js or scss files.

# `/template/js`

JS source files, index.js (opens new window) is required, other files and modules should be imported from index.

Other JS files on /template/js directory will also be considered additional Webpack entry point (opens new window).

# `/template/public`

Any static assets placed in the public folder will simply be copied and not go through Webpack. You need to reference them using absolute paths.

# `/template/public/admin`

Setup for Netlify CMS (opens new window), is optional if you're not planning to use the the referred CMS.

config.yml (opens new window) should be configured (opens new window) following your template options and features. The settings collection (file content/settings.json) must have at least the preseted fields.

# `/template/public/img`

Place default favicon and app icons here.

# `/template/public/img/uploads`

Netlify CMS media (opens new window) on uploads folder, where the merchant may upload custom logo, banners, icons and other assets from CMS dashboard.

# `/template/scss`

SCSS (opens new window) to compile CSS stylesheet, styles.scss (opens new window) is required, other files and modules should be imported inside it.

# `/template/pages`

EJS (opens new window) markup to compile HTML pages.

Required files:

├── index.ejs
├── #brands.ejs
├── #categories.ejs
├── #collections.ejs
└── #products.ejs

The above files have to be in the root of pages directory.

To complete the storefront template, you should also create other EJS views. It's possible to use as many pages as you want, and you can choose any filenames.

You may want to add a #cms folder inside pages directory, this folder should contain EJS views for folder collections (opens new window), witch produces multiple slugs.

For example, for a blog folder collection on folder content/blog, you should have a view #cms/blog.ejs, it will generate an HTML page for each post saved by CMS.

# Output

On production, files will be created on dist folder, template/js/index.js will be bundled to dist/storefront.js and template/scss/styles.scss to dist/storefront.css.

Additional entry points on template/js/ or template/scss/ root will respect original filename.

EJS on template/pages/ will be parsed to dist/[file].html or dist/[slug].html in case of store resources or CMS folder collections.

# Working with Webpack

The easiest way to tweak the Webpack configuration is providing an object exported by storefront.webpack.js file on your project root.

The object will be merged into the final config (opens new window) using webpack-merge (opens new window).

# Default Webpack aliases

We've set #template as Webpack resolve alias to @ecomplus/storefront-template/template (or other pkg if configured with STOREFRONT_TEMPLATE env).

So you can use, for example:

import '#template/js/'

@import '#template/scss/main'

# Deploy with Netlify

As a JAMstack app, your template may be easily deployed with Netlify, to do that you should add a simple netlify.toml (opens new window) file and a deploy button (opens new window) with link to your template repository and stack=cms param (considering you're using Netlify CMS).

# Sample

[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?stack=cms&repository=https://github.com/ecomclub/storefront-framework)

(opens new window)

← Checkout SPA analytics →