Configuration

/**
 * Main configuration interface for gatsby-config.js
 */
interface GatsbyConfig {
  /** Site metadata accessible through GraphQL queries */
  siteMetadata?: Record<string, any>;
  /** Array of plugins and their configurations */
  plugins?: PluginRef[];
  /** Experimental feature flags */
  flags?: GatsbyConfigFlags;
  /** Path prefix for the site when deployed to a subdirectory */
  pathPrefix?: string;
  /** Control trailing slash behavior */
  trailingSlash?: "always" | "never" | "ignore";
  /** Asset prefix for CDN hosting */
  assetPrefix?: string;
  /** GraphQL type generation options */
  graphqlTypegen?: boolean | GraphQLTypegenOptions;
  /** Promise polyfill configuration */
  polyfill?: boolean;
  /** Node field mappings for data relationships */
  mapping?: Record<string, string>;
  /** JSX runtime configuration */
  jsxRuntime?: "automatic" | "classic";
  /** JSX import source for automatic runtime */
  jsxImportSource?: string;
  /** Development proxy configuration */
  proxy?: ProxyConfigMap | ProxyConfigArray;
  /** Partytown proxied URLs for third-party scripts */
  partytownProxiedURLs?: string[];
  /** Express middleware for development server */
  developMiddleware?: (app: any) => void;
  /** HTTP headers configuration */
  headers?: HeadersMap;
  /** Deployment adapter configuration */
  adapter?: IAdapterConfig;
}

// gatsby-config.js
module.exports = {
  siteMetadata: {
    title: "My Gatsby Site",
    description: "A blazing fast static site",
    author: "@myusername",
    siteUrl: "https://mysite.com",
  },
  plugins: [
    "gatsby-plugin-react-helmet",
    {
      resolve: "gatsby-source-filesystem",
      options: {
        name: "pages",
        path: `${__dirname}/src/pages/`,
      },
    },
    {
      resolve: "gatsby-plugin-manifest",
      options: {
        name: "My Gatsby Site",
        short_name: "MyGatsby",
        start_url: "/",
        background_color: "#663399",
        theme_color: "#663399",
        display: "minimal-ui",
        icon: "src/images/gatsby-icon.png",
      },
    },
  ],
  pathPrefix: "/my-app",
  trailingSlash: "never",
  flags: {
    PRESERVE_WEBPACK_CACHE: true,
    FAST_DEV: true,
  },
};

/**
 * Site metadata configuration - accessible through GraphQL
 */
interface SiteMetadata extends Record<string, any> {
  /** Site title */
  title?: string;
  /** Site description */
  description?: string;
  /** Site author information */
  author?: string | AuthorObject;
  /** Canonical site URL */
  siteUrl?: string;
  /** Social media links */
  social?: SocialLinks;
  /** Additional custom metadata */
  [key: string]: any;
}

interface AuthorObject {
  name: string;
  email?: string;
  url?: string;
}

interface SocialLinks {
  twitter?: string;
  github?: string;
  linkedin?: string;
  [platform: string]: string | undefined;
}

/**
 * Plugin reference - can be string name or configuration object
 */
type PluginRef = string | IPluginRefObject;

interface IPluginRefObject {
  /** Plugin package name */
  resolve: string;
  /** Plugin configuration options */
  options?: PluginOptions;
  /** Internal plugin identifier */
  __key?: string;
}

interface PluginOptions extends Record<string, any> {
  /** Common plugin options */
  plugins?: PluginRef[];
  [key: string]: any;
}

// Different plugin configuration styles
module.exports = {
  plugins: [
    // Simple string reference
    "gatsby-plugin-react-helmet",
    
    // Plugin with options
    {
      resolve: "gatsby-plugin-google-analytics",
      options: {
        trackingId: "UA-123456789-1",
        head: false,
        anonymize: true,
      },
    },
    
    // Complex plugin with sub-plugins
    {
      resolve: "gatsby-plugin-mdx",
      options: {
        extensions: [".mdx", ".md"],
        plugins: [
          "gatsby-remark-images",
          "gatsby-remark-prismjs",
        ],
        remarkPlugins: [require("remark-slug")],
      },
    },
  ],
};

/**
 * Experimental feature flags
 */
interface GatsbyConfigFlags {
  /** Preserve Webpack cache between builds */
  PRESERVE_WEBPACK_CACHE?: boolean;
  /** Enable fast development mode */
  FAST_DEV?: boolean;
  /** Preserve file download cache */
  PRESERVE_FILE_DOWNLOAD_CACHE?: boolean;
  /** Enable parallel data sourcing */
  PARALLEL_SOURCING?: boolean;
  /** Enable fast refresh for React */
  FAST_REFRESH?: boolean;
  /** Additional experimental flags */
  [flag: string]: boolean | undefined;
}

/**
 * GraphQL type generation configuration
 */
interface GraphQLTypegenOptions {
  /** Output directory for generated types */
  typesOutputPath?: string;
  /** Generate types on every query change */
  generateOnBuild?: boolean;
  /** Include plugin-generated types */
  includeResolvers?: boolean;
}

