HeaderCraft

Automatically generate and insert standardized headers into your code files.
Perfect for maintaining consistent file documentation across your projects.

✨ Features

• Automatic Header Generation: Automatically adds headers when creating new files
• Smart Snippet Handling: Intelligently preserves VSCode snippets while adding headers
• Multiple Language Support: Works with various programming languages and file formats
• Customizable Templates: Define custom header templates per file type
• Flexible Date Formats: Support for different regional date formats
• Workspace Settings: Configure different settings per project
• Performance Optimized: Smart delay and content detection
• Multi-language UI: Supports English and Portuguese (BR)

🚀 Installation

1. Open Visual Studio Code
2. Go to Extensions tab (Ctrl+Shift+X or Cmd+Shift+X on macOS)
3. Search for "HeaderCraft"
4. Click Install
5. Restart VS Code

⚙️ Configuration

Basic Settings

Access through VS Code settings (Ctrl+,) or settings.json:

{
    "headerCraft.authorName": "Your Name",
    "headerCraft.useSystemUsername": false,
    "headerCraft.dateFormat": "YYYY/MM/DD"
}

Advanced Configuration

Custom Templates

Define custom header templates per file extension:

{
    "headerCraft.customTemplate": {
        ".js": "/**\n * @file ${fileName}\n * @author ${author}\n * @date ${date}\n */\n\n",
        ".py": "'''\n@file ${fileName}\n@author ${author}\n@date ${date}\n'''\n\n"
    }
}

Snippet Behavior

Control how HeaderCraft handles existing snippets:

{
    "headerCraft.snippetBehavior": "preserveAndAdd",  // Options: preserveAndAdd, skipIfContent, always
    "headerCraft.insertDelay": 500  // Delay in milliseconds
}

File Exclusions

Exclude specific files from header generation:

{
    "headerCraft.excludeFiles": [
        "*.min.js",
        "*.test.js",
        "*.spec.ts"
    ]
}

Date Format Options

The following date formats are supported:

• DD/MM/YYYY (Brazilian format)
• MM/DD/YYYY (US format)
• YYYY/MM/DD (International format)
• DD.MM.YYYY (European format)
• YYYY年MM月DD日 (Japanese format)

Example configuration:

{
    "headerCraft.dateFormat": "DD/MM/YYYY"
}

Note: Only use the predefined formats above. Do not enter actual dates.

Delay Configuration

The extension has a default delay of 2 seconds (2000ms) before adding headers. You can adjust this:

{
    "headerCraft.insertDelay": 2000  // Value in milliseconds (min: 500, max: 10000)
}

🎯 Usage

Automatic Mode

Headers are automatically added when:

• Creating new files
• Using VS Code's "New File" command
• Using file templates/snippets (with smart detection)

Manual Commands

1. Open Command Palette (Ctrl+Shift+P or Cmd+Shift+P)
2. Available commands:
   • HeaderCraft: Configure Name: Set author name
   • HeaderCraft: Add Header to Current File: Manually add header

Workspace Configuration

Create .vscode/settings.json in your project:

{
    "headerCraft.dateFormat": "DD/MM/YYYY",
    "headerCraft.customTemplate": {
        ".js": "/**\n * Project: ${projectName}\n * @file ${fileName}\n * @author ${author}\n */\n\n"
    }
}

📚 Examples & Use Cases

Basic Examples

JavaScript/TypeScript Class

/**
 * File: user.service.js
 * Author: Jean Barros
 * Date: 2024/03/15
 * Time: 14:30:25
 */

class UserService {
    // Your code here
}

Python Script

'''
File: data_processor.py
Author: Jean Barros
Date: 2024/03/15
Time: 14:30:25
'''

def process_data():
    # Your code here

Advanced Scenarios

1. Custom Project Template

{
    "headerCraft.customTemplate": {
        ".js": "/**\n * @company MyCompany\n * @project ${projectName}\n * @file ${fileName}\n * @author ${author}\n * @created ${date} ${time}\n * @lastModified ${date} ${time}\n * @description\n */\n\n"
    }
}

Results in:

/**
 * @company MyCompany
 * @project MyAwesomeProject
 * @file auth.service.js
 * @author Jean Barros
 * @created 2024/03/15 14:30:25
 * @lastModified 2024/03/15 14:30:25
 * @description
 */

// Your code here

2. Multi-language Project

{
    "headerCraft.customTemplate": {
        ".java": "/**\n * @package ${package}\n * @author ${author}\n * @since ${date}\n */\n\n",
        ".py": "'''\n${fileName}\nCreated by ${author} on ${date}\nCopyright © ${year} MyCompany. All rights reserved.\n'''\n\n",
        ".ts": "/*\n * Generated by HeaderCraft\n * Author: ${author}\n * Created: ${date}\n * Project: ${projectName}\n */\n\n"
    }
}

