Kuma is a powerful framework designed to generate scaffolds for any programming language, based on Go templates. It streamlines the process of setting up new projects by automating the creation of directories, files, and base code, ensuring consistency and saving valuable development time. Additionally, Kuma features a customizable TUI, providing an intuitive and efficient experience both for those creating scaffolds and those using them, making the process accessible and seamless for developers of all levels.
- Customize your project’s directory and file structures through Go templates.
- GitHub integration to download pre-defined templates from the community or for personal use via private repositories.
- Ability to create custom CLI/TUI command workflows through a YAML file using runs.
- Dynamic variable usage to be applied to templates. Variables can be extracted from a local YAML or JSON file or fetched from a public URL. They can also be obtained from user input during the execution of a run.
- Go version 1.23 or higher.
- Git installed and configured on your system.
-
Run the installation command:
go install github.com/arthurbcp/kuma/v2@latest
-
Add the Go bin directory to your PATH (if not already included):
Add the following line to your shell configuration file (
.bashrc
,.zshrc
, etc.):export PATH=$PATH:$(go env GOPATH)/bin
Then, reload your shell or run:
source ~/.bashrc
Replace
.bashrc
with your shell configuration file if necessary. -
Verify if $GOPATH is set correctly:
Run the following command to display the current value of $GOPATH:
echo $GOPATH
Expected Results:
-
If $GOPATH is set correctly: The command will return the path to the GOPATH directory, usually something like
/home/user/go
on Linux orC:Users/user/go
on Windows. -
If $GOPATH is empty or incorrect: You will need to set it by adding the following line to your shell configuration file:
export GOPATH=$(go env GOPATH)
Then, reload your shell or run:
source ~/.bashrc
Replace
.bashrc
with your shell configuration file if necessary.
-
-
Verify the installation:
kuma --help
You should see the Kuma CLI help, confirming that the installation was successful.
For Kuma to work, all framework-related files must be inside the .kuma
folder.
The framework uses a parser for Go templates divided into three file types:
YAML-formatted templates that contain the folder and file structure to be created.
# .kuma/base.yaml
# Global variables to be used in all templates.
global:
packageName: "{{.data.packageName}}"
# Directory and file structure to be generated
structure:
# main.go
main.go:
# The template that will be used as the basis for creating the main.go file
template: templates/Main.go
# Variables that will be used inside the template
data:
# msg: Hello, Kuma!
msg: "{{ .data.msg }}"
Individual Go templates for the files that will be created.
package main
import (
"fmt"
)
func main() {
// fmt.Print("Hello, Kuma!")
fmt.Println("{{ .data.msg }}")
}
A YAML file containing a sequence of actions that will be executed when calling a run
. It includes logs, terminal commands, HTTP calls, text input, and multiple-choice prompts, along with actions to create folders and files based on builders and templates.
all runs must be located within the .kuma/runs
directory
Check the full documentation here.
# Name of the run that will be executed as soon as the repository is obtained via the `kuma get` command
initial:
# Description of the run
description: "Initial run to set up the project"
# Steps that will be executed when the run is called
steps:
# Input action
- input:
label: "What is the package name of your project?"
out: packageName # Example: github.com/arthurbcp/kuma/v2-hello-world
# Another input action
- input:
label: "What message would you like to print?"
out: msg # Example: Hello, Kuma!
# Log message
- log: "Creating structure for {{.data.packageName}}" # Example: Creating structure for github.com/arthurbcp/kuma/v2-hello-world
# Create the project structure using the base.yaml builder
- create:
from: base.yaml
# Success log
- log: "Base structure created successfully!"
# Initialize the Go module
- cmd: go mod init {{.data.packageName}} # Example: go mod init github.com/arthurbcp/kuma/v2-hello-world
# Install dependencies
- cmd: go mod tidy
# Run the main.go file
- cmd: go run main.go # Example: Hello, Kuma!
-
This project uses sprout as a dependency, which contains hundreds of extremely useful functions for working with Go templates. In addition to our official functions, further enhancing your experience with our framework.
Sproute: Official Docs
Kuma functions: Read me
The create
command is used to create a scaffold based on the builders and templates inside the .kuma
folder and a JSON or YAML file containing the variables to replace in the templates.
kuma create --variables=swagger.json --project=. --from=base.yaml
Flags:
--variables
,-v
: Path or URL to the variables file.--project
,-p
: Path to the project where the scaffold will be created.--from
,-f
: Path to the YAML file with the structure and templates.
The exec
command is used to start the process of a run.
kuma exec --run=initial
Flags:
--run
,-r
: Name of the run to be executed.
Fetch templates and runs from a GitHub repository.
You can get templates from any repository using the command:
kuma get --repo=arthurbcp/kuma-typescript-rest-services
Or use one of our official templates with:
kuma get --template=kuma-typescript-rest-services
Flags:
--repo
,-r
: Name of the GitHub repository.--template
,-t
: Name of the official template.
- Hello World: A simple Hello World in Go.
- OpenAPI 2.0 TypeScript Services: Create a TypeScript library with typed services for all endpoints described in an Open API 2.0 file.
- Changelog Generator: Helper to write a good changelog to your project.
Contributions are welcome! Feel free to open issues or submit pull requests to improve Kuma.
-
Fork the repository.
-
Create a branch for your feature:
git checkout -b feature/my-new-feature
-
Commit your changes:
git commit -m "Add new feature"
-
Push to the branch:
git push origin feature/my-new-feature
-
Open a Pull Request.
This project is licensed under the MIT license. See the LICENSE file for more details.