/fork-cms-vite-boilerplate

Allows the use of the Vite.js next generation frontend tooling with Fork CMS.

Primary LanguagePHP

Fork CMS theme boilerplate using Vite

CI PRs Welcome

Allows the use of the Vite.js next generation frontend tooling with Fork CMS.

Simple, opiniated and performance-optimized boilerplate for Fork CMS themes supporting Typescript, React, ESNext, TailwindCSS, PostCSS, Dynamic Imports and Hot Module replacement using Vite.

Vite Overview

Next Generation Frontend Tooling

Vite (French word for "fast", pronounced /vit/) is a new breed of frontend build tool that significantly improves the frontend development experience. It consists of two major parts:

Features of Vite include:

  • 💡 Instant Server Start
  • ⚡️ Lightning Fast HMR
  • 🛠️ Rich Features
  • 📦 Optimized Build
  • 🔩 Universal Plugin Interface
  • 🔑 Fully Typed APIs

This codebase helps to create a bridge between Fork CMS/Twig and the next generation frontend build tool Vite.js using the ViteAssetExtension.php.

ViteAssetExtension allows for Hot Module Replacement (HMR) of JavaScript, CSS, and Twig (even through errors) during development, as well as optimized production builds. ViteAssetExtension supports both modern and legacy bundle builds. ViteAssetExtension also handles generating the necessary <script> and tags to support both synchronous and asynchronous loading of JavaScript and CSS.

✨ Opiniated list of features I want Vite to do

  • Code splitting with Dynamic Imports support aka lazy loading. Load only the code/resources needed when they are needed, without render blocking.
  • Development/Production. In local dev I want fast builds via the in-memory server, and for production builds I want every possible optimization.
  • Hot Module Replacement (HMR) during local dev. As I make changes to my Javascript, CSS or templates I want the webpage to seamlessly refresh. This speeds development tremendously: just say no to the Reload button. Even Twig error pages are reloaded after making a code change!
  • Dynamic Code Splitting. I don't want to manually define Javascript chunks in a config file. Vite needs to sort that out for me.
  • Cache busting via manifest.json. This allows us to set a long expiry date for static assets, while also ensuring that they are automatically cache busted if they change.
  • Typescript support.
  • ESNext support out of the box.
  • React support. Depending on the project, I either choose Vanilla Typescript, AlpineJS or React.
  • PostCSS. Think of it as the Babel of CSS, to add advanced features to CSS, or use upcoming CSS features now.
  • Tailwind CSS. While I have used BEM/ITCSS for years, I started to love the advantages of utility-css and rapidly building UI's without leaving your html code, without naming things, and without browsing endless files of css to find conflicting rules. Very opiniated choice though ;-)
  • PurgeCSS scans the theme folder for classnames that are actually used, and removes the unused styles, causing a very small css file to be generated! Perfect for tailwind css. This is built into Tailwind nowadays.
  • Prettier 💄 to automatically format js/css/html code.
  • ESLint to statically analyze and help find problems in the js/ts code.
  • Critical CSS. This makes your initial page loads significantly faster.
  • Modern & Legacy JS Bundles. I want to deploy modern JS modules to the 75%+ of browsers that support it, while gracefully providing a fallback legacy bundle for legacy browsers (with transpiled code and polyfills).

🔧 Installation

Just clone or download this repository into your Fork CMS Themes directory and start hacking away!

  1. Copy this boilerplate to your src/Frontend/Themes/MyThemeName folder in your new Fork CMS project.
  2. Configure the Twig ViteAssetExtension in Symfony:
# app/config/config.yml
services:
    ...

    # Configure the twig extension for ViteJS to easily switch between dev and prod script tags
    Frontend\Themes\MyThemeName\ViteAssetExtension:
        autowire: true
        arguments:
            $environment: '%kernel.environment%'
            $includeReactRefreshShim: false
        tags:
            - { name: twig.extension }
            - { name: kernel.event_listener, event: kernel.exception }

and make sure to add your theme name in the namespace declaration inside ViteAssetExtension.php. We'll find a way to auto-register this extension in later versions of Fork CMS.

  1. Install dependencies by running npm install in your theme directory.
  2. Run npm run build for a production build and browse to your website. The Twig extension will include the production-optimized files in Twig, as found in the dist/manifest.json.
  3. When doing local development, run npm run dev to start a dev server. Visit your normal local website url (e.g. http://localhost or http://mywebsite.test) because the Twig extension will detect that the dev server is running and include the Vite scripts.

📦 Available commands

  • npm run build - create a production-ready build in the dist folder.
  • npm run dev - start the vite-dev-server with HMR.
  • npm run prettier - Execute Prettier on your JS/CSS files.
  • npm run prettier-check - Check for Prettier on your JS/CSS files.
  • npm run lint - Lint your code using ESLint

Awesome Vite resources