Project Template Generator

This CLI tool allows you to generate new projects from customizable templates. It provides an interactive interface for selecting templates and inputting project-specific variables, with support for both local and remote generation via GitHub.

Features

Local Mode: Interactive project generation with template selection
Remote Mode: Automatic generation + GitHub repository creation
File Configuration: YAML and JSON support for automation
Smart Validation: Project and package names with appropriate validation
Automatic Installation: Dependency installation after generation
Dynamic Replacement: Customizable variables in templates
GitHub Integration: Automatic repository creation with initial push

Installation

Ensure you have Rust and Cargo installed on your system.

Clone this repository:

git clone [repository_url]
cd [repository_name]

Build the project:
```
cargo build --release
```

Available CLI Arguments

Options:
  -d, --debug                    Enable debug output
  -f, --config <CONFIG>          Path to configuration file (YAML or JSON)
  -c, --category <CATEGORY>      Template category
  -n, --template <TEMPLATE>      Template name
      --remote                   GitHub mode (generation + repository creation)
      --token <TOKEN>           GitHub token for remote mode
  -h, --help                    Show help
  -V, --version                 Show version

Quick Start - Template Testing

Pour tester rapidement vos templates, utilisez les commandes Make automatisées :

Commandes disponibles

# Afficher les templates disponibles et les commandes
make show-templates

# Générer une configuration pour le template Library
make config-library

# Générer une configuration pour le template Astro
make config-astro

# Tester le template Library (génère config + lance le test)
make test-library

# Tester le template Astro (génère config + lance le test)
make test-astro

# Nettoyer les fichiers de configuration de test
make clean-configs

Script automatique de configuration

Le script scripts/generate-config.sh analyse automatiquement les template_config.json et génère des fichiers de configuration prêts à l'emploi :

# Générer une configuration pour un template spécifique
./scripts/generate-config.sh library
./scripts/generate-config.sh astro

# Avec un nom de fichier personnalisé
./scripts/generate-config.sh library ma-config-custom.yaml

Avantages :

✅ Extraction automatique des placeholders depuis template_config.json
✅ Valeurs par défaut intelligentes selon le type de template
✅ Noms uniques avec timestamp pour éviter les conflits
✅ Configuration complète prête à l'utilisation

Tutorial 1: Remote Mode (GitHub)

Remote mode generates a project locally then automatically creates a GitHub repository with the code.

Prerequisites

GitHub Token: You must have a GitHub token with appropriate permissions
Configuration File: A YAML or JSON file is required
Environment Variables: Optional, can be used instead of the --token flag

File Configuration

Create a configuration file (e.g., config.yaml):

# Required configuration
project_name: "my-awesome-project"         # Project name (used for folder)
name: "@myorg/my-awesome-project"         # Package name (for package.json, etc.)
description: "Description of my project"  # GitHub repository description

# Template configuration
template_category: "apps"                  # Category: "apps", "packages", or "utils"
template_name: "nextjs-app"               # Specific template name

# Additional variables (optional, depends on template)
author: "My Name"
license: "MIT"
version: "1.0.0"
keywords: "nextjs,react,webapp"

Environment Variables

You can set your GitHub token in the environment:

export GITHUB_TOKEN="ghp_your_token_here"

Commands

Option 1: With token as argument

cargo run -- --remote --config config.yaml --token ghp_your_token_here

Option 2: With environment variable

export GITHUB_TOKEN="ghp_your_token_here"
cargo run -- --remote --config config.yaml

Automatic Process

When you execute the command, the tool:

✅ Reads your configuration file
✅ Validates required data
✅ Generates the project in a temporary folder
✅ Replaces all variables in template files
✅ Installs dependencies (npm, pnpm, etc.)
✅ Asks for the GitHub repository name (default: project name)
✅ Creates the GitHub repository in the organization
✅ Initializes Git, makes initial commit and pushes code
✅ Cleans up temporary folder
✅ Displays the new repository URL

Complete Example

# 1. Create the config file
cat > my-project.yaml << EOF
project_name: "portfolio-client"
name: "@nextnode/portfolio-client"  
description: "Modern portfolio site with Next.js"
template_category: "apps"
template_name: "nextjs-app"
author: "NextNode Team"
license: "MIT"
version: "0.1.0"
EOF

# 2. Execute remote generation
export GITHUB_TOKEN="ghp_your_personal_token"
cargo run -- --remote --config my-project.yaml

# 3. The tool will ask:
# > Project name: portfolio-client
# > Do you want to use the project name as the repository name? (Y/n)

Tutorial 2: Local Mode (All Possibilities)

Local mode offers several generation options based on your needs.

Option 1: Complete Interactive Mode

The simplest method to get started:

cargo run

Interactive process:

Template selection from a list
Project name input (automatic validation)
Package name input (automatic validation)
Custom variables input according to template
Generation in parent folder (../)
Automatic dependency installation

Example session:

? Select a template: › nextjs-app (apps)
? Enter value for project_name: › my-new-site
? Enter value for name: › @myorg/my-new-site
? Enter value for description: › My modern website
? Enter value for author: › My Name
✓ Project generated successfully!
✓ Dependencies installed successfully!

Option 2: Semi-Automatic Mode with Configuration

Use a config file but stay local:

cargo run -- --config config.yaml

Advantages:

No manual interaction
Reproducible and scriptable
Ideal for automation

Configuration file example:

project_name: "my-local-project"
name: "@myorg/my-local-project"
description: "Automatically generated project"
template_category: "packages"
template_name: "library"
author: "Developer"
license: "Apache-2.0"
version: "0.1.0"
# Custom variables according to template
main_export: "index.ts"
typescript: "true"

