Simple and optimized boilerplate for Fork CMS themes. It includes:
- ES2017 support using Babel
- Latest Webpack (v3.10.0) and Webpack Dev Server (v2.9.7) with Scope Hoisting enabled
- Hot Module Replacement (HMR)
- SASS support & PostCSS
- Production config
- ES6 linting with continuous linting on file changes
Why? You need some basic tooling to get started with a current-generation frontend web development project. You may, or may not, be sure if you need all the bells and whistles but you'd much rather have a setup that is easily extensible and does the basics (build a distribution package, bundle JS, transpile ES2017 into ES5) than starting from zero.
Super simple, just clone or download the repository into your Fork CMS Themes directory and start hacking away!
- Make sure you have Node.js and NPM installed (latest LTS recommended).
- Copy this boilerplate to your
src/Frontend/Themes/MyThemeNamefolder in your new Fork CMS project. - Install dependencies by running
npm installin your theme directory. - Run
npm run buildand browse to your website. When doing local development, runnpm run watchto start a dev server which you can visit on http://localhost:3000.
npm run build- create a production-ready build in thedistfolder.npm run build:dev- start a development build.npm run watch- start the webpack-dev-server with HMR.
The build operation will clear the dist folder and compile/transpile and place fresh files in the dist folder.
The npm run watch command will use webpack-dev-server to start the dev server at 0.0.0.0:3000. Webpack will use
Core/Js/app.js as the entrypoint and from there it will import the screen.scss file and other components and dependencies. With the server active, any files you work on and update will trigger a live update using Hot Module Replacement (no refreshing!).
Webpack generates a dist/manifest.json file, mapping all source file names to their corresponding output file. For example:
{
"app.css": "/src/Frontend/Themes/MyTheme/dist/app.89b2d31313389a466bb524e9051378bc.css",
"app.js": "/src/Frontend/Themes/MyTheme/dist/app.7532415ade478926494f.js",
"vendor.js": "/src/Frontend/Themes/MyTheme/dist/vendor.795cbea922c9c995ea51.js"
}
The random-looking part of the paths is called "chunk hash" in Webpack and it's a hash of the file contents. This is the best strategy for long-term asset caching, because the hash, and therefore the asset path, will change as soon as you make any change in the asset file, busting any existing cache. If we do not change our css or vendor code, the hash will stay the same after a rebuild and no cache busting is needed.
To be able to include your .js and .css files in your Head.html.twig regardless of the version, you can use the
Asset component of Symfony to manage the assets. Define a new json_manifest_path
asset config option:
# app/config/config.yml
framework:
# ...
assets:
json_manifest_path: '%kernel.root_dir%/../src/Frontend/Themes/MyTheme/dist/manifest.json'
Then, use the asset() function in your Twig files:
<link rel="stylesheet" type="text/css" href="{{ asset('app.css') }}">
<script src="{{ asset('vendor.js') }}"></script>
<script src="{{ asset('app.js') }}"></script>
The new version strategy will turn that link into <link href="/src/Frontend/Themes/MyTheme/dist/app.89b2d31313389a466bb524e9051378bc.css"> and it will update it as soon as you change the original asset file and rebuild using Webpack.