Plugin Management

Tools for discovering, installing, and managing Gatsby plugins in projects, including documentation access and plugin listing functionality.

Capabilities

Plugin Commands

Main interface for plugin-related operations and information.

/**
 * Plugin management commands
 * @param cmd - Plugin command (docs, ls)
 * @param plugins - Plugin names (optional, for future expansion)
 */
gatsby plugin <cmd> [plugins...]

type PluginCommand = "docs" | "ls";

Usage Examples:

# Show plugin documentation links
gatsby plugin docs

# List installed plugins
gatsby plugin ls

Plugin Documentation

Access comprehensive documentation and resources for Gatsby plugin development and usage.

/**
 * Display plugin documentation links and resources
 * Provides links to plugin development guides and community resources
 */
gatsby plugin docs

Documentation Categories:

Using Plugins:

• What is a Plugin? - Introduction to Gatsby plugins
• Using a Plugin in Your Site - Installation and configuration
• Loading Plugins from Local Plugins Folder - Local development
• Plugin Library - Official plugin directory

Creating Plugins:

• Naming a Plugin - Plugin naming conventions
• Files Gatsby Looks for in a Plugin - Plugin structure
• Creating a Generic Plugin - Basic plugin development
• Creating a Local Plugin - Local plugin development
• Creating a Source Plugin - Data source plugins
• Creating a Transformer Plugin - Data transformation plugins
• Submit to Plugin Library - Publishing process
• Maintaining a Plugin - Long-term maintenance

Community:

• Discord #plugin-authoring channel - Community support

Plugin Listing

List all plugins currently installed and configured in the Gatsby project.

/**
 * List installed Gatsby plugins
 * Parses gatsby-config.js to show configured plugins
 */
gatsby plugin ls

Usage Examples:

# List all installed plugins
gatsby plugin ls

Sample Output:

Following plugins are installed:

- gatsby-plugin-react-helmet
- gatsby-plugin-image
- gatsby-plugin-sharp
- gatsby-transformer-sharp
- gatsby-source-filesystem
- gatsby-plugin-manifest
- gatsby-plugin-offline

Plugin Information Displayed:

• Plugin name
• Configuration status
• Load order in gatsby-config.js

Plugin Installation (Programmatic)

Advanced programmatic plugin installation functionality for automated workflows.

/**
 * Programmatic plugin installation
 * Used internally by Gatsby CLI for automated plugin management
 */
function addPlugins(
  plugins: Array<string>,
  pluginOptions: Record<string, Record<string, unknown>>,
  directory: string,
  packages: Array<string>
): Promise<void>;

/**
 * Normalize plugin names to standard Gatsby plugin format
 * @param plugin - Plugin name to normalize
 * @returns Normalized plugin name with gatsby- prefix
 */
function normalizePluginName(plugin: string): string;

Plugin Name Normalization:

// Input -> Output examples
"react-helmet" -> "gatsby-plugin-react-helmet"
"source-filesystem" -> "gatsby-source-filesystem"  
"transformer-sharp" -> "gatsby-transformer-sharp"
"plugin-image" -> "gatsby-plugin-image"
"gatsby-plugin-sharp" -> "gatsby-plugin-sharp" // Already normalized

Installation Process:

1. Normalize plugin names
2. Install npm packages
3. Update gatsby-config.js
4. Validate configuration
5. Report installation status

Plugin Configuration Management

Tools for managing plugin configuration in gatsby-config.js.

/**
 * Plugin configuration structure
 * Represents how plugins are configured in gatsby-config.js
 */
interface PluginConfig {
  resolve: string;                           // Plugin name
  options?: Record<string, unknown>;        // Plugin options
  __key?: string;                           // Unique key for duplicate plugins
}

/**
 * Gatsby configuration with plugins
 */
interface GatsbyConfig {
  plugins: Array<string | PluginConfig>;    // Plugin list
  // ... other config options
}

Configuration Examples:

// gatsby-config.js
module.exports = {
  plugins: [
    // Simple plugin (string format)
    "gatsby-plugin-react-helmet",
    
    // Plugin with options (object format)
    {
      resolve: "gatsby-source-filesystem",
      options: {
        name: "pages",
        path: "./src/pages/",
      },
    },
    
    // Duplicate plugin with key
    {
      resolve: "gatsby-source-filesystem",
      options: {
        name: "images",
        path: "./src/images/",
      },
      __key: "images",
    },
  ],
};

Plugin Development Utilities

Utilities and tools for plugin development and testing.

/**
 * Plugin validation and development utilities
 * Internal functions used by the plugin management system
 */
interface PluginValidation {
  validatePluginName(name: string): boolean;
  validatePluginConfig(config: PluginConfig): boolean;
  checkPluginCompatibility(name: string, version: string): boolean;
}

Plugin Development Workflow:

1. Create plugin directory structure
2. Implement Gatsby Node APIs
3. Add plugin to local gatsby-config.js
4. Test with gatsby develop
5. Validate with gatsby plugin ls
6. Publish to npm registry
7. Submit to Gatsby plugin library

Plugin Categories

Understanding different types of Gatsby plugins and their purposes.

Source Plugins:

• Fetch data from external sources
• Examples: gatsby-source-contentful, gatsby-source-wordpress
• Create nodes in Gatsby's data layer

Transformer Plugins:

• Transform data from source plugins
• Examples: gatsby-transformer-remark, gatsby-transformer-sharp
• Convert raw data into usable formats

Functional Plugins:

• Add functionality to Gatsby sites
• Examples: gatsby-plugin-react-helmet, gatsby-plugin-manifest
• Integrate with React ecosystem and web APIs

Styling Plugins:

• Handle CSS and styling solutions
• Examples: gatsby-plugin-styled-components, gatsby-plugin-sass
• Configure build-time style processing

SEO and Performance Plugins:

• Optimize for search engines and performance
• Examples: gatsby-plugin-sitemap, gatsby-plugin-offline
• Automated optimization and metadata generation

Plugin Troubleshooting

Common plugin issues and resolution strategies.

Configuration Errors:

# Check plugin configuration
gatsby plugin ls

# Validate gatsby-config.js syntax
node -e "console.log(JSON.stringify(require('./gatsby-config.js'), null, 2))"

Plugin Conflicts:

• Version compatibility issues
• Conflicting transformations
• Load order dependencies
• Duplicate plugin instances

Resolution Steps:

1. Check plugin documentation
2. Verify version compatibility
3. Review plugin load order
4. Clear cache: gatsby clean
5. Check for conflicting plugins
6. Update plugin versions

Error Handling

Plugin management includes comprehensive error handling:

Configuration Parsing Errors:

• Malformed gatsby-config.js files
• Invalid plugin options
• Missing plugin dependencies
• Syntax errors in configuration

Installation Errors:

• Network connectivity issues
• Package registry problems
• Permission and access errors
• Dependency resolution failures

Runtime Errors:

• Plugin initialization failures
• API compatibility issues
• Resource loading problems
• Plugin execution errors

Error Resolution:

• Detailed error messages with context
• Suggested fixes and documentation links
• Plugin-specific troubleshooting guides
• Community support channels