Spark: A TOML-Based Project Initializer

Spark is a powerful and flexible project initializer designed to simplify your workflow. Using a TOML-based configuration, Spark allows you to quickly create project directories and files based on predefined templates. Whether you're a developer looking for consistency or speed, Spark has you covered.

Features:

• TOML-based templates for structured project creation.
• Support for environment variables and dotenv files.
• Dynamic placeholders and custom functions for template customization.
• Constant values from configuration
• JSON Support to automate user input
• Integration with Git for version control setup.
• Liquid templating support for advanced customization.
• And more..

Warning

This project was previously named idkmng. Some issues and references may still use the old name.

---

Table of Contents

• Why Spark? 🧠
• Installation
• Creating Templates 📜
• Dynamic Placeholders and Functions
• Environment Variables ⚙️
• Template Options
• Git Integration 🐙
• Example Templates
  • Neovim Plugin
  • Jekyll Blog Post
  • Browser Extension
• JSON Integration
• Liquid Templating Support 🧪
• Automated Template Generation 🚀
• Neovim Plugin

---

Why Spark? 🧠

Creating projects often involves repetitive tasks, such as setting up directories and boilerplate files. Spark streamlines this process by allowing you to define templates in TOML. For instance, to create a browser extension, simply run:

spark browser_extension

And voilà! Your project is ready for the first commit. Spark's flexibility means you can define multiple templates for various use cases, ensuring your projects always start with the structure you need.

---

Installation

Via Cargo (Requires Rust 🦀)

Install Spark directly from the GitHub repository:

cargo install --git https://github.com/pwnxpl0it/spark

Precompiled Binaries

Download a precompiled binary from the Releases page:

sudo tar -xzf spark-<VERSION>.tar.gz -C /usr/local/bin

Replace <VERSION> with the desired release version.

Verify installation by running:

spark --version

---

Creating Templates 📜

To create a new template, run:

spark new

This will generate a basic template file in ~/.config/spark/templates/<TEMPLATE_NAME>.toml.

The template structure is as follows:

[info]
name = "Template Name"
description = "Template Description"
author = "Your Name"

[[files]]
path = "file1.txt"
content = """
Content of file 1
"""

[[files]]
path = "file2.txt"
content = """
Content of file 2
"""

Tip

Tip: The [info] section is optional and can be removed.

Placeholder Format

Use {{$PLACEHOLDER}} for dynamic content replacement. Common placeholders include:

placeholder	Value	Example
PROJECTNAME	Asks for project name
CURRENTDIR	Current directory	pwd=/foo/bar => bar
HOME	Home directory	/home/user/
YYYY	Current Year in YYYY format	2024
YY	Current Year in YY format	24
MM	Current Month	2
DD	Current Day	24
NOW	Current date and time	2024-02-23 22:22:38.151417626 +00:00
NOW_UTC	Current date and time in UTC	2024-02-23 22:21:17.897444668 UTC

Dynamic Placeholders and Functions

Enhance templates with functions for additional customization. Functions follow the format {{$PLACEHOLDER:FUNCTION}}.

Supported Functions

Function	Description	Example
read	Prompts for user input	{{$VAR:read}}

Example template snippet:

[[files]]
path = "example.txt"
content = """
User input: {{$USER_INPUT:read}}
"""

---

Environment Variables ⚙️

Spark supports placeholders that map to environment variables. You can also use .env files for placeholder substitution.

Example .env file:

DB_HOST=localhost
DB_PORT=5432

Example template:

[[files]]
path = "config.py"
content = """
DB_HOST = "{{$DB_HOST}}"
DB_PORT = "{{$DB_PORT}}"
"""

Generated file:

DB_HOST = "localhost"
DB_PORT = "5432"

---

Template Options

Template options in spark provide a way to customize the project setup by allowing predefined variables or settings within the template. These options are defined in the TOML configuration file of the template and can control various aspects of the template generation process.

Option	Description	Example
git	Initialize Git repository in the project directory	git=true
project_root	Set the project name to a constant value or ask for user input	project_root="new_project", project_root="{{$PROJECTNAME}}"
use_liquid	Enable/Disable Liquid templating in the template	use_liquid=true
use_json	Embed JSON in the template	use_json='{"id": 1, "name": "John"}'

Git Integration 🐙

Initialize a Git repository during project creation:

spark /path/to/template --git

Alternatively, include Git setup in the template:

[options]
git = true
#project_root = "my_project"
project_root="{{$PROJECTNAME}}" # will prompt for the project name but you can set this to constant value

---

Example Templates

Example Templates

Here are a few examples:

Neovim Plugin [Click to expand]

[options]
git=true
project_root="{{$PROJECTNAME}}"
 
[info]
name = "Neovim Plugin"
description = "A template for nvim plugin"
author = "Mohamed Tarek @pwnxpl0it"

