Storefront Framework

Webpack based tool to develop and build JAMstack & PWA e-commerce templates with E-Com Plus APIs

CHANGELOG

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, 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 (https://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 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 and provide an starter config.yml file.

All content must be JSON, saved on content folder.

Renderization

We use EJS 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 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 JSON content. You may create and/or edit content here to preset some content for examples or defaults.

settings.json 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 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.

/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, is optional if you're not planning to use the the referred CMS.

config.yml should be configured 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 on uploads folder, where the merchant may upload custom logo, banners, icons and other assets from CMS dashboard.

/template/scss

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

/template/pages

EJS 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, 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 using webpack-merge.

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 file and a deploy button 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)