Folder Alias - VS Code Extension

June 11, 2026 · View on GitHub

English | 中文

A powerful VS Code extension that allows you to add customizable aliases and remarks to files and folders in your file tree, making project navigation and organization more intuitive.

🌟 Features

Customizable Aliases: Add meaningful names and descriptions to any file or folder
Dual Configuration: Support for both public (shared) and private (personal) aliases
Preset System: Pre-built alias sets for common workspace configurations (AI agents, frontend tooling)
Visual Integration: Seamlessly integrated into VS Code's file explorer
Easy Management: Simple right-click interface for adding and modifying aliases
Persistent Storage: Aliases are saved in JSON configuration files within your workspace

🚀 Installation

From VS Code Marketplace

Open VS Code
Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
Search for "Folder Alias"
Click Install
Reload VS Code when prompted

Manual Installation

Download the latest .vsix file from releases
Open VS Code
Go to Extensions
Click ... (More Actions) → Install from VSIX...
Select the downloaded .vsix file

🎯 Usage

Getting Started

The quickest way to get started is to apply a preset that matches your project type:

Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
Type "Apply Preset" and select it
Choose a preset from the list:
- AI Agents - For projects using AI coding assistants (Claude, Cursor, Copilot, etc.)
- Frontend Tooling - For frontend projects with common build tools (Vite, ESLint, Prettier, etc.)
The preset aliases will be applied to your workspace immediately

Tip: Preset aliases have lower priority than your manually configured aliases. You can customize any preset alias afterward using "Add Alias".

Adding an Alias

Right-click on any file or folder in the VS Code Explorer
Select "Add Alias"
Choose the alias scope:
- Public: Saved in folder-alias.json (can be committed to version control)
- Private: Saved in private-folder-alias.json (ignored by version control)
Enter your desired alias/description
Press Enter to save

Modifying an Alias

Right-click on a file/folder that already has an alias
Select "Add Alias"
Edit the existing text or clear it to remove the alias
Press Enter to update

Refreshing Aliases

After manually editing the JSON configuration files, you can refresh the file explorer display:

Right-click anywhere in the Explorer
Select "Refresh Aliases"
Or use Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and type "Refresh Aliases"
The file explorer will reload all alias configurations from the JSON files

Presets allow you to quickly apply pre-configured alias sets for common workspace configurations. Preset aliases are loaded at runtime and have lower priority than your workspace config (workspace config wins over presets).

Available Presets

Preset	Description
AI Agents	Common AI agent config directories and instruction files (Claude Code, Cursor, Copilot, MCP, etc.)
Frontend Tooling	Common frontend build tools and configuration files (Vite, Webpack, ESLint, Prettier, Tailwind, etc.)

Applying a Preset

Right-click on a workspace folder in the Explorer, or use Command Palette (Ctrl+Shift+P)
Select "Apply Preset"
Choose a preset from the list (built-in presets are marked with 📄)
The preset aliases will be applied to your workspace
Select an already-applied preset again to remove it

Saving Custom Presets

Add the aliases you want to save
Right-click on the workspace folder, or use Command Palette
Select "Save Config as Preset"
Enter a name for your preset
The preset is saved to .vscode/folder-alias-presets/

Deleting Custom Presets

Right-click on the workspace folder, or use Command Palette
Select "Delete Preset"
Choose a custom preset to delete

Preset Storage

Built-in presets: Shipped with the extension (media/presets/)
User presets: Stored in .vscode/folder-alias-presets/<name>.json
Selected presets: Stored in .vscode/folder-alias-selected-presets.json

Multi-language Support

Presets support localization. The extension detects your workspace language and displays preset names and descriptions in the appropriate language (currently supports English and Chinese).

File Structure

The extension supports two configuration locations with smart priority:

Configuration Priority

The extension will prioritize .vscode directory over root directory:

.vscode/folder-alias.json - Public aliases (highest priority)
.vscode/private-folder-alias.json - Private aliases (highest priority)
folder-alias.json - Public aliases (fallback)
private-folder-alias.json - Private aliases (fallback)

Behavior Rules:

Reading: If .vscode/folder-alias.json exists, it will be used instead of root folder-alias.json
Initialization: The extension will only create configuration files in the root directory if no corresponding files exist in .vscode
Saving: When saving aliases, the extension will save to .vscode only if the corresponding file already exists there, otherwise to root directory

File Locations

You can organize your aliases in either location:

