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

JSON Configuration

cat > tsconfig.json << 'EOF'
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src/**/*"]
}
EOF

Complex Shell Script

cat > deploy.sh << 'EOF'
#!/bin/bash
set -e

echo "Deploying..."
if [ "$ENV" = "production" ]; then
  echo "Production deployment"
fi
EOF

Advantages Over write_file

1. No escaping complexity: Quotes, backslashes, and special characters work naturally
2. Preserves formatting: Indentation and line breaks remain exact
3. Handles multi-line content: No need to concatenate strings or use base64
4. More reliable: Shell handles file I/O directly with fewer abstraction layers

Limitations

• Creates files in shell execution context (ensure correct working directory)
• Less programmatic than

  write_file

  for dynamic content generation
• Requires shell access (may not work in restricted environments)

Troubleshooting

Problem: File not created at expected path

• Solution: Use absolute paths or verify current working directory with

  pwd

Problem: Content appears corrupted

• Solution: Ensure delimiter is quoted (

  'EOF'

  ) and closing delimiter has no trailing whitespace

Problem: Permission denied

• Solution: Ensure target directory exists and you have write permissions