App Configuration Management

/**
 * Helper class for managing Taro app configuration and entry points
 * Handles parsing of Taro app structure, pages, components, and configurations
 */
class AppHelper {
  /**
   * Creates an AppHelper instance
   * @param entry - Webpack entry configuration or path (defaults to empty object)
   * @param options - Configuration options for the helper (defaults to empty object)
   */
  constructor(entry?: TEntry, options?: Partial<IOptions>);
  
  /** Returns the main app entry file path */
  readonly appEntry: string;
  
  /** Returns parsed Taro app configuration object */
  readonly appConfig: AppConfig;
  
  /** Returns Set of page objects with name and path properties */
  readonly pages: Set<{ name: string; path: string }>;
  
  /** Returns Set of component objects with name and path properties (only for native component builds) */
  readonly comps: Set<{ name: string; path: string }>;
  
  /** Returns Map of page names to their config file paths */
  readonly pagesConfigList: Map<string, string>;
  
  /** Returns Map of component names to their config file paths */
  readonly compsConfigList: Map<string, string>;
  
  /**
   * Returns config file path for the given file path
   * @param filePath - Source file path to get config for
   * @returns Path to the corresponding config file
   */
  getConfigFilePath(filePath: string): string;
  
  /** Clears all cached configuration data */
  clear(): void;
}

import { AppHelper } from "@tarojs/webpack-runner";

// Basic usage with default options
const appHelper = new AppHelper("./src/app.tsx", {
  sourceDir: "/path/to/src",
  entryFileName: "app",
  frameworkExts: [".tsx", ".ts", ".jsx", ".js"]
});

// Access app configuration
console.log(appHelper.appConfig.pages); // Array of page paths
console.log(appHelper.appConfig.window); // Window configuration

// Iterate through pages
appHelper.pages.forEach(({ name, path }) => {
  console.log(`Page: ${name} at ${path}`);
  const configPath = appHelper.getConfigFilePath(path);
  console.log(`Config: ${configPath}`);
});

// Work with components (only available for native component builds)
try {
  if (appHelper.appConfig.components) {
    appHelper.comps.forEach(({ name, path }) => {
      console.log(`Component: ${name} at ${path}`);
    });
  }
} catch (error) {
  // Components field not available in H5 builds
  console.log("Components not configured for this build type");
}

// Advanced entry configuration
const complexAppHelper = new AppHelper({
  app: ["./src/app.tsx", "./src/polyfills.ts"],
  vendor: ["react", "react-dom"]
}, {
  sourceDir: "/project/src",
  frameworkExts: [".tsx", ".ts"],
  modifyAppConfig: (config) => {
    // Modify app config before processing
    config.window.navigationBarTitleText = "My App";
  }
});

/**
 * Taro app configuration interface
 */
interface AppConfig {
  pages?: string[];
  components?: string[];
  window?: WindowConfig;
  tabBar?: TabBarConfig;
  subPackages?: SubPackageConfig[];
  subpackages?: SubPackageConfig[]; // Alternative spelling
  entryPagePath?: string;
  // Additional Taro-specific configuration properties
}

interface WindowConfig {
  navigationBarTitleText?: string;
  navigationBarBackgroundColor?: string;
  backgroundColor?: string;
  // Additional window configuration properties
}

interface TabBarConfig {
  color?: string;
  selectedColor?: string;
  backgroundColor?: string;
  list: TabBarItem[];
  // Additional tab bar configuration properties
}

interface TabBarItem {
  pagePath: string;
  text: string;
  iconPath?: string;
  selectedIconPath?: string;
}

interface SubPackageConfig {
  root: string;
  pages: string[];
  // Additional subpackage configuration properties
}

/**
 * Returns the main app entry file path
 * Handles various entry configuration formats
 */
readonly appEntry: string;

/**
 * Returns config file path for the given file path
 * Automatically resolves .config extensions
 * @param filePath - Source file path (e.g., "src/pages/index/index.tsx")
 * @returns Config file path (e.g., "src/pages/index/index.config.ts")
 */
getConfigFilePath(filePath: string): string;

/**
 * Clears all cached configuration data
 * Useful for rebuilding configuration after changes
 */
clear(): void;

// Example of how AppHelper processes configurations
const appHelper = new AppHelper("./src/app.tsx", options);

// 1. App entry resolution
const entryPath = appHelper.appEntry; 
// Resolves to actual file path: "/project/src/app.tsx"

// 2. App config parsing
const config = appHelper.appConfig;
// Parses app.config.js/ts and returns structured configuration

// 3. Pages processing
const pages = appHelper.pages;
// Processes pages array and subpackages, resolving file paths
// Set([
//   { name: "pages/index/index", path: "/project/src/pages/index/index.tsx" },
//   { name: "pages/profile/profile", path: "/project/src/pages/profile/profile.tsx" }
// ])

// 4. Config file mapping
const pageConfigs = appHelper.pagesConfigList;
// Maps page names to their config file paths
// Map([
//   ["pages/index/index", "/project/src/pages/index/index.config.ts"],
//   ["pages/profile/profile", "/project/src/pages/profile/profile.config.ts"]
// ])

// Missing app configuration
try {
  const config = appHelper.appConfig;
} catch (error) {
  // Throws: "缺少 app 全局配置，请检查！"
}

// Missing pages configuration
try {
  const pages = appHelper.pages;
} catch (error) {
  // Throws: "全局配置缺少 pages 字段，请检查！"
}

// Missing components configuration (when accessed)
try {
  const comps = appHelper.comps;
} catch (error) {
  // Throws: "全局配置缺少 components 字段，请检查！"
}

// App config with subpackages
const appConfig = {
  pages: ["pages/index/index"],
  subPackages: [
    {
      root: "packageA",
      pages: ["pages/cat/cat", "pages/dog/dog"]
    },
    {
      root: "packageB", 
      pages: ["pages/apple/apple"]
    }
  ]
};

// AppHelper processes all pages including subpackage pages
const allPages = appHelper.pages;
// Includes main pages and subpackage pages with proper root prefixes