.vscode/ directory: Keeps your workspace root clean and organized
Root directory: Traditional location, compatible with existing setups

Example Configuration

{
  "src/components/Button": {
    "description": "🎛️ Reusable Button Component",
    "tooltip": "Primary button component with variants"
  },
  "docs/api": {
    "description": "📚 API Documentation",
    "tooltip": "REST API endpoints documentation"
  }
}

🛠️ Development

Prerequisites

Node.js (v24+)
pnpm (preferred package manager)
VS Code

Setup Development Environment

# Clone the repository
git clone https://github.com/Muromi-Rikka/folder-alias.git
cd folder-alias

# Install dependencies
pnpm install

# Build the extension
pnpm build

# Run in development mode (with watch)
pnpm dev

Available Scripts

Command	Description
`pnpm build`	Build the extension
`pnpm dev`	Build in watch mode for development
`pnpm test`	Run tests
`pnpm test:watch`	Run tests in watch mode
`pnpm test:coverage`	Run tests with coverage report
`pnpm lint`	Run ESLint
`pnpm typecheck`	Run TypeScript type checking
`pnpm update:gen`	Regenerate VS Code extension metadata
`pnpm pack`	Package the extension
`pnpm publish`	Publish to VS Code Marketplace

Debugging

Open the project in VS Code
Press F5 to open a new Extension Development Host window
Make changes to the source code
Reload (Ctrl+R / Cmd+R) the Extension Development Host to see changes

# Folder Alias - Personal aliases
private-folder-alias.json

🔧 Architecture

Core Components

src/index.ts - Extension entry point, registers decoration provider and commands
src/file-alias.ts - File decoration provider and alias management per workspace folder
src/hooks/useWorkspaceManager.ts - Manages workspace folder instances and URI resolution
src/hooks/useConfig.ts - Loads, merges, and saves public/private JSON configs with preset support
src/command/add-alias.command.ts - Command handler for adding/modifying aliases
src/command/apply-preset.command.ts - Command handler for applying/toggling presets
src/command/save-preset.command.ts - Command handler for saving config as preset
src/command/delete-preset.command.ts - Command handler for deleting user presets
src/command/refresh-aliases.command.ts - Command handler for refreshing all aliases
src/typings/preset.typing.ts - Preset type definitions with localization support
src/utils/preset.util.ts - Preset utilities (load, save, localize, merge)
src/utils/file.util.ts - File I/O utilities for configuration management
src/utils/logger.util.ts - Logging utility

Technologies Used

TypeScript - Primary language
reactive-vscode - Reactive programming for VS Code extensions
es-toolkit - Modern utility library (replaces lodash)
destr - Safe JSON parsing
pathe - Cross-platform file path utilities
tsdown - Build tool for TypeScript
ESLint (antfu config) - Code linting
Vitest - Testing framework

🤝 Contributing

Contributions are welcome! To get started:

Fork the repository
Create a feature branch: git checkout -b feature/new-feature
Make your changes
Run tests: pnpm test
Run linting: pnpm lint
Commit your changes and push
Submit a pull request

Contributing Presets

We welcome contributions of new presets! Presets help developers quickly set up aliases for common project types.

Preset File Format

Create a JSON file in media/presets/ with the following structure:

{
  "name": "My Preset",
  "description": "Description of what this preset is for",
  "localized": {
    "zh-cn": {
      "name": "我的预设",
      "description": "此预设的用途说明",
      "aliases": {
        "path/to/file": { "description": "中文描述", "tooltip": "中文提示" }
      }
    }
  },
  "aliases": {
    "path/to/file": { "description": "English description", "tooltip": "English tooltip" }
  }
}

Preset Guidelines

File naming: Use lowercase with hyphens (e.g., react-framework.json)
Description: Use format "ToolName + 描述类型" (e.g., "Vite配置", "ESLint配置")
Tooltips: Provide clear, concise explanations in both English and Chinese
Aliases: Include the most common and useful files/directories for the project type
Localization: Always include both English (default) and Chinese (zh-cn) translations
No duplicates: Check existing presets to avoid redundancy

Currently Available Presets

Preset	Description
`ai-agents.json`	AI agent config directories and instruction files
`frontend-tooling.json`	Frontend build tools and configuration files

Submitting a New Preset

Create your preset file in media/presets/
Follow the format and guidelines above
Run pnpm test to ensure everything works
Submit a pull request with a clear description of:
- What project type this preset targets
- Why it's useful for developers
- Example use cases