feat(angular-rspack): improve createConfig public api (#35)

* feat(angular-rspack): improve `createConfig` public api

* feat(angular-rspack): warn about currently unsupported options

Author: leosvelperez

packages/angular-rspack/src/lib/config/create-config.unit.test.ts

@@ -18,7 +18,6 @@ describe('createConfig', () => {
     outputHashing: 'all',
     scripts: [],
     aot: true,
-    hasServer: false,
     skipTypeChecking: false,
   };
 
@@ -27,6 +26,10 @@ describe('createConfig', () => {
     vi.stubEnv('NGRS_CONFIG', '');
   });
 
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
   it('should create config for mode "production" if env variable NODE_ENV is "production"', async () => {
     vi.stubEnv('NODE_ENV', 'production');
     await expect(_createConfig(configBase)).resolves.toStrictEqual([
@@ -118,6 +121,31 @@ describe('createConfig', () => {
       ]);
     });
 
+    it('should create config even when known unsupported options are provided and warn about them', async () => {
+      const warnSpy = vi.spyOn(console, 'warn');
+
+      await expect(
+        createConfig({
+          options: {
+            ...configBase,
+            clearScreen: true,
+            devServer: { allowedHosts: ['localhost'] },
+          },
+        })
+      ).resolves.not.toContain([
+        expect.objectContaining({
+          clearScreen: true,
+          devServer: { allowedHosts: ['localhost'] },
+        }),
+      ]);
+      expect(warnSpy).toHaveBeenCalledWith(
+        `The following options are not yet supported:
+  "clearScreen"
+  "devServer.allowedHosts"
+`
+      );
+    });
+
     it('should create config from options with a custom root', async () => {
       const customRoot = join(process.cwd(), 'custom-root');
 

packages/angular-rspack/src/lib/models/angular-rspack-plugin-options.ts

@@ -3,8 +3,12 @@ import type {
   InlineStyleLanguage,
   StylePreprocessorOptions,
 } from '@nx/angular-rspack-compiler';
+import type {
+  DevServerUnsupportedOptions,
+  PluginUnsupportedOptions,
+} from './unsupported-options';
 
-export interface DevServerOptions {
+export interface DevServerOptions extends DevServerUnsupportedOptions {
   port?: number;
   ssl?: boolean;
   sslKey?: string;
@@ -76,57 +80,63 @@ export interface SourceMap {
   vendor: boolean;
 }
 
-export interface AngularRspackPluginOptions {
-  index: IndexElement;
-  browser: string;
+export interface AngularRspackPluginOptions extends PluginUnsupportedOptions {
+  aot?: boolean;
+  assets?: AssetElement[];
+  browser?: string;
+  commonChunk?: boolean;
+  devServer?: DevServerOptions;
+  extractLicenses?: boolean;
+  fileReplacements?: FileReplacement[];
+  index?: IndexElement;
+  inlineStyleLanguage?: InlineStyleLanguage;
+  namedChunks?: boolean;
+  optimization?: boolean | OptimizationOptions;
+  outputHashing?: OutputHashing;
+  outputPath?:
+    | string
+    | (Required<Pick<OutputPath, 'base'>> & Partial<OutputPath>);
+  polyfills?: string[];
+  root?: string;
+  scripts?: ScriptOrStyleEntry[];
   server?: string;
+  skipTypeChecking?: boolean;
+  sourceMap?: boolean | Partial<SourceMap>;
   ssr?:
     | boolean
     | {
         entry: string;
         experimentalPlatform?: 'node' | 'neutral';
       };
-  polyfills: string[];
-  assets?: AssetElement[];
+  stylePreprocessorOptions?: StylePreprocessorOptions;
   styles?: ScriptOrStyleEntry[];
-  scripts?: ScriptOrStyleEntry[];
-  outputPath:
-    | string
-    | (Required<Pick<OutputPath, 'base'>> & Partial<OutputPath>);
-  fileReplacements: FileReplacement[];
-  aot: boolean;
-  inlineStyleLanguage: InlineStyleLanguage;
-  tsConfig: string;
-  hasServer: boolean;
-  sourceMap?: boolean | Partial<SourceMap>;
-  skipTypeChecking: boolean;
+  tsConfig?: string;
   useTsProjectReferences?: boolean;
-  optimization?: boolean | OptimizationOptions;
-  outputHashing?: OutputHashing;
-  stylePreprocessorOptions?: StylePreprocessorOptions;
-  namedChunks?: boolean;
   vendorChunk?: boolean;
-  commonChunk?: boolean;
-  devServer?: DevServerOptions;
-  extractLicenses?: boolean;
-  root?: string;
 }
 
 export interface NormalizedAngularRspackPluginOptions
   extends Omit<AngularRspackPluginOptions, 'index' | 'scripts' | 'styles'> {
   advancedOptimizations: boolean;
+  aot: boolean;
   assets: NormalizedAssetElement[];
-  index: NormalizedIndexElement | undefined;
+  browser: string;
+  commonChunk: boolean;
   devServer: DevServerOptions & { port: number };
   extractLicenses: boolean;
-  namedChunks: boolean;
-  vendorChunk: boolean;
-  commonChunk: boolean;
+  fileReplacements: FileReplacement[];
   globalScripts: GlobalEntry[];
   globalStyles: GlobalEntry[];
+  index: NormalizedIndexElement | undefined;
+  inlineStyleLanguage: InlineStyleLanguage;
+  hasServer: boolean;
+  namedChunks: boolean;
   optimization: boolean | OptimizationOptions;
   outputHashing: OutputHashing;
   outputPath: OutputPath;
+  polyfills: string[];
   root: string;
   sourceMap: SourceMap;
+  tsConfig: string;
+  vendorChunk: boolean;
 }

packages/angular-rspack/src/lib/models/normalize-options.ts

@@ -27,9 +27,13 @@ import type {
   NormalizedAssetElement,
   NormalizedIndexElement,
   OutputPath,
-  SourceMap,
   ScriptOrStyleEntry,
+  SourceMap,
 } from './angular-rspack-plugin-options';
+import {
+  DEV_SERVER_OPTIONS_PENDING_SUPPORT,
+  TOP_LEVEL_OPTIONS_PENDING_SUPPORT,
+} from './unsupported-options';
 
 export const INDEX_HTML_CSR = 'index.csr.html';
 
@@ -97,9 +101,35 @@ export function validateOptimization(
     );
 }
 
+function validateGeneralUnsupportedOptions(
+  options: AngularRspackPluginOptions
+) {
+  const topLevelUnsupportedOptions = TOP_LEVEL_OPTIONS_PENDING_SUPPORT.filter(
+    (option) => options[option] !== undefined
+  ).sort();
+  const devServerUnsupportedOptions = DEV_SERVER_OPTIONS_PENDING_SUPPORT.filter(
+    (option) => options.devServer?.[option] !== undefined
+  ).sort();
+
+  const unsupportedOptions = [
+    ...topLevelUnsupportedOptions.map((option) => `"${option}"`),
+    ...devServerUnsupportedOptions.map((option) => `"devServer.${option}"`),
+  ];
+
+  if (unsupportedOptions.length > 0) {
+    console.warn(
+      `The following options are not yet supported:\n  ${unsupportedOptions.join(
+        '\n  '
+      )}\n`
+    );
+  }
+}
+
 export function normalizeOptions(
   options: AngularRspackPluginOptions
 ): NormalizedAngularRspackPluginOptions {
+  validateGeneralUnsupportedOptions(options);
+
   const { fileReplacements = [], server, ssr, optimization } = options;
 
   validateSsr(ssr);
@@ -146,6 +176,8 @@ export function normalizeOptions(
       'Disabling the "index" option is not yet supported. Defaulting to "src/index.html".'
     );
     options.index = join(root, 'src/index.html');
+  } else if (!options.index) {
+    options.index = join(root, 'src/index.html');
   }
 
   let index: NormalizedIndexElement | undefined;
@@ -206,32 +238,32 @@ export function normalizeOptions(
   }
 
   return {
-    index,
-    browser: options.browser ?? './src/main.ts',
-    ...(server ? { server } : {}),
-    ...(ssr ? { ssr: normalizedSsr } : {}),
-    optimization: normalizedOptimization,
     advancedOptimizations,
-    polyfills: options.polyfills ?? [],
     assets,
+    aot,
+    browser: options.browser ?? './src/main.ts',
+    commonChunk: options.commonChunk ?? true,
+    devServer: normalizeDevServer(options.devServer),
+    extractLicenses: options.extractLicenses ?? true,
+    fileReplacements: resolveFileReplacements(fileReplacements, root),
     globalStyles,
     globalScripts,
-    outputPath: normalizeOutputPath(root, options.outputPath),
-    fileReplacements: resolveFileReplacements(fileReplacements, root),
-    aot,
-    outputHashing: options.outputHashing ?? 'all',
-    inlineStyleLanguage: options.inlineStyleLanguage ?? 'css',
-    tsConfig,
-    sourceMap: normalizeSourceMap(options.sourceMap),
     hasServer: getHasServer(root, server, normalizedSsr),
+    index,
+    inlineStyleLanguage: options.inlineStyleLanguage ?? 'css',
+    namedChunks: options.namedChunks ?? false,
+    optimization: normalizedOptimization,
+    outputHashing: options.outputHashing ?? 'all',
+    outputPath: normalizeOutputPath(root, options.outputPath),
+    polyfills: options.polyfills ?? [],
+    root,
+    server,
     skipTypeChecking: options.skipTypeChecking ?? false,
+    sourceMap: normalizeSourceMap(options.sourceMap),
+    ssr: normalizedSsr,
+    tsConfig,
     useTsProjectReferences: options.useTsProjectReferences ?? false,
-    namedChunks: options.namedChunks ?? false,
     vendorChunk: options.vendorChunk ?? false,
-    commonChunk: options.commonChunk ?? true,
-    devServer: normalizeDevServer(options.devServer),
-    extractLicenses: options.extractLicenses ?? true,
-    root,
   };
 }
 

packages/angular-rspack/src/lib/models/unsupported-options.ts

@@ -0,0 +1,111 @@
+export type BudgetEntry = {
+  type:
+    | 'all'
+    | 'allScript'
+    | 'any'
+    | 'anyScript'
+    | 'anyComponentStyle'
+    | 'bundle'
+    | 'initial';
+  name?: string;
+  baseline?: string;
+  maximumWarning?: string;
+  maximumError?: string;
+  minimumWarning?: string;
+  minimumError?: string;
+  warning?: string;
+  error?: string;
+};
+
+export interface DevServerUnsupportedOptions {
+  allowedHosts?: string[] | boolean;
+  headers?: Record<string, string>;
+  open?: boolean;
+  liveReload?: boolean;
+  servePath?: string;
+  hmr?: boolean;
+  inspect?: string | boolean;
+  prebundle?:
+    | boolean
+    | {
+        exclude: string[];
+      };
+}
+
+export interface PluginUnsupportedOptions {
+  deployUrl?: string;
+  security?: {
+    autoCsp?:
+      | boolean
+      | {
+          unsafeEval?: boolean;
+        };
+  };
+  externalDependencies?: string[];
+  clearScreen?: boolean;
+  define?: Record<string, string>;
+  baseHref?: string;
+  verbose?: boolean;
+  progress?: boolean;
+  i18nMissingTranslation?: 'warning' | 'error' | 'ignore';
+  i18nDuplicateTranslation?: 'warning' | 'error' | 'ignore';
+  localize?: boolean | string[];
+  watch?: boolean;
+  poll?: number;
+  deleteOutputPath?: boolean;
+  preserveSymlinks?: boolean;
+  subresourceIntegrity?: boolean;
+  serviceWorker?: string | false;
+  statsJson?: boolean;
+  budgets?: BudgetEntry[];
+  webWorkerTsConfig?: string;
+  crossOrigin?: 'none' | 'anonymous' | 'use-credentials';
+  allowedCommonJsDependencies?: string[];
+  prerender?:
+    | boolean
+    | {
+        routesFile?: string;
+        discoverRoutes?: boolean;
+      };
+  appShell?: boolean;
+  outputMode?: 'static' | 'server';
+}
+
+export const TOP_LEVEL_OPTIONS_PENDING_SUPPORT = [
+  'deployUrl',
+  'security',
+  'externalDependencies',
+  'clearScreen',
+  'define',
+  'baseHref',
+  'verbose',
+  'progress',
+  'i18nMissingTranslation',
+  'i18nDuplicateTranslation',
+  'localize',
+  'watch',
+  'poll',
+  'deleteOutputPath',
+  'preserveSymlinks',
+  'subresourceIntegrity',
+  'serviceWorker',
+  'statsJson',
+  'budgets',
+  'webWorkerTsConfig',
+  'crossOrigin',
+  'allowedCommonJsDependencies',
+  'prerender',
+  'appShell',
+  'outputMode',
+];
+
+export const DEV_SERVER_OPTIONS_PENDING_SUPPORT = [
+  'allowedHosts',
+  'headers',
+  'open',
+  'liveReload',
+  'servePath',
+  'hmr',
+  'inspect',
+  'prebundle',
+];