Getting Started with Plugins

Install, manage, and use plugins in Fresh with the built-in package manager

Fresh includes a built-in package manager for installing, updating, and managing plugins, themes, and language packs.

Installing Plugins

Use the command palette to install plugins from the registry:

1. Open Command Palette

   Press Ctrl+P to open the command palette, then type >.

2. Search for Install Command

   Type “pkg: Install Plugin” and press Enter.

3. Browse Available Plugins

   Select a plugin from the list of available plugins in the registry.

4. Restart Fresh

   Restart Fresh to activate the newly installed plugin.

Package Manager Commands

All package management is done through the command palette (Ctrl+P >):

Command	Description
pkg: Install Plugin	Browse and install plugins from the registry
pkg: Install Theme	Browse and install themes from the registry
pkg: Install from URL	Install directly from any git repository URL
pkg: List Installed	Show all installed packages
pkg: Update All	Update all installed packages
pkg: Remove Package	Remove an installed package
pkg: Sync Registry	Fetch the latest package lists from registry sources

Installing from Git URL

Any git repository can be installed directly:

1. Open Command Palette

   Press Ctrl+P > to open the command palette.

2. Select Install from URL

   Search for pkg: Install from URL and press Enter.

3. Enter Git URL

   Paste the git repository URL:

   https://github.com/user/fresh-plugin
   
4. Restart Fresh

   Restart Fresh to activate the plugin.

Monorepo Support

For repositories containing multiple plugins, use a URL fragment to specify the subdirectory:

https://github.com/user/fresh-plugins#packages/rainbow-brackets

This installs only the packages/rainbow-brackets directory from the repository.

This is useful for monorepos or repositories that contain multiple related plugins.

Package Locations

Installed packages are stored in your config directory:

Linux/macOS

# Plugins
~/.config/fresh/plugins/packages/

# Themes
~/.config/fresh/themes/packages/

# Language Packs
~/.config/fresh/grammars/

Each package is a git repository, so you can update manually with git pull if needed.

Custom Registry Sources

By default, Fresh uses the official package registry. You can add additional registries in your config:

config.json

{
  "packages": {
    "sources": [
      "https://github.com/sinelaw/fresh-plugins-registry",
      "https://github.com/my-org/private-plugins"
    ]
  }
}

After adding sources, run pkg: Sync Registry from the command palette to fetch the latest package lists.

Only add registry sources you trust, as plugins have access to the editor API.

Plugin Development Location

When developing your own plugins, place them in the main plugins directory:

~/.config/fresh/plugins/

Any .ts file in this directory will be automatically loaded when Fresh starts.

For quick testing, you can create a plugin file directly in this directory without using the package manager.

Bundled Plugins

Fresh ships with many production-ready plugins already installed:

Essential Plugins

Git Integration

• git_grep.ts - Interactive search through git-tracked files
• git_find_file.ts - Fuzzy file finder for git repositories
• git_blame.ts - Git blame view with commit navigation
• git_log.ts - Git log viewer with history browsing
• git_gutter.ts - Show git diff markers in the gutter

Code Tools

• diagnostics_panel.ts - LSP diagnostics panel with navigation
• find_references.ts - Find references across the codebase
• todo_highlighter.ts - Highlights TODO/FIXME/HACK in comments
• color_highlighter.ts - Preview color codes inline

Editing Features

• search_replace.ts - Search and replace functionality
• path_complete.ts - Path completion in prompts
• markdown_compose.ts - Semi-WYSIWYG markdown editing
• merge_conflict.ts - 3-way merge conflict resolution

Language Support

LSP integration for:

• TypeScript/JavaScript (typescript-lsp.ts)
• Rust (rust-lsp.ts)
• Python (python-lsp.ts)
• Go (go-lsp.ts)
• C/C++ (clangd-lsp.ts)
• And many more…

Using Plugins

Once installed, plugins automatically register their commands. Access them through:

Command Palette

Press Ctrl+P > and search for the plugin’s commands:

# Examples:
> Git Grep
> Git: Find File
> Git Blame
> Show Diagnostics
> Find References

Keybindings

Plugins can register keybindings. Check your config or the plugin’s documentation for available shortcuts.

Automatic Features

Some plugins work automatically:

• todo_highlighter.ts - Automatically highlights TODO/FIXME keywords
• color_highlighter.ts - Automatically previews color codes
• git_gutter.ts - Automatically shows git changes in the gutter
• diagnostics_panel.ts - Automatically shows LSP diagnostics

Updating Plugins

Keep your plugins up to date:

1. Open Command Palette

   Press Ctrl+P > to open the command palette.

2. Update All Packages

   Search for pkg: Update All and press Enter.

3. Restart Fresh

   Restart Fresh to load the updated plugins.

Manual Update

Since each package is a git repository, you can also update manually:

cd ~/.config/fresh/plugins/packages/plugin-name
git pull

Removing Plugins

Remove unwanted plugins:

1. Open Command Palette

   Press Ctrl+P > to open the command palette.

2. Remove Package

   Search for pkg: Remove Package and select the plugin to remove.

3. Restart Fresh

   Restart Fresh to complete the removal.

Troubleshooting

Plugin Not Loading

Check Plugin Location

Ensure the plugin is in the correct directory:

~/.config/fresh/plugins/
# or for installed packages:
~/.config/fresh/plugins/packages/

Check TypeScript Syntax

Plugins must have valid TypeScript syntax. Check for syntax errors:

/// <reference path="../types/fresh.d.ts" />

// Your plugin code here

Check Debug Logs

Run Fresh with debug logging:

RUST_LOG=debug fresh

Restart Fresh

Plugins are only loaded at startup. Always restart Fresh after installing or modifying plugins.

Plugin Conflicts

If two plugins conflict (e.g., both register the same keybinding), the last loaded plugin wins. Check your keybindings config to resolve conflicts.

Next Steps

Plugin Development

Learn how to create your own plugins

Plugin Examples

Explore real plugin examples with code

Plugin Overview

Learn about the plugin system architecture

API Reference

Complete API documentation