FoundryKit

Configuration Guide

Configure FoundryKit CLI for your project needs

Configuration Guide

Learn how to configure the FoundryKit CLI to match your project requirements and preferences.

Configuration Files

FoundryKit Config

The main configuration file is foundrykit.config.js in your project root.

module.exports = {
  // Project metadata
  project: {
    name: 'my-foundrykit-project',
    version: '1.0.0',
    description: 'A FoundryKit project',
    author: 'Your Name',
    license: 'MIT'
  },

  // Build configuration
  build: {
    outDir: 'dist',
    assetsDir: 'assets',
    sourcemap: true,
    minify: true,
    target: 'es2020'
  },

  // Development server configuration
  dev: {
    port: 3000,
    host: 'localhost',
    open: true,
    https: false,
    cors: true
  },

  // Component configuration
  components: {
    directory: 'src/components',
    prefix: '',
    style: 'css',
    typescript: true
  },

  // Testing configuration
  testing: {
    framework: 'jest',
    environment: 'jsdom',
    coverage: true,
    watch: false
  },

  // Linting configuration
  linting: {
    eslint: true,
    prettier: true,
    typescript: true
  }
}

Package.json Integration

The CLI can also read configuration from your package.json file.

{
  "name": "my-foundrykit-project",
  "version": "1.0.0",
  "foundrykit": {
    "build": {
      "outDir": "build"
    },
    "dev": {
      "port": 8080
    }
  }
}

Project Configuration

Project Metadata

Configure basic project information.

module.exports = {
  project: {
    name: 'my-project',
    version: '1.0.0',
    description: 'Project description',
    author: 'Your Name <your.email@example.com>',
    license: 'MIT',
    repository: {
      type: 'git',
      url: 'https://github.com/username/my-project'
    },
    keywords: ['foundrykit', 'react', 'typescript'],
    homepage: 'https://my-project.com'
  }
}

Environment Configuration

Configure different settings for different environments.

module.exports = {
  // Base configuration
  build: {
    outDir: 'dist',
    sourcemap: true
  },

  // Environment-specific overrides
  environments: {
    development: {
      dev: {
        port: 3000,
        open: true
      },
      build: {
        sourcemap: true,
        minify: false
      }
    },
    production: {
      dev: {
        port: 8080,
        open: false
      },
      build: {
        sourcemap: false,
        minify: true
      }
    },
    staging: {
      dev: {
        port: 4000
      },
      build: {
        sourcemap: true,
        minify: true
      }
    }
  }
}

Build Configuration

Output Settings

Configure build output behavior.

module.exports = {
  build: {
    // Output directory
    outDir: 'dist',
    
    // Assets directory
    assetsDir: 'assets',
    
    // Source maps
    sourcemap: true,
    
    // Minification
    minify: true,
    
    // Target environment
    target: 'es2020',
    
    // Module format
    format: 'esm',
    
    // Bundle splitting
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['react', 'react-dom'],
          utils: ['@foundrykit/utils']
        }
      }
    }
  }
}

Build Optimization

Configure build optimizations.

module.exports = {
  build: {
    // Tree shaking
    treeshake: true,
    
    // Code splitting
    chunkSizeWarningLimit: 1000,
    
    // Asset optimization
    assetsInlineLimit: 4096,
    
    // CSS code splitting
    cssCodeSplit: true,
    
    // Preload directives
    rollupOptions: {
      output: {
        assetFileNames: 'assets/[name]-[hash][extname]',
        chunkFileNames: 'js/[name]-[hash].js',
        entryFileNames: 'js/[name]-[hash].js'
      }
    }
  }
}

Development Configuration

Server Settings

Configure the development server.

module.exports = {
  dev: {
    // Server port
    port: 3000,
    
    // Server host
    host: 'localhost',
    
    // Open browser automatically
    open: true,
    
    // HTTPS
    https: false,
    
    // CORS
    cors: true,
    
    // Proxy configuration
    proxy: {
      '/api': {
        target: 'http://localhost:8000',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, '')
      }
    },
    
    // Middleware
    middleware: [
      // Custom middleware functions
    ]
  }
}

Hot Module Replacement

Configure HMR behavior.

module.exports = {
  dev: {
    // HMR settings
    hmr: {
      overlay: true,
      port: 24678
    },
    
    // Watch options
    watch: {
      ignored: ['**/node_modules/**', '**/dist/**'],
      usePolling: false
    }
  }
}

Component Configuration

Component Settings

Configure component generation and organization.

module.exports = {
  components: {
    // Component directory
    directory: 'src/components',
    
    // Component prefix
    prefix: '',
    
    // Style approach
    style: 'css', // 'css', 'scss', 'styled-components', 'emotion'
    
    // TypeScript support
    typescript: true,
    
    // Test files
    tests: true,
    
    // Storybook stories
    stories: true,
    
    // Documentation
    docs: true,
    
    // Component templates
    templates: {
      // Custom component template
      component: './templates/component.tsx',
      test: './templates/component.test.tsx',
      story: './templates/component.stories.tsx'
    }
  }
}

Component Organization

Configure component file structure.

module.exports = {
  components: {
    // File structure
    structure: {
      // Component file naming
      naming: 'kebab-case', // 'kebab-case', 'camelCase', 'PascalCase'
      
      // Index files
      indexFiles: true,
      
      // Barrel exports
      barrelExports: true,
      
      // Grouping
      grouping: 'feature', // 'feature', 'type', 'none'
      
      // Subdirectories
      subdirectories: {
        ui: 'components/ui',
        forms: 'components/forms',
        layout: 'components/layout'
      }
    }
  }
}

Testing Configuration

Test Framework

Configure testing setup.

module.exports = {
  testing: {
    // Test framework
    framework: 'jest', // 'jest', 'vitest', 'playwright'
    
    // Test environment
    environment: 'jsdom',
    
    // Coverage
    coverage: {
      enabled: true,
      threshold: {
        global: {
          branches: 80,
          functions: 80,
          lines: 80,
          statements: 80
        }
      },
      reporters: ['text', 'lcov', 'html']
    },
    
    // Test patterns
    patterns: {
      test: '**/*.{test,spec}.{js,jsx,ts,tsx}',
      ignore: ['**/node_modules/**', '**/dist/**']
    }
  }
}

Jest Configuration

Configure Jest-specific settings.

module.exports = {
  testing: {
    framework: 'jest',
    jest: {
      // Setup files
      setupFilesAfterEnv: ['<rootDir>/src/setupTests.ts'],
      
      // Module name mapping
      moduleNameMapping: {
        '^@/(.*)$': '<rootDir>/src/$1',
        '^@components/(.*)$': '<rootDir>/src/components/$1'
      },
      
      // Transform
      transform: {
        '^.+\\.(ts|tsx)$': 'ts-jest'
      },
      
      // Test environment
      testEnvironment: 'jsdom',
      
      // Coverage collection
      collectCoverageFrom: [
        'src/**/*.{js,jsx,ts,tsx}',
        '!src/**/*.d.ts',
        '!src/**/*.stories.{js,jsx,ts,tsx}'
      ]
    }
  }
}

Linting Configuration

ESLint Settings

Configure ESLint behavior.

module.exports = {
  linting: {
    eslint: {
      enabled: true,
      config: {
        extends: [
          'eslint:recommended',
          '@typescript-eslint/recommended',
          'plugin:react/recommended',
          'plugin:react-hooks/recommended'
        ],
        parser: '@typescript-eslint/parser',
        plugins: ['@typescript-eslint', 'react'],
        rules: {
          'react/react-in-jsx-scope': 'off',
          '@typescript-eslint/no-unused-vars': 'error',
          'prefer-const': 'error'
        }
      },
      ignorePatterns: ['dist/**', 'node_modules/**']
    }
  }
}

Prettier Settings

Configure Prettier formatting.

module.exports = {
  linting: {
    prettier: {
      enabled: true,
      config: {
        semi: false,
        singleQuote: true,
        tabWidth: 2,
        trailingComma: 'es5',
        printWidth: 80,
        bracketSpacing: true,
        arrowParens: 'avoid'
      },
      ignoreFiles: ['dist/**', 'node_modules/**', '*.min.js']
    }
  }
}

TypeScript Configuration

TypeScript Settings

Configure TypeScript behavior.

module.exports = {
  typescript: {
    enabled: true,
    config: {
      compilerOptions: {
        target: 'ES2020',
        lib: ['ES2020', 'DOM', 'DOM.Iterable'],
        module: 'ESNext',
        skipLibCheck: true,
        moduleResolution: 'bundler',
        allowImportingTsExtensions: true,
        resolveJsonModule: true,
        isolatedModules: true,
        noEmit: true,
        jsx: 'react-jsx',
        strict: true,
        noUnusedLocals: true,
        noUnusedParameters: true,
        noFallthroughCasesInSwitch: true
      },
      include: ['src'],
      exclude: ['node_modules', 'dist']
    }
  }
}

Documentation Configuration

Documentation Settings

Configure documentation generation.

module.exports = {
  documentation: {
    enabled: true,
    output: {
      directory: 'docs',
      format: 'mdx', // 'mdx', 'html', 'json'
      theme: 'default'
    },
    components: {
      include: ['src/components/**/*.{tsx,jsx}'],
      exclude: ['src/components/**/*.test.{tsx,jsx}'],
      templates: {
        component: './templates/component-doc.mdx',
        index: './templates/index.mdx'
      }
    },
    api: {
      enabled: true,
      output: 'api.json'
    }
  }
}

Environment Variables

Environment Configuration

Configure environment variable handling.

module.exports = {
  env: {
    // Environment file loading
    files: ['.env', '.env.local', '.env.development', '.env.production'],
    
    // Variable prefix
    prefix: 'FOUNDRYKIT_',
    
    // Default values
    defaults: {
      NODE_ENV: 'development',
      PORT: '3000',
      API_URL: 'http://localhost:8000'
    },
    
    // Required variables
    required: ['API_KEY', 'DATABASE_URL']
  }
}

Plugin Configuration

Plugin Settings

Configure CLI plugins.

module.exports = {
  plugins: [
    // Built-in plugins
    '@foundrykit/plugin-typescript',
    '@foundrykit/plugin-tailwind',
    
    // Custom plugins
    {
      name: 'my-custom-plugin',
      config: {
        // Plugin-specific configuration
      }
    }
  ],
  
  // Plugin configuration
  pluginConfig: {
    typescript: {
      strict: true,
      declaration: true
    },
    tailwind: {
      config: './tailwind.config.js',
      css: './src/styles/globals.css'
    }
  }
}

Advanced Configuration

Conditional Configuration

Use functions for dynamic configuration.

module.exports = function(env) {
  const isProduction = env === 'production'
  
  return {
    build: {
      sourcemap: !isProduction,
      minify: isProduction,
      outDir: isProduction ? 'build' : 'dist'
    },
    dev: {
      port: isProduction ? 8080 : 3000,
      open: !isProduction
    }
  }
}

Configuration Validation

Add validation to your configuration.

module.exports = {
  // Configuration validation
  validate: {
    project: {
      name: { required: true, type: 'string' },
      version: { required: true, pattern: /^\d+\.\d+\.\d+$/ }
    },
    build: {
      outDir: { required: true, type: 'string' },
      port: { type: 'number', min: 1, max: 65535 }
    }
  },
  
  // Actual configuration
  project: {
    name: 'my-project',
    version: '1.0.0'
  },
  build: {
    outDir: 'dist',
    port: 3000
  }
}

Configuration Examples

Minimal Configuration

module.exports = {
  project: {
    name: 'my-project'
  }
}

Full Configuration

module.exports = {
  project: {
    name: 'my-foundrykit-project',
    version: '1.0.0',
    description: 'A comprehensive FoundryKit project'
  },
  
  build: {
    outDir: 'dist',
    sourcemap: true,
    minify: true
  },
  
  dev: {
    port: 3000,
    host: 'localhost',
    open: true
  },
  
  components: {
    directory: 'src/components',
    typescript: true,
    tests: true
  },
  
  testing: {
    framework: 'jest',
    coverage: true
  },
  
  linting: {
    eslint: true,
    prettier: true
  }
}

Next Steps

Command Reference

Complete reference for all FoundryKit CLI commands

Advanced Usage

Advanced CLI workflows and complex project setups