templates/modernkit

ModernKit Project

ModernKit is a versatile and performant project boilerplate built with Gulp, Twig, and SCSS. It provides a robust build system and a foundational UI kit to kickstart your web development.

Features

• Build System:
  • Gulp-powered task runner.
  • SCSS compilation with Autoprefixer and minification (for production).
  • JavaScript transpilation (Babel) and concatenation with separate development (unminified) and production (minified) builds.
  • Image optimization (including WebP generation for production).
  • Twig templating with dynamic data injection from JSON files (only top-level templates are processed into HTML files).
  • Asset copying (e.g., other static files).
  • Favicon copying.
  • Font copying.
  • SVG sprite generation and injection into HTML.
  • Resource versioning (cache busting) using content hashing (for production).
  • Source map generation for CSS and JavaScript (for development).
  • Code Quality: Biome integration for JavaScript linting and formatting.
  • Robust error handling with gulp-plumber.
  • Performance Optimization: Utilizes gulp-cached and gulp-remember to speed up recompilation of unchanged files.
  • Clean task to remove build artifacts.
• UI Kit:
  • Basic styles and resets.
  • Comprehensive typography.
  • Responsive grid system.
  • Utility classes for spacing, text alignment, display, and colors.
  • Basic components (e.g., buttons).

Getting Started

Prerequisites

Make sure you have Node.js and npm installed on your system.

Installation

1. Clone the repository:

   git clone <your-repository-url>
   cd modernkit
   

2. Install the dependencies:

   npm install
   

Available Commands

• npm start: Runs the default Gulp task, which starts a development server with BrowserSync, watches for file changes, and recompiles assets automatically. This uses the development JavaScript build (unminified) and generates source maps.
• npm run build: Performs a one-time development build. Cleans the dist directory, lints JavaScript, generates SVG sprites, compiles Twig templates, SCSS, JavaScript (development version), optimizes images, and copies assets, favicon, and fonts.
• npm run build:prod: Performs a one-time production build. Similar to npm run build, but uses minified CSS and JavaScript (production version), optimizes images more aggressively, generates WebP versions of images, and applies content hashing for cache busting.
• npm run test: Runs Jest tests.
• npm run lint: Runs Biome check on JavaScript files.
• npm run format: Runs Biome formatter on JavaScript files.

Project Structure

modernkit/
├───gulpfile.js
├───jest.config.js
├───package-lock.json
├───package.json
├───biome.json
├───dist/                 # Compiled output (ignored by Git)
├───node_modules/         # Node.js dependencies (ignored by Git)
└───src/
    ├───images/           # Source images
    │   └───test.png
    ├───js/               # Source JavaScript files
    │   ├───main.js
    │   └───main.test.js
    ├───scss/             # Source SCSS files
    │   ├───main.scss
    │   ├───_variables.scss
    │   ├───_base.scss
    │   ├───_typography.scss
    │   ├───_grid.scss
    │   ├───_utilities.scss
    │   └───_components.scss
    ├───templates/        # Twig templates
    │   ├───index.twig
    │   ├───about.twig
    │   └───components/   # Twig components
    │       ├───button.twig
    │       ├───footer.twig
    │       └───header.twig
    ├───data/             # JSON data for Twig templates
    │   ├───global.json
    │   └───about.json
    ├───assets/           # Static assets (e.g., other files)
    │   └───test.txt
    ├───icons/            # SVG icons for sprite generation
    │   ├───clock.svg
    │   └───info.svg
    └───fonts/            # Font files
        └───test.ttf

UI Kit Usage

Typography

Use standard HTML heading tags (<h1> to <h6>) and paragraph tags (<p>). Utility classes like .small can be applied for smaller text.

Grid System

Utilize the .container, .row, and .col-* classes for responsive layouts. Breakpoints are defined in src/scss/_variables.scss.

<div class="container">
  <div class="row">
    <div class="col-12 col-md-6">
      <!-- Content -->
    </div>
    <div class="col-12 col-md-6">
      <!-- Content -->
    </div>
  </div>
</div>

Buttons

Apply the .btn base class along with contextual classes like .btn-primary, .btn-secondary, etc.

<button class="btn btn-primary">Primary Button</button>
<a href="#" class="btn btn-success">Success Link</a>

Utility Classes

Various utility classes are available for common styling needs:

• Spacing: m-1, pt-3, px-auto, etc. (for margin and padding)
• Text Alignment: text-left, text-center, text-right
• Display: d-block, d-inline-block, d-flex
• Colors: text-primary, bg-dark, etc.

SVG Icons

SVG icons from src/icons are compiled into a sprite and injected into your HTML. Use them with the <svg><use> pattern:

<svg class="icon" width="24" height="24"><use xlink:href="#clock"></use></svg>

Data Management

Twig templates can access global data from src/data/global.json and page-specific data from src/data/<template-name>.json (e.g., src/data/about.json for about.twig). Page-specific data will override global data if keys conflict.

Example in Twig:

<h1>{{ global.welcomeMessage }}</h1>
<p>{{ pageTitle }}</p>

Testing

Jest is configured to run unit tests for JavaScript files. The test environment is set to jsdom to simulate a browser environment.

To run tests:

npm test

Contributing

Feel free to contribute to this project by submitting issues or pull requests.