Framework for PWA and JAMstack e-commerce templates with E-Com Plus APIs
npm install @ecomplus/storefront-framework 
Webpack based
tool to develop and build
JAMstack &
PWA
e-commerce templates with
E-Com Plus APIs
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 :wink:
_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.
First things first, install the module as dev dependency:
``bash`
npm i --save-dev @ecomplus/storefront-framework
> Note: while you can install and run storefront-pack globally,
we recommend installing it locally.
- storefront-pack serve:storefront-pack build
Starts Webpack development server on port _9100_ (http://localhost:9100);
- :
Compile assets bundles for production and prerender e-commerce pages;
#### Optional arguments
- --port=8080:--verbose
Change the dev server port number, you may replace _8080_ by what you want;
- :--analyze
Detailed output of Webpack compilation process;
- :--sw
Open Webpack Bundle Analyzer with dev server;
- :--prerender=index,app/index
Force setup manifest and Service Worker on dev server;
- :--prerender-limit=50
List URLs to be prerendered (defaults to all);
- :--no-bundler
Limit number of random URLs to be prerendered;
- :
Disable Webback compilation to run views renderization only;
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:
`json`
{
"scripts": {
"serve": "storefront-pack serve",
"build": "storefront-pack build"
}
}
And run the following in your terminal/console:
`bash`
npm run serve
Building for production:
`bash`
npm run build
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.
We use EJS to prerender views with
following template data:
`jscontent/settings.json
data = {
_: {
// Boolean development mode
devMode,
// Parsed object from
settings,
// Function to get CMS JSON content by filepath
cms,
// Function to get 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.
You can code examples of EJS these views in our
storefront-template repo.
You may load CMS content by calling the cms function
with the filename (without extension) as param, eg.:
`ejs`
<% const page = _.cms('pages/about-us') %>
<%= page.title %>
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.:
`ejs`
<%= _.md.render(pages.home.md_content) %>
Template parameters will have a route property,
it'll be an object varying by type of view:
- Store resource (products, categories, brands, collections):
`js`
route = { path, resource, _id }
You should use to get the body of respectiveecomClient
resource document with ;
- CMS folder collection (eg.: _blog_ or _pages_):
`js`
route = { path, collection, slug }
You should use to get the parsed CMS contentcms
with function;
- In other cases, such as for index.ejs:`js`
route = { path }
You may use to know the current context
on included EJS partials;
#### Context object
With resolveRoute function you can get context objectbody
with resource or CMS collection content:
`ejs`
<%
const context = _.resolveRoute()
if (_.route.resource) {
// store resource
// context = { resource, body }
} else if (_.route.collection) {
// cms folder collection
// context = { collection, slug, content }
} else {
// context = {}
}
%>
Passing _absolute path_ (posix) you can import EJS files
directly from @ecomplus/storefront-template
(or other configured with env)template/pages:
`ejs`
<%- await include('/@/views/home', { _ }) %>
To work with this framework,
your template project must have the following file structure:
`
├── 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,#cms/blog.ejs
you should have a view , it will generate an HTML page for each
post saved by CMS.
On production, files will be created on dist folder,template/js/index.js will be bundled to dist/storefront.js
and 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 in case of store resources or CMS
folder collections.
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.
We've set #template as Webpack resolve alias to@ecomplus/storefront-template/template
(or other pkg if configured with env).
So you can use, for example:
`js`
import '#template/js/'
`scss`
@import '#template/scss/main'
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).
`md``
