Processors vs Plugins

Processors and plugins serve different purposes in CyanPrint. Understanding when to use each is key to effective template design.

Quick Comparison

Processors

Processors handle file transformation during generation.

When to Use

• Variable substitution in files
• Template engine processing (Eta, Handlebars)
• Code generation (GraphQL, Protobuf)
• File content transformation
• Custom file processing logic

How They Work

Example

return {
  processors: [{
    name: 'cyan/default',
    files: [
      { root: 'templates', glob: '**/*.md', exclude: [], type: GlobType.Template }
    ],
    config: {
      vars: { name: 'my-project' }
    }
  }]
};

Template file:

# var__name__

Welcome to var__name__!

Generated file:

# my-project

Welcome to my-project!

Plugins

Plugins handle post-generation actions after files are created.

When to Use

• Git repository initialization
• Dependency installation
• Running scripts
• External service integration
• IDE configuration
• File permissions

How They Work

Example

return {
  processors: [/* ... */],
  plugins: [
    {
      name: 'cyan/init-git',
      config: { commitMessage: 'Initial commit' }
    },
    {
      name: 'cyan/npm-install',
      config: { packageManager: 'pnpm' }
    }
  ]
};

Decision Flow

Common Patterns

Template with Variable Substitution

Use processor:

processors: [{
  name: 'cyan/default',
  files: [{ root: 'templates', glob: '**/*', exclude: [], type: GlobType.Template }],
  config: { vars: { name, version } }
}]

Code Generation

Use custom processor:

processors: [{
  name: 'myorg/graphql-codegen',
  files: [{ root: 'schemas', glob: '**/*.graphql', exclude: [], type: GlobType.Template }],
  config: { generateTypes: true, outputDir: 'src/generated' }
}]

Git Initialization

Use plugin:

plugins: [{
  name: 'cyan/init-git',
  config: { commitMessage: 'Initial commit' }
}]

Install Dependencies

Use plugin:

plugins: [{
  name: 'cyan/npm-install',
  config: { packageManager: 'pnpm' }
}]

Creating Custom

Custom Processor

Create when you need specialized file processing:

1. Define processor package
2. Implement IProcessor interface
3. Register with registry
4. Use in templates

See Processor Development for details.

Custom Plugin

Create when you need post-generation actions:

1. Define plugin package
2. Implement IPlugin interface
3. Register with registry
4. Use in templates

See Plugin Development for details.

Best Practices

1. Use default processor for standard templating
2. Create custom processors for specialized file processing
3. Use plugins for actions that modify project state
4. Keep processors focused on file transformation
5. Keep plugins focused on side effects

Related

• Default Processor - How cyan/default works
• Processor Development - Creating custom processors
• Plugin Development - Creating custom plugins
• Use Custom Processor - How-to guide