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 9123 (http://localhost:9123);
• 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;

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
  cms,
  // 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,
  brands,
  items,
  // 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,
  // Optional route object
  route
}

EJS is configured with support for asyc/await and 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 data may have a route property, it'll be set when the same EJS file should be rendered to multiple pages (slugs):

• 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, the route object will not be set on template data;

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.

/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.

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)