npm package: @kleeinteractive/ktt
Description: KI Themer Tool - Static builder tool for theming
Author: Klee Group
Latest version: 1.0.5

# 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](#before-starting)
- 🚀 [Getting Started](#getting-started)
- 💻 [Configuration](#configuration)
- 🌍 [How to Use](#how-to-use)
- 📌 [What's New](#whats-new)
- ⚖️ [License](#license)

---

## <a name="before-starting">🚨 Before Starting</a>

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](https://www.npmjs.com/package/stylelint-scss)
    - [autoprefixer](https://www.npmjs.com/package/autoprefixer)
    - [clean-css](https://www.npmjs.com/package/clean-css)
    - [eslint](https://www.npmjs.com/package/eslint)
    - [esbuild](https://www.npmjs.com/package/esbuild)
    - [tailwindcss](https://www.npmjs.com/package/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.

---

## <a name="getting-started">🚀 Getting Started</a>

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`):

```bash
pnpm add -D @kleeinteractive/ktt
```

Create a default `ktt-config.json` file with <a name="configuration">configuration</a> options below.

## <a name="configuration">💻 Configuration</a>

### Example of a `ktt-config.json`

```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`

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

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

```javascript
/** @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"
}
```

## <a name="how-to-use">🌍 How to Use</a>

### | 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).

## <a name="whats-new">📌 What's New</a>

Check out the latest updates in the CHANGELOG.md.

## <a name="license">⚖️ License</a>

MIT (LICENSE file in the package)