heredoc-file-write

Heredoc File Write Workaround

When to Use This Skill

Use this pattern when:

• write_file repeatedly fails with "unknown error" or similar messages
• The target file contains complex code (TypeScript, JSX, JSON with special characters, etc.)
• Standard file writing approaches encounter encoding or escaping issues
• You need a reliable fallback method to create files

Core Technique

Switch from write_file to run_shell using heredoc syntax with cat. The heredoc approach handles special characters, quotes, and complex content more reliably.

Step-by-Step Instructions

Step 1: Identify Write Failures

When write_file fails repeatedly on the same file:

1. Note the error message (e.g., "unknown error", encoding issues)
2. Review the file content for special characters, nested quotes, or complex syntax
3. Attempt the heredoc workaround below

Step 2: Use Heredoc Syntax

Execute shell command with heredoc:

cat > /path/to/file.tsx << 'EOF'
// Your file content here
import React from 'react';
const Component = () => {
  return <div>Hello</div>;
};
export default Component;
EOF

Step 3: Key Heredoc Rules

1. Use quoted delimiter ('EOF' not EOF) to prevent variable expansion:

   • 'EOF' = literal content (recommended for code files)
   • EOF = allows variable expansion (use only if needed)

2. Match delimiters exactly: Opening and closing EOF must be on their own lines with no leading/trailing whitespace

3. No escaping needed: Content between delimiters is taken literally when using quoted delimiter

Step 4: Verify File Creation

After executing the heredoc command:

1. Check if file exists: ls -la /path/to/file.tsx
2. Verify content: cat /path/to/file.tsx or head -20 /path/to/file.tsx
3. Proceed with subsequent tasks once confirmed

Example Scenarios

TypeScript/JSX Component

cat > src/components/Button.tsx << 'EOF'
import React from 'react';

interface ButtonProps {
  label: string;
  onClick: () => void;
}

export const Button: React.FC<ButtonProps> = ({ label, onClick }) => {
  return (
    <button onClick={onClick} className="btn-primary">
      {label}
    </button>
  );
};
EOF