3. Team Configuration

{
    "headerCraft.customTemplate": {
        ".js": "/**\n * Team: ${teamName}\n * Developer: ${author}\n * Review Required: Yes\n * Created: ${date}\n */\n\n"
    },
    "headerCraft.teamName": "Alpha Team",
    "headerCraft.requiresReview": true
}

4. Legal/License Headers

{
    "headerCraft.customTemplate": {
        ".cs": "/*\n * Copyright (c) ${year} MyCompany\n * All Rights Reserved\n * \n * Created by ${author} on ${date}\n * File: ${fileName}\n */\n\n"
    }
}

5. Different Date Formats by Region

Japanese Format:

{
    "headerCraft.dateFormat": "YYYY年MM月DD日",
    "headerCraft.customTemplate": {
        ".js": "/**\n * ファイル: ${fileName}\n * 作成者: ${author}\n * 作成日: ${date}\n */\n\n"
    }
}

European Format:

{
    "headerCraft.dateFormat": "DD.MM.YYYY",
    "headerCraft.customTemplate": {
        ".js": "/**\n * Datei: ${fileName}\n * Autor: ${author}\n * Datum: ${date}\n */\n\n"
    }
}

Special Cases

1. Working with Snippets

When creating a new Java class with VS Code snippet:

/**
 * File: UserController.java
 * Author: Jean Barros
 * Date: 2024/03/15
 * Time: 14:30:25
 */

package com.myapp.controllers;

public class UserController {
    // Snippet-generated content preserved
    private final UserService userService;
    
    public UserController(UserService userService) {
        this.userService = userService;
    }
}

2. Git Integration

{
    "headerCraft.customTemplate": {
        ".js": "/**\n * @file ${fileName}\n * @author ${author}\n * @date ${date}\n * @branch ${gitBranch}\n * @commit ${gitLastCommit}\n */\n\n"
    }
}

3. Environment-specific Headers

{
    "headerCraft.customTemplate": {
        ".js": "/**\n * Environment: ${nodeEnv}\n * Version: ${projectVersion}\n * Author: ${author}\n * Created: ${date}\n */\n\n"
    }
}

4. API Documentation

{
    "headerCraft.customTemplate": {
        ".js": "/**\n * @api {${httpMethod}} /${endpoint}\n * @apiName ${fileName}\n * @apiGroup ${groupName}\n * @apiVersion ${version}\n * @apiAuthor ${author}\n * @apiCreated ${date}\n */\n\n"
    }
}

Integration Examples

1. With ESLint

{
    "headerCraft.customTemplate": {
        ".js": "/* eslint-disable */\n/**\n * @file ${fileName}\n * @author ${author}\n */\n/* eslint-enable */\n\n"
    }
}

2. With TypeScript Decorators

/**
 * File: user.controller.ts
 * Author: Jean Barros
 * Date: 2024/03/15
 * Module: Users
 */

@Controller('users')
export class UserController {
    // Your code here
}

3. With React Components

/**
 * Component: UserProfile
 * Author: Jean Barros
 * Created: 2024/03/15
 * Dependencies: React, Redux
 */

import React from 'react';

const UserProfile = () => {
    // Component code
};

Troubleshooting Examples

1. Fixing Snippet Conflicts

{
    "headerCraft.snippetBehavior": "preserveAndAdd",
    "headerCraft.insertDelay": 1000,
    "headerCraft.excludeFiles": ["*.spec.ts", "*.test.js"]
}

2. Custom Error Messages

{
    "headerCraft.customTemplate": {
        ".js": "/**\n * @file ${fileName}\n * @author ${author}\n * @throws {Error} If configuration is invalid\n * @throws {TypeError} If parameters are incorrect\n */\n\n"
    }
}

🔍 Troubleshooting

Header Not Generating

1. Check extension status:

   • Open VS Code extensions panel
   • Verify HeaderCraft is enabled

2. Verify file type support:

   • Check settings for excluded files
   • Ensure file extension has template

3. Snippet Issues:

   • Adjust snippetBehavior setting
   • Increase insertDelay if needed

Common Issues

1. Headers Overwriting Snippets

   • Set "headerCraft.snippetBehavior": "preserveAndAdd"
   • Increase insertDelay value

2. Wrong Date Format

   • Configure dateFormat in settings
   • Check system locale settings

3. Custom Templates Not Working

   • Verify JSON syntax
   • Check file extension matching

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

📬 Contact

• LinkedIn: j3anbarros
• GitHub: Barros99
• Issues: GitHub Issues

📄 License

MIT License - See LICENSE.md for details.

Made with ❤️ by j3anbarros