[[files]]
path="{{$PROJECTNAME}}/lua/{{$PROJECTNAME}}/init.lua"
content="""
local M = {}

M.config = {}

M.setup = function ()
   if config ~= nil then
        M.config = config
    end

end

return M
"""

[[files]]
path="{{$PROJECTNAME}}/plugin/init.lua"
content="""
require("{{$PROJECTNAME}}")
"""

Jekyll new blogpost [Click to expand]

I use this template to create a new post in my blog directly from CLI,This one here uses more keywords and includes a private BLOGPATH placeholder that it's value is loaded from config file.

[info]
name = "new_post"
description = "New jekyll post"
author = "Mohamed Tarek @pwnxpl0it"

[[files]]
path="{{$BLOGPATH}}/_posts/{{$YYYY}}-{{$MM}}-{{$DD}}-{{$blogtitle:read}}.markdown"
content="""
---
layout: post
title: "{{$blogtitle}}"
date: {{$NOW_UTC}}
tags: {{$Tags:read}}
---

"""

Browser (Chrome) Extension [Click to expand]

This one is just for creating a really BASIC chrome extension.

[options]
git=true
project_root="{{$PROJECTNAME}}"

[info]
name = "browser_extension"
description = "A Template for creating a browser extension"
author = "Mohamed Tarek @pwnxpl0it"
refrence= "https://developer.chrome.com/docs/extensions/mv3/manifest/"

[[files]]
path="{{$PROJECTNAME}}/manifest.json"
content="""
{
  "manifest_version": 3,
  "name":"{{$PROJECTNAME}}",
  "version": "1.0.1",
  "content_scripts":[
    {
     "matches":["<all_urls>"],
     "js":["content.js"]
    }
  ]
}
"""

[[files]]
path="{{$PROJECTNAME}}/content.js"
content="""
console.log("Hello world!")
"""

Info section can have any additional values, it won't get printed but maybe usefull when sharing the template or just as a reference for docs like I did here

---

JSON Integration

You can use json to replace placeholders in your template, spark will automatically load values from a json file and replace them automatically

Spark uses JSON Query language to load values from json nodes.

Here is an example:

{
	"user": {
		"id": "12345",
		"name": "John Doe",
		"email": "[email protected]"
	},
	"status": ["200 OK"]
}

Example template:

[[files]]
path="test"
content="""
User ID: {{$.user.id}}
User Name: {{$.user.name}}
User Email: {{$.user.email}}
Response Status: {{$.status[0]}}
"""

$ spark template --json test.json

Output:

$ cat test

User ID: 12345
User Name: John Doe
User Email: [email protected]
Response Status: 200 OK

Note

Although this is a cool feature to automate user inputs, It comes with performance costs Why?

Liquid Templating Support 🧪

Spark now supports Liquid templating alongside its own custom syntax. This allows you to benefit from Liquid's logic (loops, conditionals) while continuing to use spark's powerful keyword replacement.

Example:

[[files]]
path = "output.txt"
content = """
{% for i in (1..5) %}
Example! {{ i }} {{ "{{$file:read}}" | append: ".html" }}
{% endfor %}
"""

• Spark replaces {{$file:read}} with user input.
• Liquid handles loops and string manipulation.

Result:

Example! 1 ff.html
Example! 2 ff.html
Example! 3 ff.html
Example! 4 ff.html
Example! 5 ff.html

With this integration, you can create dynamic and flexible templates that combine the strengths of both spark and Liquid.

Tip

Liquid is enabled by default in templates. To disable it, set use_liquid=false in the template options. or use --no-liquid flag when running spark

Automated Template generation 🚀

Also there is one more time saving way! if you have some files in /foo/bar/ you can just run spark init and it will create a template for you with directory name bar.toml and it will have all your files in it! 🌸

$ tree
.
├── lua
│   └── test123
│       └── init.lua
└── plugin
    └── init.lua

4 directories, 2 files

$ spark init
Creating Template: test123.toml

$ cat test123.toml

[[files]]
path = 'plugin/init.lua'
content = '''
require("test123")
'''

[[files]]
path = 'lua/test123/init.lua'
content = '''
local M = {}

M.config = {}

M.setup = function ()
   if config ~= nil then
        M.config = config
    end

end

return M
'''

Config Keywords ⚙️

You can have your own Keywords for spark to replace with desired values! Spark finds them stored in $HOME/.config/spark/config.toml Or the config path you specified using -c/--config option 🦀

[Keywords]
AUTHOR = "Mohamed Tarek"
USERNAME = "@pwnxpl0it"
GITHUB = "https://github.com/pwnxpl0it"
#etc .....

👾 Neovim plugin (spark.nvim)

I wrote a neovim plugin that makes it a way easier, Check it out spark.nvim.