KTT - KI Themer Tool

KTT is a static theming tool based on the Gulp task runner.

Its purpose is to build SASS, JavaScript, or Tailwind CSS from and to specified locations, following recommended best practices for linting and optimization.

📢 Warning: A specific Node.js version is required for each version of KTT to ensure proper functionality and compatibility with all its dependencies. If you run a KTT command with an unsupported Node.js version, a reminder message will be shown.

Please note: we do not offer support for external needs, and updates are provided on a best-effort basis — but the tool is available for anyone to use.

Table of Contents

• 🚨 Before Starting
• 🚀 Getting Started
• 💻 Configuration
• 🌍 How to Use
• 📌 What's New
• ⚖️ License

🚨 Before Starting

1. Be aware that KTT includes the following packages for the assets in your KTT configuration (see the full list of dependencies in the package.json file):

   • stylelint-scss
   • autoprefixer
   • clean-css
   • eslint
   • esbuild
   • tailwindcss
   • ...

2. Unless you have a specific reason not to, we recommend placing KTT in the top-level folder of your application — usually one directory above the app root.

🚀 Getting Started

Use the following command to add the KTT as a dependency of your project (note that you can use npm or yarn instead of pnpm):

pnpm add -D @kleeinteractive/ktt

Create a default ktt-config.json file with configuration options below.

💻 Configuration

Example of a ktt-config.json

{
    "entrypoints": [ // Add as many entrypoints as you want
        {
            "name": "example_theme_css",
            "path": "./web/themes/custom/example_theme",
            "compiler": "sass", // sass | js | tailwind
            "dir": {
                "src": "scss/",
                "dest": "css/" // OPTIONAL - if you don't set a "dest", assets will not be built, for instance, if you want this entrypoint to be lint-only
            },
            "files": ["example-theme-fonts.scss", "example-theme.scss"],
            "stylelint_config_path": ".stylelintrc.json", // OPTIONAL - override stylelint config
            "sass_config": {}, // OPTIONAL - add sass options (https://sass-lang.com/documentation/js-api/interfaces/options/) 
            "minify": {}, // OPTIONAL - override minify for this entrypoint
            "sourcemap": {}, // OPTIONAL - override sourcemap for this entrypoint
            "lint": {} // OPTIONAL - override lint for this entrypoint
        },
        {
            "name": "example_theme_js",
            "path": "./web/themes/custom/example_theme",
            "compiler": "js",
            "dir": {
                "src": "js/",
                "dest": "dist/" // OPTIONAL - remove dest if you choose not to build this entrypoint at all (to lint-only, for example)
            },
            "files": ["*.js"], // GLOB pattern allowed (beta)
            "esbuild_config": {}, // OPTIONAL - Only for 'js' entrypoints, you can extend or override the default KTT esbuild config with your own options from here (https://esbuild.github.io/api/)
            "eslint_config": {} // OPTIONAL - Only for 'js' entrypoints, you can extend or override the default KTT eslint config with your own options from here (https://www.npmjs.com/package/gulp-eslint-new)
        },
        {
            "name": "example_theme_tailwind",
            "path": "./themes/custom/example_theme",
            "compiler": "tailwind",
            "dir": {
                "src": "src/",
                "dest": "css/"
            },
            "files": ["my-tailwind-style.css"],
            "tailwind_config_path": "./example-theme-tailwind.config.js" // SPECIFIC - The relative path to the tailwind config file to use for this entrypoint, only works with tailwind as compiler
        }
    ],
    // OPTIONAL - override global minify, default values are:
    "minify": {
        "dev": false, 
        "prod": true 
    },
    // OPTIONAL - override global sourcemap, default values are:
    "sourcemap": {
        "dev": true, 
        "prod": false 
    },
    // OPTIONAL - override lint for this entrypoint, default values are:
    "lint": {
        "dev": true, 
        "prod": false,
        "failOnError": true
    }
}

Example of a .stylelintrc.json

{
  "extends": ["../node_modules/@kleeinteractive/ktt/.stylelintrc.json"],
  "rules": {
    "declaration-no-important": null
  }
}

Example of a example-theme-tailwind.config.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    "./web/themes/custom/**/*.twig",
  ],
  theme: {
    extend: {},
  },
  plugins: [], // Add your plugins as string w/o require(), e.g. "@tailwindcss/typography"
}

🌍 How to Use

| Command Options

The KTT creates a "ktt" command to perform operations based on your ktt-config.json and provided arguments.

Operations

• dev
• prod
• watch (equivalent to dev with build on save)
• lint (lint-only, no build at all)

Arguments

| Name | Value(s) | Description | |--------------|--------------|--------------| | --e | {entrypoint_name} | Target an entrypoint by its name (defined in ktt-config.json) | | --c | {compiler_name} | Target the entrypoints by compiler (sass, tailwind, js) | | --ctype | css or js | Target the entrypoints by compiler "type": css (sass, tailwind) or js | | --v, --version | N/A | Show the version of the KTT | | --h, --help | N/A | Display help information for available commands |

| Examples

• pnpm ktt prod: Execute the prod operation for all entrypoints in the ktt-config.json.
• pnpm ktt dev --ctype=css: Execute the dev operation for every entrypoint of the css compiler type (sass, tailwind).

📌 What's New

Check out the latest updates in the CHANGELOG.md.

⚖️ License

MIT (LICENSE file in the package)