@pixpilot/scaffoldfy

A flexible and powerful task automation utility for project setup, cleanup, and configuration.

Features

• 🔄 9 Task Types - update-json, template, regex-replace, replace-in-file, delete, conditional-delete, rename, git-init, exec
• 🧩 Template Inheritance - Extend base templates for code reuse
• 🔍 Dry-Run Mode with Diff - Preview exact changes before applying
• 🔌 Plugin System - Create custom task types and lifecycle hooks
• 💬 Interactive Prompts - Collect user input with input, select, confirm, number, and password prompts
• � Variables - Define reusable values from static or executable sources without user interaction
• �📦 JSON/TypeScript Config - Define tasks in JSON or TypeScript files
• 🔗 Task Dependencies - Ensure tasks run in the correct order
• ✅ Type-Safe - Full TypeScript support with JSON schema validation
• 🎯 Template Variables - Use {{variable}} syntax for dynamic configuration
• 📝 Handlebars Support - Advanced templating with conditionals, loops, and helpers
• ⚡ CLI & Programmatic - Use as a command-line tool or import as a library

Installation

pnpm add @pixpilot/scaffoldfy

Quick Start

CLI Usage

# Basic usage with default task file
scaffoldfy

# With custom tasks file
scaffoldfy --tasks-file ./my-tasks.json

# TypeScript tasks file
scaffoldfy --tasks-ts ./my-tasks.ts

# Preview changes (dry run)
scaffoldfy --dry-run

# Force re-initialization
scaffoldfy --force

Or run without installing using npx:

# Basic usage with default task file
npx @pixpilot/scaffoldfy

# With custom tasks file
npx @pixpilot/scaffoldfy --tasks-file ./my-tasks.json

# TypeScript tasks file
npx @pixpilot/scaffoldfy --tasks-ts ./my-tasks.ts

# Preview changes (dry run)
npx @pixpilot/scaffoldfy --dry-run

# Force re-initialization
npx @pixpilot/scaffoldfy --force

CLI Options

Programmatic API

import { runWithTasks } from '@pixpilot/scaffoldfy';

await runWithTasks(tasks, {
  dryRun: false,
  force: false,
  tasksFilePath: './my-tasks.json',
});

Task Types

9 built-in task types for common operations:

📖 Complete Task Types Reference →

Interactive Prompts

Collect custom user input directly in your task definitions:

{
  "id": "setup",
  "prompts": [
    {
      "id": "projectName",
      "type": "input",
      "message": "What is your project name?",
      "required": true,
      "global": true
    },
    {
      "id": "useTypeScript",
      "type": "confirm",
      "message": "Use TypeScript?",
      "default": true
    }
  ],
  "config": {
    "file": "package.json",
    "updates": {
      "name": "{{projectName}}"
    }
  }
}

Supported prompt types: input, password, number, select, confirm

Global prompts: Mark prompts with "global": true to share values across all tasks

💬 Full Prompts Guide → | 📋 Quick Reference →

Template Variables

Use {{variable}} syntax anywhere in your task configs:

{
  "updates": {
    "name": "{{projectName}}",
    "author": "{{author}}",
    "repository": "{{repoUrl}}"
  }
}

All variables come from prompts: Define prompts with "global": true to create variables available across all tasks.

Example: {{projectName}}, {{author}}, {{repoUrl}}, {{port}}, etc.

Handlebars Templates

Create powerful file templates with Handlebars support. Files with .hbs extension automatically use Handlebars templating:

{
  "id": "readme-from-template",
  "name": "Generate README",
  "type": "template",
  "config": {
    "file": "README.md",
    "templateFile": "templates/readme.hbs"
  }
}

Automatic detection: Any template file ending in .hbs uses Handlebars. Other files use simple {{variable}} interpolation.

Template file (templates/readme.hbs):

#
{{projectName}}

