Tateru CLI

Simple CLI static site builder tool with Twig.

---

✨ Features

• Lightweight CLI for generating static sites.
• Uses Twig.js templating engine for simplified markup.
• Has integrated custom Twig extensions (e.g., translations, sorting)
• Minifies output HTML.
• Simple integration with Gulp and other build tools via CLI.
• Configured via custom JSON configuration, allowing for extensive customization of build settings.
• Zero dependencies on complex frameworks.

---

📦 Install

Install Tateru CLI locally in your project:

npm i -D tateru-cli

Or install globally:

npm i -g tateru-cli

---

🚀 Usage

1. Create a config file tateru.config.json with your settings (see example in ./example/tateru.config.json).
2. Run the CLI command:

npx tateru-cli tateru.config.json

Or, if installed globally:

tateru-cli tateru.config.json

Example Usage

tateru-cli tateru.config.json --env prod

This generates the site with the prod environment settings.

Show help

To display usage details, run:

tateru-cli --help

or

npx tateru-cli --help

(Experimental) Integration with Gulp

You can use Tateru CLI within a Gulp task by executing it via child_process.exec:

/** @file tasks/tateru.js */

const { exec } = require('child_process');

module.exports = function tateru(cb) {
  return new Promise((resolve) => {
    exec('npx tateru-cli tateru.config.json', function (error, stdout, stderr) {

      if (error && stdout) {
        console.error(stdout);
      } else if (stdout) {
        console.info(stdout);
      }

      if (stderr) {
        console.error(stderr);
      }

      resolve(cb);
    })
  })
}

/** @file gulpfile.js */

const { series, parallel } = require('gulp');
const tateru = require('./tasks/tateru');

function build(cb) {
  return series(clean, parallel(css, tateru))(cb);
}

module.exports = {
    build,
    default: build,
};

---

⚙️ Configuration

The tateru.config.json file defines how Tateru CLI generates your static site. Below is a breakdown of the configuration structure:

Environment Settings

"env": {
    "dev": {
        "data": {
            "app": {
                "environment": "dev"
            }
        }
    },
    "prod": {
        "data": {
            "app": {
                "environment": "prod"
            }
        }
    }
}

Defines environment-specific variables (dev, prod).

• data: Overrides specific data in options.data, allowing for environment-based customization.

Global Options

"options": {
    "data": {
        "app": {
            "environment": "dev",
            "root": "/"
        },
        "title": "Tateru CLI Example",
        "domain": "https://www.example.com/"
    },
    "src": "src/twig",
    "ext": "dist"
}

• data: Global variables accessible in templates. For example, you can reference title in a Twig template using {{- title -}}.
• src: Path to source Twig files.
• ext: Output directory for compiled files.

Global Data in Templates

The final data available in Twig templates is composed by merging several configuration sources:

• options.data: Global data defined in the tateru.config.json file.
• env.[env].data: Environment-specific data (dev or prod).
• pages.[lang].[page].data: Page-specific overrides.
• href: Automatically generated URLs for each page.
• lang: The current language in use.

Example of referencing global data in a Twig template:

<h1>{{ title }}</h1>
<p>Environment: {{ app.environment }}</p>
<a href="{{ href.index }}">Home</a>

Translations

"translations": {
    "cs": {
        "src": "src/translations/cs.json",
        "ext": ""
    }
}

Defines translation files per language.

Pages Configuration

"pages": {
    "cs": {
        "index": {
            "data": {
                "page": "index",
                "title": "Index Page"
            },
            "src": "views/index.html.twig",
            "ext": "index.html",
            "minify": ["prod", "dev"]
        }
    }
}

• pages: Defines each page with its template source, output name, and optional minification settings.
• data: Page-specific variables that override global data in options.data.
• src: Path to the Twig template file for this page.
• ext: Output file name and extension.
• minify: Array specifying environments (prod, dev) where HTML minification should be applied.

For more complex configurations, refer to /example/tateru.config.json.

---

🛠 Custom Twig Extensions

📖 Translations

{{ trans('homepage.title') }}

🔀 Sort By

Example translation.json:

{
    "sort": [
        { "key": "x" },
        { "key": "a" },
        { "key": "k" },
        { "key": "c" },
        { "key": "b" }
    ]
}

Example index.html.twig:

<ul>
    {% for item in trans('sort')|sort_by('key') -%}
    <li>{{ item.key }}</li>
    {% endfor %}
</ul>

---

🔧 Development

To build the project:

npm run build

To clean the output directory:

npm run clean

To run an example build:

npm run example:build

To run an example production build:

npm run example:build:prod

To clean example output:

npm run example:clean

To run the CLI in development mode:

npm run dev

Test CLI help:

npm run dev:help

Test CLI version:

npm run dev:version

Test CLI with arguments:

npm run dev:args

Test CLI error:

npm run dev:error

Test CLI arguments error:

npm run dev:args-error

Test CLI argument with missing value error:

npm run dev:missing-arg-error

Run unit tests:

npm test

---

🤝 Contributing

Want to contribute? Feel free to open an issue or pull request on GitHub! 🚀

1. Fork the repo
2. Create a new branch (git checkout -b feature-branch)
3. Make your changes
4. Commit the changes (git commit -m "Add new feature")
5. Push to the branch (git push origin feature-branch)
6. Open a pull request 🚀

---

📜 License

MIT License © 2025 Daniel Sitek