Quick Reference Guide

Get started with Scaffoldfy in minutes! This guide provides quick examples and essential commands to help you understand and use the library without reading all the documentation.

Table of Contents

Basic Usage

🚀 Quick Start with npx (No Installation Required)


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

# Preview changes first (recommended)
npx @pixpilot/scaffoldfy  --config ./config.json --dry-run

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

CLI

Installation (Optional)

Optional: You can use npx (above) without installing anything. Or install for repeated use:


# Or install locally in your project
npm install --save-dev @pixpilot/scaffoldfy


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

# Preview changes without applying (dry-run mode)
scaffoldfy  --config ./config.json --dry-run

# With TypeScript task file
scaffoldfy --config ./my-tasks.ts

Programmatic API

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

// Run tasks
await runWithTasks(tasks, {
  dryRun: false,
  force: false,
  configFilePath: './config.json',
});

Essential Task Types

1. Write Files - Create or overwrite files

{
  "id": "create-readme",
  "name": "Create README",
  "type": "write",
  "config": {
    "file": "README.md",
    "template": "# \n\nAuthor: "
  }
}

2. Update JSON - Modify JSON files (merge or set values)

{
  "id": "update-package",
  "name": "Update package.json",
  "type": "update-json",
  "config": {
    "file": "package.json",
    "updates": {
      "name": "",
      "version": "1.0.0",
      "author": ""
    }
  }
}

3. Copy Files - Copy files or directories

{
  "id": "copy-template",
  "name": "Copy template files",
  "type": "copy",
  "config": {
    "source": "templates/",
    "destination": "src/",
    "overwrite": true
  }
}

4. Execute Commands - Run shell commands

{
  "id": "install-deps",
  "name": "Install dependencies",
  "type": "exec",
  "config": {
    "command": "npm install"
  }
}

5. Delete Files - Remove files or directories

{
  "id": "cleanup",
  "name": "Remove temp files",
  "type": "delete",
  "config": {
    "paths": ["temp/", "*.log"]
  }
}

Quick Prompt Examples

Text Input

{
  "id": "projectName",
  "type": "input",
  "message": "Project name",
  "required": true,
  "default": "my-project"
}

Confirmation (Yes/No)

{
  "id": "useTypeScript",
  "type": "confirm",
  "message": "Use TypeScript?",
  "default": true
}

Single Selection

{
  "id": "framework",
  "type": "select",
  "message": "Choose a framework",
  "choices": ["React", "Vue", "Angular", "Svelte"]
}

Multiple Selection

{
  "id": "features",
  "type": "multiselect",
  "message": "Select features",
  "choices": ["ESLint", "Prettier", "Jest", "Husky"]
}

Dynamic Default from Command

{
  "id": "author",
  "type": "input",
  "message": "Author name",
  "default": {
    "type": "exec",
    "value": "git config --get user.name"
  }
}

Common Patterns

Complete Minimal Config

{
  "$schema": "https://unpkg.com/@pixpilot/scaffoldfy/schema",
  "prompts": [
    {
      "id": "projectName",
      "type": "input",
      "message": "Project name",
      "required": true
    }
  ],
  "tasks": [
    {
      "id": "create-readme",
      "name": "Create README",
      "type": "write",
      "config": {
        "file": "README.md",
        "template": "# \n\nA new project."
      }
    },
    {
      "id": "init-git",
      "name": "Initialize Git",
      "type": "git-init"
    }
  ]
}

Conditional Task Execution

{
  "id": "setup-typescript",
  "name": "Setup TypeScript",
  "type": "write",
  "enabled": {
    "type": "condition",
    "value": "useTypeScript === true"
  },
  "config": {
    "file": "tsconfig.json",
    "template": "{\"compilerOptions\": {\"strict\": true}}"
  }
}

Alternative formats:

{
  "enabled": {
    "type": "exec",
    "value": "git rev-parse --is-inside-work-tree" // Execute command
  }
}

Task with Dependencies

{
  "id": "install-deps",
  "name": "Install dependencies",
  "type": "exec",
  "dependencies": ["update-package"],
  "config": {
    "command": "npm install"
  }
}

Using Variables (No User Input)

{
  "variables": [
    {
      "id": "currentYear",
      "value": {
        "type": "exec",
        "value": "date +%Y"
      }
    }
  ],
  "tasks": [
    {
      "id": "add-license",
      "name": "Add LICENSE",
      "type": "write",
      "config": {
        "file": "LICENSE",
        "template": "Copyright  "
      }
    }
  ]
}

# Run with default config
scaffoldfy

# With custom config file
scaffoldfy --config ./config.json

# Dry run (preview changes)
scaffoldfy --dry-run

# Show version
scaffoldfy --version

# Show help
scaffoldfy --help

Options

--config <path>    # Path to config file (JSON or TypeScript, default: ./configs-tasks.json)
--dry-run          # Preview changes without applying them
--no-validate      # Skip schema validation
--force            # Force execution even if checks fail

Programmatic API

Basic Usage

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

// Run with tasks array
await runWithTasks(tasks, {
  dryRun: false,
  force: false,
  configFilePath: './configs-tasks.json',
});

With Options

await runWithTasks(tasks, {
  dryRun: true, // Preview mode
  force: false, // Don't force execution
  configFilePath: './config.json',
  variables: [], // Optional global variables
  prompts: [], // Optional global prompts
});

Error Handling

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

try {
  await runWithTasks(tasks, {
    dryRun: false,
    configFilePath: './configs-tasks.json',
  });
  console.log('✅ Tasks completed successfully!');
} catch (error) {
  console.error('❌ Task execution failed:', error.message);
}

Quick Tips

💡 Best Practices

  1. Always use --dry-run first to preview changes
  2. Use descriptive task IDs for better error messages
  3. Set required: false for optional tasks, or use conditional required with { "type": "condition", "value": "expression" } for dynamic behavior
  4. Use the typed format for enabled and required fields: { "type": "condition"|"exec", "value": "..." }
  5. Use dependencies to ensure tasks run in the correct order
  6. Validate your configuration with the JSON schema for IntelliSense

🔥 Common Gotchas

📦 Configurations File Formats

Scaffoldfy supports multiple formats:

Next Steps

Learn More

Example Configurations

Check the examples/ directory for complete working configurations:

Need Help?

Ready to start? Run your first template:

scaffoldfy --config scaffoldfy.json --dry-run