🎉 The Architech v1.0 is now available. Read more →
CLI Internals
Blueprint Actions
Action Reference

Blueprint Actions Reference

Complete API Documentation

This is the single source of truth for all blueprint actions supported by The Architech CLI.

CREATE_FILE

Create a new file with content or from a template.

Signature

{
  type: 'CREATE_FILE';
  path: string;
  content?: string;        // Direct content
  template?: string;       // Or template file
  data?: Record<string, any>;  // Data for template
  forEach?: string;        // Optional: Loop over array
}

Example: Direct Content

{
  type: 'CREATE_FILE',
  path: 'src/config.ts',
  content: 'export const API_URL = process.env.API_URL;'
}

Example: From Template

{
  type: 'CREATE_FILE',
  path: 'src/db/schema.ts',
  template: 'schema.ejs',
  data: {
    tableName: 'users',
    fields: ['id', 'email', 'name']
  }
}

Example: With forEach

{
  type: 'CREATE_FILE',
  forEach: 'module.parameters.components',  // ['button', 'card']
  path: 'components/ui/{{item}}.tsx',
  template: 'component.ejs',
  data: { componentName: '{{item}}' }
}
 
// Generates:
// - components/ui/button.tsx
// - components/ui/card.tsx

ENHANCE_FILE

Modify an existing file using a modifier (AST-based).

Signature

{
  type: 'ENHANCE_FILE';
  path: string;
  modifier: string;        // Modifier name
  params: Record<string, any>;
  fallback?: 'create' | 'skip' | 'error';
}

Example: Add Import

{
  type: 'ENHANCE_FILE',
  path: 'src/app/layout.tsx',
  modifier: 'ts-module-enhancer',
  params: {
    importsToAdd: [
      { name: 'QueryProvider', from: '@/lib/query-client' }
    ]
  }
}

Example: Wrap JSX Children

{
  type: 'ENHANCE_FILE',
  path: 'src/app/layout.tsx',
  modifier: 'jsx-children-wrapper',
  params: {
    wrapperComponent: 'QueryProvider',
    importFrom: '@/lib/query-client',
    props: { dehydratedState: 'pageProps.dehydratedState' }
  }
}

Fallback Strategies

fallback: 'create'  // Create file if missing
fallback: 'skip'    // Skip action if file missing
fallback: 'error'   // Throw error if file missing (default)

INSTALL_PACKAGES

Install npm packages.

Signature

{
  type: 'INSTALL_PACKAGES';
  packages: string[];
  dev?: boolean;
}

Example

{
  type: 'INSTALL_PACKAGES',
  packages: ['@tanstack/react-query', 'zustand']
}
 
{
  type: 'INSTALL_PACKAGES',
  packages: ['@types/node', 'typescript'],
  dev: true
}

ADD_SCRIPT

Add npm script to package.json.

Signature

{
  type: 'ADD_SCRIPT';
  name: string;
  command: string;
}

Example

{
  type: 'ADD_SCRIPT',
  name: 'db:migrate',
  command: 'drizzle-kit migrate'
}

ADD_ENV_VAR

Add environment variable to .env file.

Signature

{
  type: 'ADD_ENV_VAR';
  key: string;
  value?: string;
  comment?: string;
}

Example

{
  type: 'ADD_ENV_VAR',
  key: 'DATABASE_URL',
  value: 'postgresql://localhost:5432/mydb',
  comment: 'Database connection string'
}

RUN_COMMAND

Execute a CLI command.

Signature

{
  type: 'RUN_COMMAND';
  command: string;
  cwd?: string;
}

Example

{
  type: 'RUN_COMMAND',
  command: 'npx shadcn-ui@latest init'
}

Available Modifiers

ts-module-enhancer

Add imports and top-level statements to TypeScript files.

jsx-children-wrapper

Wrap children props with provider components.

package-json-merger

Deep merge package.json.

tsconfig-enhancer

Merge tsconfig.json.

js-export-wrapper

Wrap exports with HOCs (e.g., withSentry).

json-merger

Generic deep merge for JSON files.

yaml-merger

Merge YAML configuration files.

css-enhancer

Intelligently merge CSS files.

Complete Modifier Documentation →

For Marketplace Authors

When creating blueprints, use these actions. Never perform direct file operations.

✅ Do this:

{ type: 'CREATE_FILE', path: 'file.ts', content: '...' }

❌ Not this:

fs.writeFileSync('file.ts', '...');  // Don't do this!

Why: Actions go through VFS, ensuring safety and atomicity.

Next Steps

OverviewModifiers System