configuration.md

Project configuration

A spackle project is defined by a spackle.toml file at the root directory. Below is a reference for the configuration file.

Field legend

{s} = slot environment ({{ }} will be replaced by slot values)

Global slots

Global slots are available in all slot environments (.j2 file contents, file names, {s} fields).

• _project_name string
  • The name of the project itself
• _output_name string
  • The name of the output directory

Project-level config

name string

The name of the project. This also sets the _project_name global slot, so keep that in mind. If this isn't set, the project name will be inferred from the directory name.

name = "my_cool_project"

ignore string[]

Files and directories to ignore when copying. These will be relative to the project directory.

ignore = [
    ".git"
]

slots table

Slots are defined by one or more [[slots]] table entries in the spackle.toml file.

[[slots]]
key = "slot_name"
type = "string"
name = "Slot name"
description = "A description of the slot"
default = "default value"

key string

The key of the slot in the project. This is the identifier you can use in slot environments to retrieve the value of the slot.

key = "slot_name"

type string

The data type of the slot. Can be one of the following:

• String
• Number
• Boolean

type = "String"

needs string[]

The slots that the slot depends on.

needs = ["some_slot", "other_slot"]

name string

The human-friendly name of the slot.

name = "Slot name"

description string

The human-friendly description of the slot.

description = "A description of the slot"

default string

The default value of the slot. The CLI will use the default value if one is not provided by the user (e.g. they press enter without typing anything).

For library consumers, is up to you to decide whether to use the default value or not. The generate function will not use the default value if the slot is not provided, and will instead error if a slot is not provided properly.

default = "default value"

hooks table

Hooks are defined by one or more [[hooks]] table entries in the spackle.toml file. Hooks are ran after the project is rendered and ran in the generated directory, and can be used to modify the project or enable specific functionality.

[[hooks]]
name = "create file"
command = ["touch", "new_file"]
optional = { default = true }
needs = ["foo"]
if = "{{foo}} != 'bar'"
name = "Create a new file"
description = "Create a new file called new_file"

Command sequences

To manage hook command sequences, create a single hook that runs a shell command, invoking your desired commands in sequence. For example:

[[hooks]]
key = "create_file"
command = ["bash", "-c", "touch new_file && chmod +x new_file"]

key string

The identifier for the hook.

command string[] {s}

The command to execute. The first element is the command and the rest are arguments. Accepts values from slots.

command = ["echo", "Hello {{ foo }}"]

default boolean

The default value of the hook. The CLI will use the default value if one is not provided by the user (e.g. they press enter without typing anything).

default = false

needs string[]

The items on which the hook depends. The hook will only be executed if all the dependencies are satisfied. A dependency is satisfied if the dependency is enabled and all of its own dependencies are satisfied.

A slot is considered enabled if it has a non-default value (default values include "", 0, and false for example).

Note: Because if is evaluated only on hook run time, it is not taken into account when determining satisfaction of needs.

needs = ["some_hook", "other_slot"]

if string {s}

The condition on which to execute the hook. Accepts values from slots.

if = "{{ foo }} != 'bar'"

Note: The if condition is evaluated directly before the hook is executed.

Dependencies on other hooks

If you want to run a hook only if another hook has already been run, you can use the hook_ran_{hook_key} variable.

if = "{{ hook_ran_other_hook }}"

name string

The name of the hook.

description string

A description for the hook.