ecmascript-sass-webpack-starter
Overview
Starter/boilerplate project for a web application requiring ECMAScript (6/7), Webpack (3.X) and Sass (4.X) - optionally served from a lightly configured Docker container. The project is particularly helpful for craftsmen/craftswomen demanding more control of their frontend stack and tired of the growing bloat and complexity of today's Franken-frameworks.
This repository is inspired from micooz/es6-webpack2-starter.
Features
The project supports the following "out-of-box" features:
- Multiple Entry Points, Multiple Pages
- EcmaScript (Babel (6.X) and ESLint)
- SASS (4.X, Stylelint)
- Webpack (3.X, dashboard, dev-server)
- Google Lighthouse (performance/best-practice profiling)
- Progressive Web Application (PWA) compliance
- Testing (Mocha, Chai, Istanbul)
- Documentation (JsDoc)
- Docker Container (optional)
Installation
Windows platform users should install GitBash before continuing so you can use Unix terminal commands.
Docker Container (Optional)
If you haven't already done so, install Docker on you host OS. Windows <=7 users need to install Docker Toolbox. If you have any issues, hit-up the Docker forums or SO.
The latest official Node image from the Node.js Foundation is used by the container. Edit the Dockerfile as you see fit.
# build and start container $ . ./run.sh # this will dump you on the commandline inside the container Project Hydration
$ git clone https://github.com/chrisalexander55/ecmascript-sass-webpack-starter.git$ cd ecmascript-sass-webpack-starter$ npm iAfter installation, you will see this directory structure:
|- webpack/ # webpack config dir |- src |- robots.txt |- test/ # test dir |- app |- assets | |- platform/ # icons + platform config dir |- modules | |- index/ # index modules dir | |- shared/ # shared modules dir | |- some-page-1/ # some-page-1 modules dir | |- some-page-2/ # some-page-2 modules dir | |- not-found/ # not-found modules dir | |- not-supported/ # not-supported modules dir |- pages | |- some-page-1.html | |- some-page-2.html |- sass | |- main.scss # for global styles |- index.html # default page |- not-found.html # 404 |- not-supported.html # browser doesn't meet required features Configuration
# run just to ensure env.js was created (it may silently fail) $ npm run postinstall # edit env.js per your environment needs # 1. development # - edit src/app/modules/shared/proxy/config.js to hit API resources you need # 1a. starts up the webpack-dev-server from host OS + launches browser pointing to http://localhost:3000/index.html $ npm run start:host # 1b. starts up the weback-dev-server from container # on your host OS, open your favorite web browser and point to url http://localhost:3000 $ npm run start:container # 2. production # outputs into dist/ directory $ npm run buildDistribution directory structure will look like this after transpilation:
dist |- css/ |- modules/ |- pages/ |- platform/ |- index.html |- not-found.html |- not-supported.html |- robots.txtTesting (WIP)
Not working coverage yet but present if you need it now.
Tests have a single entry point via src/test/index.js and leverage Mocha and Chai (Should) with Istanbul coverage reporting.
$ npm testDocumentation
Generate documentation based on JsDoc formated code comments:
# outputs into docs/ directory; open index.html $ npm run docsHeader Element
I know, "Dude, you talking to me about the HTML Header element?" Yes, I am because I've seen too often how under utilized it is in helping developers/organizations delivery the best possible user experience, device support and SEO. Configured right, the HTML Header is powerful!
Base Feature Support
Standard tags/attributes cover:
- Security
- Caching
- Geolocation
- Site ownership verification
- Telephone number formating
Social Media Coverage
If you need to share content tailored for social media platforms, either statically or via a SPA page, the platforms covered include:
Progressive Web Application (PWA) Support
Generally, developers are aware of the native JavaScript APIs and polyfills related to PWAs but most are not aware that markup must also be configured for an valid and performant implementation.
Platform Coverage
Platform-specific meta tags/attributes covered include:
- iOS
- Android/Chrome
- Windows
Template
Here is the recommended header element that can be cut-n-pasted and edited to fit your needs, full/partial SPA or non-SPA.
<!-- ############################################################# Order is important, including href placement! Edit as needed! ############################################################# --> <!-- ########## START: Tag Base Feature Support ########## --> <!-- security related --> <!-- Name of web application (only should be used if the website is used as an app) --> <!-- Short description of the page (limit to 150 characters) --> <!-- Tells Google not to show the sitelinks search box --> <!-- Tells Google not to provide a translation for this page --> <!-- Verify ownership for Google Search Console --> <!-- Verify ownership for Yandex Webmasters --> <!-- Verify ownership for Bing Webmaster Center --> <!-- Verify ownership for Alexa Console --> <!-- Verify ownership for Pinterest Console--> <!-- Verify ownership for Norton Safe Web --> <!-- Short description of your site's subject --> <!-- Gives a general age rating based on site content --> <!-- Allows control over how referrer information is passed --> <!-- I recommend 2 values for new apps no-referrer|none-when-downgrade --> <!-- Disable automatic detection and formatting of possible phone numbers --> <!-- Completely opt out of DNS prefetching by setting to 'off' --> <!-- for more info: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-DNS-Prefetch-Control --> <!-- Geo tags --> <!-- applicable if site represents a physical location, like a shop, agency, ect. --> <!-- Country code (ISO 3166-1): mandatory, state code (ISO 3166-2): optional; eg. content="US" / content="US-NY" --> <!-- eg. content="New York City" --> <!-- ########## END: Tag Base Feature Support ########## --> <!-- ########## Start: Tag Platform Feature Support ########## --> <!-- %%%% iOS %%%% 1. https://developer.apple.com/library/content/documentation/AppleApplications/Reference/SafariWebContent/ConfiguringWebApplications/ConfiguringWebApplications.html#//apple_ref/doc/uid/TP40002051-CH3-SW1 2. https://developer.apple.com/library/content/documentation/AppleApplications/Reference/SafariHTMLRef/Articles/MetaTags.html 3. https://developer.apple.com/ios/human-interface-guidelines/graphics/launch-screen/ --> <!-- launch icon title --> <!-- hides address bar and status bar => native application feel --> <!-- Only works if apple-mobile-web-app-capable is set --> <!-- Deep App linking --> <!-- %%%% Google %%%% --> <!-- Android --> <!-- Add to home screen; see https://developers.google.com/web/fundamentals/engage-and-retain/app-install-banners/ --> <!-- App Deep Linking --> <!-- Native App Appearance --> <!-- %%%% Windows %%%% --> <!-- Pinned site < IE 11 (https://msdn.microsoft.com/en-us/library/dn255024(v=vs.85).aspx) --> <!-- Pinned IE 11 Live Tiles (https://msdn.microsoft.com/en-us/library/bg183312(v=vs.85).aspx) --> <!-- matches the 2 pinned site tasks above from msapplication-task tag --> <!-- Facebook Open Graph (static or dynamically set; if dynamic, pre-render, then serve) --> <!-- Facebook Instant Articles (static or dynamically set; if dynamic, pre-render, then serve) --> <!-- The style to be used for this article --> <!-- %%%% 3rd-Party Tool Tags Here %%%% --> <!-- ########## END: Tag Platform Feature Support ########## --> <!-- ########## Start: Links + Platform Features ########## --> <!-- %%%% UA directives %%%% --> <!-- Origin that will be used to fetch resources, the UA "should" resolve as early as possible; https://www.w3.org/TR/resource-hints/#dns-prefetch --> <!-- Initiate early connection (DNS, TCP handshake and optional TLS negotiation) to origin; https://www.w3.org/TR/resource-hints/#preconnect --> <!-- Instructs origin to retrieve resource without blocking main thread; https://www.w3.org/TR/preload/ --> <!-- default icon --> <!-- Facebook Instant Articles --> <!-- %%%% Windows %%%% --> <!-- Windows IE11, Edge icons --> <!-- Windows Tile UI --> <!-- See file platform/windows/browserconfig.xml --> <!-- %%%% iOS %%%% --> <!-- Apple icons --> <!-- iPhone --> <!-- iPad, iPad mini --> <!-- iPad Pro --> <!-- iPhone --> <!-- Related to iOS apple-itunes-app App deep linking above --> <!-- For Safari pinned tabs; see https://developer.apple.com/library/content/documentation/AppleApplications/Reference/SafariWebContent/pinnedTabs/pinnedTabs.html --> <!-- %%%% Android/Chrome %%%% --> <!-- Android icons --> <!-- home screen icon --> <!-- Related to Android google-play-app App deep linking above --> <!-- Supported by Chrome Mobile (Android Only) + Opera; see https://developer.mozilla.org/en-US/docs/Web/Manifest --> <!-- Refer to a copyright statement --> <!-- ########## END: Links + Platform Features ########## --> <!-- ########## START: Scripts ########## --> <!-- Scripts (generally, preload > async) <script src="https://origin.com/my-script.min.js" async|defer type="[text/javascript|module]"></script> --> <!-- ########## END: Scripts ########## --> Big props go out to the maintainers at GetHead.Info. If your technical understanding of the Head element, and its siblings, is thin, I strongly encourage you visit their site to bulk-up your knowledge!
Helpers
Other stuff I've found helpful...
Port Management
# strictly unix-based, of course... # list all open ports $ netstat -nat | grep LISTEN # list pids associated with a specfic port $ lsof -ti tcp:[PORT_NUMBER] # kill a pid $ kill -9 [PID]