{{#if description}}
  >
  {{description}}
{{else}}
  > A modern TypeScript project
{{/if}}

## Features

{{#each features}}
  -
  {{this}}
{{/each}}

{{#if author}}
  ## Author

  {{author}}
{{/if}}

Key features:

• File-based only: Handlebars is only supported for external template files (.hbs extension)
• Automatic detection: No configuration needed - just use .hbs files
• Conditionals: {{#if}}, {{#unless}}, {{else}}
• Loops: {{#each}}, {{#with}}
• Comments: {{!-- This won't appear in output --}}

📝 Complete Handlebars Guide →

Template Inheritance

Extend base templates to promote code reuse:

{
  "extends": "./base-template.json",
  "tasks": [
    {
      "id": "custom-task",
      "name": "Custom Task",
      "description": "Project-specific setup",
      "required": true,
      "enabled": true,
      "type": "exec",
      "config": { "command": "echo 'Custom setup'" }
    }
  ]
}

You can extend multiple templates, override tasks by ID, and merge dependencies automatically.

🧬 Complete Inheritance Guide →

Dry-Run Mode with Diff Preview

Preview exactly what will change before applying:

scaffoldfy --tasks-file ./tasks.json --dry-run

See color-coded diffs for all file modifications, deletions, and additions.

🔍 Dry-Run Documentation →

Plugin System

Create custom task types for specialized operations:

import { createPlugin, registerPlugin } from '@pixpilot/scaffoldfy';

const myPlugin = createPlugin(
  'my-plugin',
  'custom-task',
  async (task, config, options) => {
    // Your custom logic here
  },
);

registerPlugin(myPlugin);

🔌 Complete Plugin Guide →

Task Dependencies

Control execution order:

{
  "tasks": [
    { "id": "clean", "type": "delete", "config": { "paths": ["dist"] } },
    {
      "id": "build",
      "dependencies": ["clean"],
      "type": "exec",
      "config": { "command": "pnpm build" }
    }
  ]
}

Example Configuration

Simple Example

{
  "tasks": [
    {
      "id": "update-package",
      "name": "Update package.json",
      "description": "Update repository information",
      "required": true,
      "enabled": true,
      "type": "update-json",
      "config": {
        "file": "package.json",
        "updates": {
          "name": "{{projectName}}",
          "author": "{{author}}"
        }
      }
    }
  ]
}

With Prompts

{
  "tasks": [
    {
      "id": "setup-project",
      "name": "Setup Project",
      "description": "Configure project settings",
      "required": true,
      "enabled": true,
      "type": "update-json",
      "prompts": [
        {
          "id": "projectName",
          "type": "input",
          "message": "Project name?",
          "required": true
        },
        {
          "id": "includeTests",
          "type": "confirm",
          "message": "Include tests?",
          "default": true
        }
      ],
      "config": {
        "file": "package.json",
        "updates": {
          "name": "{{projectName}}",
          "scripts": {
            "test": "{{includeTests ? 'vitest' : 'echo \"No tests\"'}}"
          }
        }
      }
    }
  ]
}

📁 More Examples →

Documentation

📚 Complete Documentation - Comprehensive guides and references

Quick Links

• Getting Started - Installation, CLI usage, and examples
• Task Types Reference - All 9 built-in task types
• Interactive Prompts - Collect user input
• Variables - Reusable values without user interaction
• Advanced Features - Conditional execution, global prompts, Handlebars
• Template Inheritance - Extend and compose templates
• Plugin System - Create custom task types
• Dry-Run Mode - Preview changes safely

Resources

• JSON Schema - For IDE autocomplete and validation
• Example Files - Sample task configurations

JSON Schema Support

Enable autocomplete and validation in your IDE:

{
  "$schema": "node_modules/@pixpilot/scaffoldfy/schema/tasks.schema.json",
  "tasks": []
}

Contributing

Contributions are welcome! Please check out the Contributing Guide for guidelines.

Development

# Install dependencies
pnpm install

# Run tests
pnpm test

# Run tests in watch mode
pnpm test --watch

# Build
pnpm build

# Type check
pnpm typecheck

License

MIT