/**
 * Proxy configuration for development server
 */
type ProxyConfigMap = Record<string, string | ProxyConfigObject>;
type ProxyConfigArray = Array<ProxyConfigObject>;

interface ProxyConfigObject {
  /** Proxy target URL */
  target: string;
  /** Enable secure connections */
  secure?: boolean;
  /** Change origin header */
  changeOrigin?: boolean;
  /** Path rewrite rules */
  pathRewrite?: Record<string, string>;
  /** Custom headers */
  headers?: Record<string, string>;
}

module.exports = {
  // Simple proxy mapping
  proxy: {
    "/api": "http://localhost:3001",
  },
  
  // Advanced proxy configuration
  proxy: [
    {
      prefix: "/api",
      url: "http://localhost:3001",
      changeOrigin: true,
      pathRewrite: {
        "^/api": "",
      },
    },
  ],
};

/**
 * HTTP headers configuration
 */
type HeadersMap = Record<string, Record<string, string>>;

module.exports = {
  headers: {
    "/*": [
      {
        key: "X-Frame-Options",
        value: "DENY",
      },
      {
        key: "X-Content-Type-Options", 
        value: "nosniff",
      },
    ],
    "/api/*": [
      {
        key: "Access-Control-Allow-Origin",
        value: "*",
      },
    ],
  },
};

/**
 * Adapter configuration for deployment platforms
 */
interface IAdapterConfig {
  /** Adapter package name */
  name: string;
  /** Adapter configuration options */
  options?: Record<string, any>;
  /** Image CDN configuration */
  imageCDN?: boolean;
  /** File CDN configuration */
  fileCDN?: boolean;
  /** Functions support */
  supports?: {
    functions?: boolean;
    redirects?: boolean;
    headers?: boolean;
  };
}

module.exports = {
  adapter: {
    name: "gatsby-adapter-netlify",
    options: {
      excludeDatastoreFromBundle: true,
      imageCDN: true,
    },
  },
};

/**
 * Path prefix for subdirectory deployment
 * Example: "/my-app" for deployment to https://example.com/my-app/
 */
pathPrefix?: string;

/**
 * Trailing slash behavior
 * - "always": Add trailing slash to all URLs
 * - "never": Remove trailing slash from all URLs  
 * - "ignore": Leave URLs as-is
 */
trailingSlash?: "always" | "never" | "ignore";

/**
 * Asset prefix for CDN hosting
 * Example: "https://cdn.example.com" 
 */
assetPrefix?: string;

/**
 * Deployment adapter configuration
 */
interface IAdapterConfig {
  /** Adapter package name */
  name: string;
  /** Adapter configuration options */
  options?: Record<string, any>;
  /** Image CDN configuration */
  imageCDN?: boolean;
  /** File CDN configuration */
  fileCDN?: boolean;
  /** Platform-specific capabilities */
  supports?: {
    functions?: boolean;
    redirects?: boolean;
    headers?: boolean;
  };
}

/**
 * Adapter initialization function type
 */
type AdapterInit = (options?: object) => IAdapter;

/**
 * Core adapter interface
 */
interface IAdapter {
  name: string;
  cache: Cache;
  config: IAdapterConfig;
  initializeAdapterStore?: () => Promise<void>;
  createRoutes?: (functions?: Array<IFunctionDefinition>) => Promise<RoutesManifest>;
}

// gatsby-config.js - Netlify adapter
module.exports = {
  adapter: {
    name: "gatsby-adapter-netlify",
    options: {
      excludeDatastoreFromBundle: true,
      imageCDN: true,
    },
  },
};

// Vercel adapter with functions
module.exports = {
  adapter: {
    name: "gatsby-adapter-vercel",
    options: {
      regions: ["us-east-1"],
      functions: true,
      imageCDN: true,
      fileCDN: false,
    },
  },
};

// Custom adapter configuration  
module.exports = {
  adapter: {
    name: "./adapters/my-custom-adapter",
    options: {
      deploymentTarget: "production",
      customOption: "value",
    },
  },
};

/**
 * Routes manifest for deployment
 */
interface RoutesManifest {
  version: 1;
  routes: Array<IStaticRoute | IFunctionRoute | IRedirectRoute>;
  headers?: HeaderRoutes;
  functions?: FunctionsManifest;
}

/**
 * Static route definition
 */
interface IStaticRoute {
  type: "static";
  route: string;
  filePath: string;
}

/**
 * Function route definition
 */
interface IFunctionRoute {
  type: "function";
  route: string;
  functionId: string;
}

/**
 * Redirect route definition
 */
interface IRedirectRoute {
  type: "redirect";
  route: string;
  redirectTo: string;
  statusCode: number;
}

/**
 * Function definition for serverless deployment
 */
interface IFunctionDefinition {
  functionId: string;
  originalFilePath: string;
  relativeCompiledFilePath: string;
  absoluteCompiledFilePath: string;
  matches: Array<string>;
}