Option 3: Targeted Mode with Arguments

Directly specify the desired template:

cargo run -- --category apps --template nextjs-app

Process:

Pre-selected template
Interactive input only for variables
Immediate generation

Option 4: Debug Mode

To diagnose or understand the process:

cargo run -- --debug --config config.yaml

Information displayed:

Configuration file parsing
Extracted variables and their values
Processed files and replacements made
Dependency installation steps
Details of each operation

Option 5: Advanced Combinations

Partial configuration + interaction

# config-partial.yaml
project_name: "base-project"
template_category: "apps"
template_name: "react-app"
# Other variables will be asked interactively

cargo run -- --config config-partial.yaml

Debug with specific template

cargo run -- --debug --category packages --template library

Available Templates and Categories

Supported categories:

apps: Complete applications (Next.js, React, etc.)
packages: NPM libraries and packages
utils: Development utilities and tools

Templates Repository: You can find all available templates at: https://github.com/NextNodeSolutions/utils_project-templates

Template structure:

templates/
├── apps/
│   ├── nextjs-app/
│   │   ├── template_config.json
│   │   ├── package.json
│   │   ├── src/
│   │   └── ...
│   └── react-app/
├── packages/
│   └── library/
└── utils/
    └── cli-tool/

Available System Variables

All these variables can be used in your templates:

{{project_name}}: Project name (validated: lowercase, hyphens, underscores)
{{name}}: Package name (validated: npm standard format)
{{description}}: Project description
{{author}}: Project author
{{license}}: License type
{{version}}: Initial version
{{keywords}}: Keywords (transformed to array for JSON)

Template Configuration

Each template contains a template_config.json:

{
  "files_to_replace": [
    "package.json",
    "README.md", 
    "src/config.ts"
  ],
  "replacements": [
    {
      "name": "project_name",
      "key": "name", 
      "value": "{{project_name}}",
      "type": "string"
    },
    {
      "name": "keywords",
      "key": "keywords",
      "value": "{{keywords}}",
      "type": "array"
    }
  ]
}

Output Directory

Local Mode: Projects are generated in ../project-name/

Structure after generation:

../
├── my-new-project/
│   ├── package.json        # Variables replaced
│   ├── README.md          # Variables replaced
│   ├── src/
│   ├── node_modules/      # Dependencies installed
│   └── ...

Environment Variables Configuration

GitHub Token

For remote mode, you can use:

# Option 1: Environment variable
export GITHUB_TOKEN="ghp_your_token"

# Option 2: .env file (if supported)
echo "GITHUB_TOKEN=ghp_your_token" >> .env

# Option 3: CLI argument
cargo run -- --remote --token ghp_your_token --config config.yaml

Global Debug

# Enable debug for all operations
export DEBUG=1
cargo run

Use Case Examples

1. Developing a new webapp

# Complete interactive mode
cargo run
# Select: nextjs-app (apps)
# Fill in the requested variables

2. Creating an NPM library

# With predefined configuration
cat > lib-config.yaml << EOF
project_name: "utils-math"
name: "@myorg/utils-math"
description: "Reusable mathematical utilities"
template_category: "packages"
template_name: "library"
author: "My Team"
license: "MIT"
EOF

cargo run -- --config lib-config.yaml

3. Generation + GitHub Deployment

# Remote mode with repository creation
export GITHUB_TOKEN="ghp_your_token"
cargo run -- --remote --config production-config.yaml

4. Development with debugging

# See all process details
cargo run -- --debug --category apps --template nextjs-app

Validation and Security

Project names: Strict validation (lowercase, letters, numbers, hyphens, underscores)
Package names: NPM standard format validation
GitHub tokens: Never displayed in plain text, secure handling
Temporary files: Automatic cleanup after remote generation
Permissions: Rights verification before repository creation

Troubleshooting

Common Errors

"GitHub token is required"

export GITHUB_TOKEN="your_token"
# or
cargo run -- --token your_token --remote --config config.yaml

"Config file is required for remote mode"

# Remote mode always requires a config file
cargo run -- --remote --config your-config.yaml

"Failed to parse config file"

# Check YAML/JSON syntax
cargo run -- --debug --config your-config.yaml

"Template not found"

# Check available categories and templates
cargo run -- --debug

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the GPL-3.0-only License.

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
.vscode		.vscode
scripts		scripts
src		src
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
Makefile		Makefile
README.md		README.md
config-astro-20250927.yaml		config-astro-20250927.yaml
config-library-20250927.yaml		config-library-20250927.yaml
config.example.yaml		config.example.yaml

Folders and files

Latest commit

History

Repository files navigation

Project Template Generator

Features

Installation

Available CLI Arguments

Quick Start - Template Testing

Commandes disponibles

Script automatique de configuration

Tutorial 1: Remote Mode (GitHub)

Prerequisites

File Configuration

Environment Variables

Commands

Option 1: With token as argument

Option 2: With environment variable

Automatic Process

Complete Example

Tutorial 2: Local Mode (All Possibilities)

Option 1: Complete Interactive Mode

Option 2: Semi-Automatic Mode with Configuration

Option 3: Targeted Mode with Arguments

Option 4: Debug Mode

Option 5: Advanced Combinations

Partial configuration + interaction

Debug with specific template

Available Templates and Categories

Available System Variables

Template Configuration

Output Directory

Environment Variables Configuration

GitHub Token

Global Debug

Use Case Examples

1. Developing a new webapp

2. Creating an NPM library

3. Generation + GitHub Deployment

4. Development with debugging

Validation and Security

Troubleshooting

Common Errors

Contributing

License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages