CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-ice--app

A universal framework based on React.js that provides scripts and configuration for web development with zero-config support for ES6+, TypeScript, routing, state management, and multi-platform deployment.

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

configuration.mddocs/

Configuration Management

Ice.js provides comprehensive configuration management through the defineConfig function and UserConfig interface, enabling developers to customize every aspect of the build and development process with full TypeScript support.

Capabilities

Define Configuration

Creates a typed configuration object with validation and intelligent defaults.

/**
 * Define framework configuration with TypeScript support and validation
 * @param config - Configuration object or function returning configuration
 * @returns Validated UserConfig object
 */
function defineConfig(config: UserConfig | (() => UserConfig)): UserConfig;

Usage Examples:

import { defineConfig } from "@ice/app";

// Object configuration
export default defineConfig({
  outputDir: 'build',
  publicPath: '/my-app/',
  hash: true,
  plugins: []
});

// Function configuration (for dynamic config)
export default defineConfig(() => {
  const isProduction = process.env.NODE_ENV === 'production';
  
  return {
    outputDir: isProduction ? 'dist' : 'dev',
    minify: isProduction,
    sourceMap: !isProduction
  };
});

Build Configuration

Configure build output, asset handling, and optimization settings.

interface BuildConfig {
  /** Build output directory (default: 'build') */
  outputDir?: string;
  /** Public path for assets (default: '/') */
  publicPath?: string;
  /** Development public path override */
  devPublicPath?: string;
  /** Enable filename hashing for cache busting */
  hash?: boolean | string;
  /** Code minification settings */
  minify?: boolean | MinifyOptions;
  /** Source map generation */
  sourceMap?: boolean | 'inline' | 'hidden' | 'nosources-cheap-source-map';
  /** Cross-origin loading for dynamic imports */
  crossOriginLoading?: 'anonymous' | 'use-credentials' | false;
  /** Output filename pattern for built bundles */
  filename?: string;
}

interface MinifyOptions {
  type: 'terser' | 'swc';
  options?: Record<string, any>;
}

Module Configuration

Configure module resolution, aliases, and external dependencies.

interface ModuleConfig {
  /** Module path aliases for import resolution */
  alias?: Record<string, string>;
  /** External dependencies to exclude from bundle */
  externals?: Record<string, string> | string[];
  /** Dependencies to compile (instead of treating as external) */
  compileDependencies?: string[];
  /** Global constant definitions for DefinePlugin */
  define?: Record<string, any>;
  /** Legacy browser polyfill configuration */
  polyfill?: boolean | 'entry' | 'usage';
}

Usage Examples:

export default defineConfig({
  alias: {
    '@': './src',
    '@components': './src/components',
    '@utils': './src/utils'
  },
  externals: {
    'react': 'React',
    'react-dom': 'ReactDOM'
  },
  define: {
    __VERSION__: JSON.stringify(process.env.npm_package_version),
    __DEV__: process.env.NODE_ENV === 'development'
  }
});

Development Configuration

Configure development server, proxying, and hot reload behavior.

interface DevelopmentConfig {
  /** Development server proxy configuration */
  proxy?: Record<string, ProxyConfig>;
  /** Mock service configuration */
  mock?: MockConfig | boolean;
  /** Force cache directory removal on start */
  force?: boolean;
  /** Development server host */
  host?: string;
  /** Development server port */
  port?: number;
  /** Enable HTTPS */
  https?: boolean | 'self-signed';
  /** Automatically open browser */
  open?: boolean | string;
}

interface ProxyConfig {
  target: string;
  changeOrigin?: boolean;
  pathRewrite?: Record<string, string>;
  headers?: Record<string, string>;
}

interface MockConfig {
  exclude?: string[];
  include?: string[];
}

Styling Configuration

Configure CSS processing, modules, and PostCSS plugins.

interface StylingConfig {
  /** CSS Modules configuration */
  cssModules?: boolean | CSSModulesConfig;
  /** PostCSS configuration */
  postcss?: PostCSSConfig;
  /** Global style glob patterns */
  globalStyleGlobPattern?: string[];
}

interface CSSModulesConfig {
  /** Local class name generation pattern */
  localIdentName?: string;
  /** Hash digest method */
  hashPrefix?: string;
  /** Generate source maps for CSS modules */
  generateScopedName?: (name: string, filename: string, css: string) => string;
}

interface PostCSSConfig {
  plugins?: any[];
  options?: Record<string, any>;
}

Routing Configuration

Configure file-system based routing and route generation.

interface RoutesConfig {
  /** Files to ignore during route generation */
  ignoreFiles?: string[];
  /** Custom route definitions */
  defineRoutes?: (defineRoute: DefineRouteFunction) => void;
  /** Route-specific configuration */
  config?: Record<string, RouteConfig>;
  /** Initial entry injection configuration */
  injectInitialEntry?: boolean | InjectInitialEntryConfig;
}

interface RouteConfig {
  title?: string;
  meta?: Record<string, any>;
  auth?: boolean | string[];
}

Server Configuration

Configure server-side rendering and compilation settings.

interface ServerConfig {
  /** Enable server-side rendering */
  onDemand?: boolean;
  /** Server output format */
  format?: 'esm' | 'cjs';
  /** Server bundling configuration */
  bundle?: boolean;
  /** Files to ignore in server compilation */
  ignores?: string[];
  /** Server external dependencies */
  externals?: string[];
  /** Bundler selection for server */
  bundler?: 'webpack' | 'rspack';
  /** Custom webpack configuration for server */
  webpackConfig?: (config: WebpackConfig) => WebpackConfig;
}

Plugin Configuration

Configure and extend Ice.js functionality through plugins.

interface PluginConfig {
  /** Plugin array for extending framework functionality */
  plugins?: Plugin[];
}

interface Plugin<Options = any> {
  (api: PluginAPI, options?: Options): void;
}

interface PluginAPI {
  /** Register build hooks */
  onHook: (name: string, fn: Function) => void;
  /** Modify webpack configuration */
  modifyWebpackConfig: (fn: ModifyWebpackConfig) => void;
  /** Add runtime options */
  addRuntimeOptions: (options: RuntimeOptions) => void;
  /** Register generator plugins */
  addPlugin: (plugin: GeneratorPlugin) => void;
}

Optimization Configuration

Configure build optimizations and performance settings.

interface OptimizationConfig {
  /** Router optimization (remove when single route) */
  router?: boolean;
  /** Force disable router dependencies */
  disableRouter?: boolean;
  /** Package import optimization for barrel files */
  optimizePackageImport?: string[] | boolean;
}

interface CodeSplittingConfig {
  /** Enable code splitting */
  codeSplitting?: boolean | 'page-only' | 'depot-granular';
}

Rendering Configuration

Configure rendering modes and static generation.

interface RenderingConfig {
  /** Enable server-side rendering */
  ssr?: boolean;
  /** Enable static site generation */
  ssg?: boolean;
  /** Data loading capabilities */
  dataLoader?: boolean;
  /** HTML generation configuration */
  htmlGenerating?: HtmlGeneratingConfig;
}

interface HtmlGeneratingConfig {
  /** Generation mode */
  mode?: 'cleanUrl' | 'compat';
  /** Custom HTML template */
  template?: string;
  /** Inject runtime configuration */
  inject?: boolean;
}

Developer Experience Configuration

Configure development tools and quality checks.

interface DeveloperExperienceConfig {
  /** TypeScript type checking */
  tsChecker?: boolean;
  /** ESLint integration */
  eslint?: boolean | ESLintConfig;
  /** Console log levels to drop in production */
  dropLogLevel?: ('trace' | 'debug' | 'log' | 'info' | 'warn' | 'error')[];
  /** Bundle analyzer integration */
  analyzer?: boolean;
  /** Speedup with Rust tools */
  speedup?: boolean;
}

interface ESLintConfig {
  files?: string[];
  exclude?: string[];
  options?: Record<string, any>;
}

Advanced Configuration

Configure experimental features and advanced build settings.

interface AdvancedConfig {
  /** Experimental features */
  experimental?: ExperimentalConfig;
  /** Code transformation rules */
  transform?: TransformConfig;
  /** Syntax feature flags */
  syntaxFeatures?: SyntaxFeatures;
  /** Feature polyfill configuration */
  featurePolyfill?: PolyfillConfig;
  /** Direct webpack configuration modification (not recommended) */
  webpack?: (config: WebpackConfig, { webpack }: { webpack: any }) => WebpackConfig;
  /** Data loading configuration for SSR/SSG */
  dataLoader?: boolean | DataLoaderConfig;
}

interface ExperimentalConfig {
  /** Experimental router features */
  router?: boolean;
  /** Experimental build features */
  build?: Record<string, any>;
}

interface SyntaxFeatures {
  /** Export default from syntax */
  exportDefaultFrom?: boolean;
  /** Function bind operator */
  functionBind?: boolean;
}

interface TransformConfig {
  /** File patterns and transform rules */
  [pattern: string]: {
    loader?: string;
    options?: Record<string, any>;
  };
}

interface DataLoaderConfig {
  /** Custom fetcher configuration */
  fetcher?: {
    packageName: string;
    method?: string;
  };
}

interface PolyfillConfig {
  /** AbortController polyfill for legacy browsers */
  abortcontroller?: boolean | string;
}

Complete Configuration Example

import { defineConfig } from "@ice/app";

export default defineConfig({
  // Build configuration
  outputDir: 'dist',
  publicPath: '/',
  hash: true,
  minify: {
    type: 'swc',
    options: {
      compress: true,
      mangle: true
    }
  },
  sourceMap: 'hidden',

  // Module configuration
  alias: {
    '@': './src',
    '@components': './src/components',
    '@utils': './src/utils'
  },
  define: {
    __VERSION__: JSON.stringify('1.0.0'),
    __API_URL__: JSON.stringify(process.env.API_URL)
  },

  // Development configuration
  proxy: {
    '/api': {
      target: 'http://localhost:8080',
      changeOrigin: true,
      pathRewrite: {
        '^/api': ''
      }
    }
  },
  mock: {
    exclude: ['**/components/**']
  },

  // Styling configuration
  cssModules: {
    localIdentName: '[name]__[local]--[hash:base64:5]'
  },
  postcss: {
    plugins: [
      require('autoprefixer'),
      require('postcss-preset-env')
    ]
  },

  // Routing configuration
  routes: {
    ignoreFiles: ['**/components/**', '**/*.test.*'],
    config: {
      '/admin': {
        auth: ['admin'],
        title: 'Admin Panel'
      }
    }
  },

  // Server configuration
  server: {
    format: 'esm',
    bundle: true,
    externals: ['react', 'react-dom']
  },

  // Optimization configuration
  optimization: {
    router: true,
    optimizePackageImport: ['antd', 'lodash']
  },

  // Rendering configuration
  ssr: true,
  ssg: false,
  dataLoader: true,

  // Developer experience
  tsChecker: true,
  eslint: {
    files: ['src/**/*.{ts,tsx}'],
    exclude: ['**/*.test.*']
  },
  dropLogLevel: ['debug', 'trace'],

  // Plugins
  plugins: [
    // Custom plugins
  ]
});

docs

analysis.md

cli.md

configuration.md

index.md

logging.md

service.md

testing.md

types.md

tile.json