Forem: fonlow

Automate Your Full-stack Development on ASP.NET Core Web API and Angular With Code Generator and AI Code Agent

fonlow — Fri, 10 Apr 2026 23:58:48 +0000

User Story

As a full stack software developer, after developing ASP.NET Web API with data validations in the Web API bindings, I would like the SPA on Angular framework to have client side validations to reduce round trips of related data error and improve user experience.

Functional requirements.

When user input invalid data, the GUI should respond with warning or error message.
Invalid data cannot be submitted to the backend.

Technical requirements

Strictly typed reactive forms.
Use built-in validators along with FormControl.
Develop custom validators if necessarily.
Look for 3rd party solutions including AI code agent before hand-crafting codes. For example, the 3rd party code generator or AI should transform some validation attributes of .NET to validators of Angular.
For numeric .NET types like byte, integer, uint, and int64 etc., the client side validations should be applied.

Backend with .NET Integral Types and Validation Attributes

POCO Class and API function:

    public class IntegralEntity
    {
        public sbyte SByte { get; set; }

        public byte Byte { get; set; }

        public short Short { get; set; }

        public ushort UShort { get; set; }

        public int Int { get; set; }

        public uint UInt { get; set; }

        [Range(-1000, 1000000)]
        public int ItemCount { get; set; }
    }

    public class MixedDataEntity : IntegralEntity
    {
        public DateOnly DOB { get; set; }

        [System.ComponentModel.DataAnnotations.Required]//MVC and Web API care about only this
        [MinLength(2), MaxLength(255)]
        public string Name { get; set; }

        [RegularExpression(@"^(https?:\/\/)?[da-z.-]+.[a-z.]{2,6}([/\w .-]*)*\/?$")]
        public Uri Web { get; set; }

        [EmailAddress, MaxLength(255)]
        public string EmailAddress { get; set; }
    }

        [HttpPost("MixedDataEntity")]
        public MixedDataEntity PostMixedDataEntity([FromBody] MixedDataEntity entity)
        {
            return entity;
        }

Generate TypeScript Code for Angular Reactive Forms

Utilize WebApiClientGen, with plugin "Fonlow.WebApiClientGenCore.NG2FormGroup".

Application Programming with Generated Code

Generated TypeScript code:

    export interface IntegralEntity {

        /** Type: byte, 0 to 255 */
        byte?: number | null;

        /** Type: int, -2,147,483,648 to 2,147,483,647 */
        int?: number | null;

        /**
         * Type: int
         * Range: inclusive between -1000 and 1000000
         */
        itemCount?: number | null;

        /** Type: sbyte, -128 to 127 */
        sByte?: number | null;

        /** Type: short, -32,768 to 32,767 */
        short?: number | null;

        /** Type: uint, 0 to 4,294,967,295 */
        uInt?: number | null;

        /** Type: ushort, 0 to 65,535 */
        uShort?: number | null;
    }
    export function CreateIntegralEntityFormGroup() {
        return new FormGroup({
            byte: new FormControl<number | null | undefined>(undefined, [Validators.min(0), Validators.max(255)]),
            int: new FormControl<number | null | undefined>(undefined, [Validators.min(-2147483648), Validators.max(2147483647)]),
            itemCount: new FormControl<number | null | undefined>(undefined, [Validators.min(-1000), Validators.max(1000000)]),
            sByte: new FormControl<number | null | undefined>(undefined, [Validators.min(-128), Validators.max(127)]),
            short: new FormControl<number | null | undefined>(undefined, [Validators.min(-32768), Validators.max(32767)]),
            uInt: new FormControl<number | null | undefined>(undefined, [Validators.min(0), Validators.max(4294967295)]),
            uShort: new FormControl<number | null | undefined>(undefined, [Validators.min(0), Validators.max(65535)]),
        });

    }

    export interface MixedDataEntity extends DemoWebApi_DemoData_Client.IntegralEntity {

        /** Type: DateOnly */
        dob?: Date | null;

        /** Max length: 255 */
        emailAddress?: string | null;

        /**
         * Required. Null or empty is invalid.
         * Min length: 2
         * Max length: 255
         */
        name: string;

        /**
         * Type: Uri
         * Regex pattern: ^(https?:\\/\\/)?[da-z.-]+.[a-z.]\{2,6\}([\/\w .-]\*)\*\\/?$
         */
        web?: string | null;
    }
    export function CreateMixedDataEntityFormGroup() {
        return new FormGroup({
            byte: new FormControl<number | null | undefined>(undefined, [Validators.min(0), Validators.max(255)]),
            int: new FormControl<number | null | undefined>(undefined, [Validators.min(-2147483648), Validators.max(2147483647)]),
            itemCount: new FormControl<number | null | undefined>(undefined, [Validators.min(-1000), Validators.max(1000000)]),
            sByte: new FormControl<number | null | undefined>(undefined, [Validators.min(-128), Validators.max(127)]),
            short: new FormControl<number | null | undefined>(undefined, [Validators.min(-32768), Validators.max(32767)]),
            uInt: new FormControl<number | null | undefined>(undefined, [Validators.min(0), Validators.max(4294967295)]),
            uShort: new FormControl<number | null | undefined>(undefined, [Validators.min(0), Validators.max(65535)]),
            dob: CreateDateOnlyFormControl(),
            emailAddress: new FormControl<string | null | undefined>(undefined, [Validators.email, Validators.maxLength(255)]),
            name: new FormControl<string | null>(null, [Validators.required, Validators.minLength(2), Validators.maxLength(255)]),
            web: new FormControl<string | null | undefined>(undefined, [Validators.pattern(/^(https?:\/\/)?[da-z.-]+.[a-z.]{2,6}([/\w .-]*)*\/?$/)]),
        });

    }

        /**
         * POST api/Entities/MixedDataEntity
         */
        postMixedDataEntity(entity?: DemoWebApi_DemoData_Client.MixedDataEntity | null, headersHandler?: () => HttpHeaders): Observable<DemoWebApi_DemoData_Client.MixedDataEntity> {
            return this.http.post<DemoWebApi_DemoData_Client.MixedDataEntity>(this.baseUri + 'api/Entities/MixedDataEntity', JSON.stringify(entity), { headers: headersHandler ? headersHandler().append('Content-Type', 'application/json;charset=UTF-8') : new HttpHeaders({ 'Content-Type': 'application/json;charset=UTF-8' }) });
        }

Create Data Edit Form Through ChatGPT

It is the normal ChatGPT, while you are welcome to try Plus, Codex, or Claude AI etc. And I gave the following prompt:

Prompt

For Angular Reactive Forms programming of Angular 21 along with Angular Material Components, I have the following TypeScript codes about the data models and FormGroup declarations:

...The ts code block above except the generated client API POST call...
...

and I would like you to:

Craft a data entry component for data fields of data model MixedDataEntity, with FormGroup object created by CreateMixedDataEntityFormGroup(), and the expect output is data-detail.component.ts and data-detail.component.html
The HTML template are composed with matFormField and matInput and formControlName etc.
MatHint of each FormField hints about data constraints.
Only when the matInput gets focused, the matHint is shown.
MatError for showing validation errors
Use @if instead of *ngIf.

Generated Component

With minor modification, I get the following:

Compare with Other AI Code Agents

Please check the online demo.

Through ChatGPT Codex

I use the Codex extension of Visual Studio Code.

Codex is surely smarter than generic ChatGPT, especially when it is integrated with Visual Studio Code, at least for better Developer Experience.

Rather the inlining error messages in the HTML template, the code agent aggregates error messages into the TS file. And Codex "understands" how Angular FormControl and Validators work, and minimize the code footprint through utilizing the error output of Angular validators.
The standalone component has proper imports of modules needed.

Through Claude.ai

Claude.ai is as smart as Codex, however, the code generated is too verbose, and its practice of defensive programming is over diligent.

HTML by generic ChatGPT:

  <mat-form-field appearance="outline">
    <mat-label>Name</mat-label>

    <input matInput formControlName="name"
           (focus)="onFocus('name')" (blur)="onBlur()" />

    @if (focused === 'name') {
      <mat-hint>Required • 2–255 characters</mat-hint>
    }

    @if (form.controls.name.errors && form.controls.name.touched) {
      <mat-error>
        @if (form.controls.name.errors['required']) { Name is required }
        @if (form.controls.name.errors['minlength']) { Minimum length is 2 }
        @if (form.controls.name.errors['maxlength']) { Maximum length is 255 }
      </mat-error>
    }
  </mat-form-field>

HTML generated by Claude.ai:

     <mat-form-field appearance="outline" class="full-width">
        <mat-label>Name</mat-label>
        <input matInput
               formControlName="name"
               placeholder="Full name"
               (focus)="onFocus('name')"
               (blur)="onBlur()" />
        @if (focusedField === 'name') {
          <mat-hint>Required · 2–255 characters</mat-hint>
        }
        @if (form.get('name')?.hasError('required')) {
          <mat-error>Name is required.</mat-error>
        }
        @if (form.get('name')?.hasError('minlength')) {
          <mat-error>At least 2 characters required.</mat-error>
        }
        @if (form.get('name')?.hasError('maxlength')) {
          <mat-error>Maximum 255 characters allowed.</mat-error>
        }
      </mat-form-field>

For displaying errors of multiple constraints, the code generated by ChatGPT is more compact. Also, ChatGPT recognizes that the FormGroup TypeScript codes included in the prompt provides strictly typed data with form.controls.name already assure form control name is there. There's no need to have a guesswork and safety net like form.get('name')?.

Nevertheless, this does not mean Claude.ai is overall worse than ChatGTP. It might just happen that Claude.ai is not very good in crafting Angular code, or the default settings need to be adjusted through prompt.

Common Behavior

Without explicitly prompting "Use @if instead of *ngIf", they all use *ngIf in the HTML template. Apparently the training of these AI agents was mostly done before Angular 17.

How About Generate GUI Directly From Backend Code?

Previously, I have used WebApiClientGen generated TypeScript code as part of the prompt for AI code agents to create the data‑entry component. You may be asking: why not just use the backend POCO classes as part of the prompt?

And I have tried:

Prompt

For Angular Reactive Forms programming of Angular 21 along with Angular Material Components, I have already the following .NET POCO classes codes about the data models:

    public class IntegralEntity
    {
        public sbyte SByte { get; set; }

        public byte Byte { get; set; }
...
        [RegularExpression(@"^(https?:\/\/)?[da-z.-]+.[a-z.]{2,6}([/\w .-]*)*\/?$")]
        public Uri Web { get; set; }

        public string EmailAddress { get; set; }
    }

and I would like you to:

Declare TypeScript interfaces for POCO classes, and strictly typed FormGroup codes which include Angular validators mapping to .NET numeric types and validation attributes.
Craft a data entry component for data fields of data model MixedDataEntity, and the expect output is data-detail.component.ts and data-detail.component.html
The HTML template are composed with matFormField and matInput and formControlName etc.
MatHint of each FormField hints about data constraints.
Only when the matInput gets focused, the matHint is shown.
MatError for showing validation errors
Use @if instead of *ngIf.

AI Generated Code

I have tried with ChatGPT normal, and Claud.ai. You may try with similar prompt with various AI code agents.

So far I see the component generated by ChatGPT is slightly more verbose than the one based on the prompt containing TypeScript code generated.
And the one generated by Claude.ai is much more verbose and complex -- more complex design with much lengthier code.

Summary

After these experiments, I would prefer to use a traditional code generator to produce TypeScript code first, and then ask AI to generate the data‑entry form. My reasons are:

The output of a traditional code generator is predictable, deterministic and the least verbose.
I shouldn't be expected to manually adjust and maintain the generated code by traditional codegen.
Even though the data‑entry form is generated by AI, it is still faster to adjust it manually than to write prompts asking the AI to refine it.
The more tasks/steps in the AI context window, the more likely the AI generates more complex design and longer code, and the more likely the data entry form contains more unnecessary technical details / wastes.

Both traditional code generators and AI code agents are opinionated, while you may ask AI code generates to changed to the other opinionated approaches.

When building complex business applications using libraries, frameworks, code generators, and AI code agents:

Where is the balance?
How do we define that balance among various opinionated approaches?

Web Theme Loader, hand-crafted or AI generated

fonlow — Mon, 06 Apr 2026 22:30:43 +0000

I have crafted one from scratch based on specific functional requirements and technical requirements, conforming to my design principles for UI, UX and Developer Experience.

Developer Experience expected:

Rich features with small API surface.
Flexibility.
Portability & Reusability.

If you just want to use this loader right away, please check "Web Theme Loader with Comprehensive Features and Minimum API Surface"

This article is the first in a series of articles comparing hand‑crafted code and code generated by AI agents on a non‑trivial topic.

Requirements

User Story

As a web app user, I want to choose from multiple available themes — sometimes light, other times dark.

Work Order

Develop a TypeScript‑based, framework‑agnostic API that exposes reusable helpers and abstractions for implementing theme pickers in web applications. The API should remain independent of any specific framework while optionally offering seamless integration points for Angular.

Functional Requirements

Support both light and dark themes.
Support more than two themes.
Support commonly used prebuilt themes, optionally combined with an app‑specific color stylesheet such as colors.css, with an optional dark‑mode variant like colors-dark.css.
Support dynamic switching between themes at runtime.
When the same web app/site is opened in another browser tab, the explicitly selected theme should be preserved and applied.

Technical Requirements

Reusable across multiple applications.
Minimal API surface to ensure easy configuration and customization.
Neutral with respect to specific UI design choices.
Must be efficient and avoid visual flicker during startup and theme switching.
Usable in both SPA and PWA.
Fully functional in PWAs, offline usage, and intranet environments.
Configurable after build, bundling, and deployment. For example, an IT admin should be able to change the number and order of available themes, and modify app‑specific color files.
Themes may be hosted locally with the app code or on a CDN.
Selecting a theme that is already loaded should not trigger a reload of the theme.
Core theme management must be separated from the theme‑picker UI.

Examples in the real world:

If you find your requirements match mine, please read on.

The following sourcecode is crafted in TypeScript for Angular SPA, and it should be reusable in other Web apps or sites crafted in JavaScript, with near zero modification.

## Theme Loader

themeLoader.ts (full sourcecode)

import { ThemeConfigConstants } from "./themeDef"; //just for typed

/**
 * Helper class to load default theme or selected theme among themes defined in app startup settings.
 * index.html should not have the theme css link during design time.
 * In addition to the main theme which could be one the prebuilt themes reusable across apps, like one of those of Angular Material, 
 * the app may optionally has its own app css file for colors.
 */
export class ThemeLoader {
    private static readonly settings = ThemeConfigConstants.themeLoaderSettings;

    /**
     * selected theme file name saved in localStorage.
     */
    static get selectedTheme(): string | null {
        return this.settings ? localStorage.getItem(this.settings.storageKey) : null;
    };
    private static set selectedTheme(v: string) {
        if (this.settings) {
            localStorage.setItem(this.settings.storageKey, v);
        }
    };

    /**
     * Load default or previously selected theme during app startup, typically used before calling `bootstrapApplication()`.
     */
    static init(){
        this.loadTheme(this.selectedTheme);
    }

    /**
     * Load theme during operation through `ThemeLoader.loadTheme(themeDicKey);`.
     * @param picked one of the prebuilt themes, typically used with the app's theme picker.
     */
    static loadTheme(picked: string | null) {
        if (!ThemeConfigConstants.themesDic || !this.settings || Object.keys(ThemeConfigConstants.themesDic).length === 0) {
            console.error('AppConfigConstants need to have themesDic with at least 1 item, and themeKeys.');
            return;
        }

        let themeLink = document.getElementById(this.settings.themeLinkId) as HTMLLinkElement;
        if (themeLink) { // app has been loaded in the browser page/tab.
            const currentTheme = themeLink.href.substring(themeLink.href.lastIndexOf('/') + 1);
            const notToLoad = picked == currentTheme;
            if (notToLoad) {
                return;
            }

            const themeValue = ThemeConfigConstants.themesDic[picked!];
            if (!themeValue) {
                return;
            }

            themeLink.href = picked!;
            this.selectedTheme = picked!;
            console.info(`theme altered to ${picked}.`);

            if (this.settings.appColorsLinkId) {
                let appColorsLink = document.getElementById(this.settings.appColorsLinkId) as HTMLLinkElement;
                if (appColorsLink) {
                    if (themeValue.dark != null && this.settings.colorsDarkCss && this.settings.colorsCss) {
                        const customFile = themeValue.dark ? this.settings.colorsDarkCss : this.settings.colorsCss;
                        appColorsLink.href = (this.settings.appColorsDir ?? '') + customFile;
                    } else if (this.settings.colorsCss) {
                        appColorsLink.href = (this.settings.appColorsDir ?? '') + this.settings.colorsCss;
                    }
                }
            }
        } else { // when app is loaded for the first time, then create 
            themeLink = document.createElement('link');
            themeLink.id = this.settings.themeLinkId;
            themeLink.rel = 'stylesheet';
            const themeDicKey = picked ?? Object.keys(ThemeConfigConstants.themesDic!)[0];
            themeLink.href = themeDicKey;
            document.head.appendChild(themeLink);
            this.selectedTheme = themeDicKey;
            console.info(`Initially loaded theme ${themeDicKey}`);

            if (this.settings.appColorsLinkId) {
                const appColorsLink = document.createElement('link');
                appColorsLink.id = this.settings.appColorsLinkId;
                appColorsLink.rel = 'stylesheet';
                const themeValue = ThemeConfigConstants.themesDic[themeDicKey];
                if (themeValue.dark != null && this.settings.colorsDarkCss && this.settings.colorsCss) {
                    const customFile = themeValue.dark ? this.settings.colorsDarkCss : this.settings.colorsCss;
                    appColorsLink.href = (this.settings.appColorsDir ?? '') + customFile;
                } else if (this.settings.colorsCss) {
                    appColorsLink.href = (this.settings.appColorsDir ?? '') + this.settings.colorsCss;
                }

                if (appColorsLink.href) {
                    document.head.appendChild(appColorsLink);
                    console.info(`appColors ${appColorsLink} loaded.`)
                } else {
                    console.warn(`With appColorsLinkId defined, dark&colorsCss&colorDarkCss or colorsCss should be defined.`)
                }
            }
        }
    }
}

Configuration

Typically an Web app with JavaScript has some settings that should be loaded at the very beginning synchronously.

Data schema (full sourcecode):

export interface ThemeValue {
    /** Display name used in the UI like menu or dropdown */
    display: string;

    /** Dark them or not. Optionally to tell which optional app level colors CSS to use, if some app level colors need to adapt the light or dark theme. */
    dark?: boolean;
}

export interface ThemeDef extends ThemeValue {
    /** Relative path or URL to CDN */
    filePath: string;
}

export interface ThemesDic {
    [filePath: string]: ThemeValue
}

export interface ThemeLoaderSettings {
    /**
     * The key of themeDic to store the selected theme in local storage of browser. Each app or site must have a unique key to avoid conflict with other apps or sites.
     */
    storageKey: string;

    /**
     * The id of the link element in index.html for loading the theme CSS file dynamically during app startup and operation.
     */
    themeLinkId: string;

    /** 
     * Optionally the app may has an app level colors CSS declaring colors neutral to the light or dark theme, in addition to a prebuilt theme reused across apps. 
     * If some colors need to adapt the light or dark theme, having those colors defined in colorsCss and colorsDarkCss is convenient for SDLC, since you can
     * use tools to flip colors to dark or light.
     */
    appColorsLinkId?: string;

    /**
     * If undefined or null, app colors css is in root.
     * Effected only when appColorsLinkId is defined.
     */
    appColorsDir?: string;

    /** 
     * Optionally the app may has an app level colors CSS declaring colors adapting to the light theme. 
     * If the app uses only light or dark theme, for example ThemeValue.dark is not defined, this alone is enough, not needing colorsDarkCss. 
    */
    colorsCss?: string;

    /** 
     * Optionally the app may has an app level colors CSS declaring colors adapting to the dark theme. 
     * If the app uses only light or dark theme, there's no need to declare this. 
     */
    colorsDarkCss?: string;
}

interface Theme_Config {
    themesDic?: ThemesDic,

    themeLoaderSettings?: ThemeLoaderSettings
}

declare const THEME_CONFIG: Theme_Config

export const ThemeConfigConstants: Theme_Config = {
    ...(typeof THEME_CONFIG === 'undefined' ? {} : THEME_CONFIG),
}

siteconfig.js (full sourcecode):

const THEME_CONFIG = {
    themesDic: {
        "assets/themes/rose-red.css":{display: "Roes & Red", dark:false},
        "assets/themes/azure-blue.css":{display: "Azure & Blue", dark:false},
        "assets/themes/magenta-violet.css":{display: "Magenta & Violet", dark:true},
        "assets/themes/cyan-orange.css":{display: "Cyan & Orange", dark:true}
    },
    themeLoaderSettings: {
        storageKey: 'app.theme',
        themeLinkId: 'theme',
        appColorsDir: 'conf/',
        appColorsLinkId: 'app-colors',
        colorsCss: 'colors.css',
        colorsDarkCss: 'colors-dark.css'
    }
}

index.html (full sourcecode):

...
    <script src="conf/siteconfig.js"></script>
    ...

Hints:

Theme filename can be URL to CDN.
When the Website or app is launched for the first time, the top one in themesDic is the default.
Having the config as js file give you or your customers to alter the config after build or after deployment.
Depending on your app design, you may hardcode the details of THEME_CONFIG in code without using a JS file.

Startup

To ensure Angular runtime to utilize the theme as early as possible before rendering any component, ThemeLoader must be called before bootstrap:

main.ts

ThemeLoader.loadTheme(ThemeLoader.selectedTheme);
bootstrapApplication(AppComponent, appConfig);

html

And you may do the same for React apps and alike.

UI for Switching Theme

Typically the UI of switching between themes is a dropdown implemented using something like MatMenu or MatSelect, while there are Websites for graphic designers coming with complex runtime styles and theme selection UI, like what in PrimeVue. However, I would doubt any business app or consumer app would favor such powerful complexity.

HTML with MatSelect:

  <mat-form-field>
    <mat-label i18n>Themes</mat-label>
    <mat-select #themeSelect (selectionChange)="themeSelectionChang($event)" [value]="currentTheme">
      @for (item of themes; track $index) {
      <mat-option [value]="item.fileName">{{item.name}}</mat-option>
      }
    </mat-select>
  </mat-form-field>

Code behind (full codes):

  themes?: ThemeDef[];

  currentTheme: string | null;
  ...
    this.themes = AppConfigConstants.themesDic ? Object.keys(AppConfigConstants.themesDic).map(k => {
      const c = AppConfigConstants.themesDic![k];
      const obj: ThemeDef = {
        name: c.name,
        fileName: k,
        dark: c.dark
      };
      return obj;
    }) : undefined;
...
  themeSelectionChang(e: MatSelectChange) {
    ThemeLoader.loadTheme(e.value);
  }

Summary

The API exposes 3 contracts:

static init() of themeLoader to be called during app startup.
static loadTheme(picked: string | null, appColorsDir?: string | null) to be called when the app user picks one from available themes.
static get selectedTheme(): string | null of themeLoader to give the URL of the selected theme, so GUI may display which theme is in-use.
JavaScript constant SITE_CONFIG that contains a theme dictionary and app specific theme settings.

Web Sites and Apps that Use This ThemeLoader

Alternative Implementation by Angular Material Documentation

After Angular Material Components v12, the documentation site has been merged into the components' repository.

Please check https://github.com/angular/components/blob/main/docs/src/app/shared/theme-picker/ and https://github.com/angular/material.angular.io/blob/main/src/app/shared/style-manager/ .

The design basically conforms to the "Requirements" above, though more complex and comprehensive in the contexts of the documentation site, and within its business scope. Overall, decent and elegant enough.

And likely, the design and the implementation have inspired many LLMs based AI code generators.

Alternative Designs by AI Code Agents

Using the requirements above as prompt, I asked Windows Copilot, then asked M365 Copilot of another account, and the Claude.AI etc. to generate sourcecode.

My Take on AI Code Generators

For almost a year, since early 2025, I have been using Windows Copilot and M365 Copilot to help my daily software development works, mostly trivial works, and occasionally heavy scaffolding, covering these areas:

Simple data transformation, such as JSON data to CSV.
Common algorithms.
Common code snippets.
Craft CSS, or create dark theme based on existing CSS.
Sample codes regarding some details of frameworks and libraries that I am not familiar with or forget.
Scaffold codes for synchronizing data sets, for example, sync the customers of ErpNext to contacts of QuickBook.
Migrating legacy React app to newer React lib.
...

I feel pleased, relax and productive with such junior programmers helping me, releasing me from trivial and repetitive technical details.

The attempts above asking AI to generate a theme loader is to have more hand-on experience in using AI in other areas. I will be writing a series of articles about how AI could help senior developers, the inherent shortfalls of AI code generators and why such short falls exist.

Prompt to AI-generated binary is feasible. And is doomsday for programmers near?

fonlow — Sun, 01 Mar 2026 01:05:01 +0000

The most original post:

@Freeze with video.

If you google “elon musk ai will skip code machine code,” you may find that an overwhelming number of software developers disagree with and criticize this idea for various reasons. I picked a few in-depth articles whose authors apparently have a wide range of knowledge and a deep understanding of computer science and software engineering.

My Take

I would consider what Elon said to be quite feasible.

I don’t have any insider information. Elon Musk means that AI would generate machine code directly, rather than generating source code and invoking a compiler targeting a specific type of processor:

@Freeze

Current: Code → Compiler → Binary → Execute

Future: Prompt → AI-generated Binary → Execute

The training of Grok Code should be fundamentally different from the training of other LLM AI code agents that produce human-readable source code.

Review of the History of Programming

Disclaimer:

I am not a computer scientist or an AI expert, but an active full-stack developer—surely a programmer as well.

As a programmer, I am not old enough to have used plugboards and switches in the pre-machine-code era, nor punch cards and paper tape for writing machine code. However, I have used Fortran, Assembly, and PLC at university as part of coursework while studying digital technologies for a bachelor’s degree in Physics. I also wrote an M68K processor emulator as part of my master’s thesis, using C++ code to interpret M68K machine code.

Over the years, I have used C / C++, Turbo Pascal, VB, Delphi, C#, and TypeScript for day-to-day coding. As far as I understand, high-level languages and most principles of computer science and software engineering are designed for flesh-and-blood human brains, like the following:

High cohesion and loose coupling
SOLID
Design Patterns
Agile Manifesto, XP, and DevOps, etc.
Reusable libraries and frameworks

No matter how well you conform to those principles or how clean your source code is, it will eventually be compiled and linked into something resembling spaghetti—something human brains hate but computers do not care about.

Clean code can facilitate better compile-time, link-time, and run-time optimizations, and the performance boost could be up to 25%. I think that current optimization algorithms are largely written as fixed rules by programmers, and generally such rules reward clean code.

In short, these practices exist to help human brains digest functional and technical complexity in order to deliver a working program.

Programming and LLM AI Code Agents

I presume you have a basic idea of how AI code agent vendors train their models. However, I am not sure what raw code they collect or how they label it:

Do they simply scan all code on GitHub and SourceForge, as well as some commercial programs and libraries?
Do they label code with signals about code quality?

As a programmer, I have benefited greatly from AI code agents, partly because I am poor at remembering trivial technical details. So far, I have found that once I ask AI code agents to implement a non-trivial feature—no matter how detailed, formal, or simple the prompt—the generated source code is usually over-bloated in design and implementation, and the line count is typically 3–5 times what it should be.

AI-Generated Source Code and Mediocre but “Politically Correct” Hand-Crafted Code

“3–5 times” sounds like a magic number to me. In several commercial rewrite projects and one rewrite of an open-source tool—using the same technical stack and language:

My codebase was around 1/3 to 1/5 the LoC of the legacy versions, which were only a few months or a year older.
My designs were much simpler, with fewer dependencies on third-party components and less fancy DI/IoC, SOLID, and design patterns.
Runtime performance was 20% to 50% faster.
The end products were more reliable and robust.

Regarding the legacy codebases:

The author of one tool was enthusiastic about SOLID and DI/IoC but apparently misunderstood high cohesion and loose coupling, using DI/IoC in the wrong places.
The authors of the legacy commercial programs knew SOLID and design patterns well, but still applied them in the wrong places—likely due to misunderstanding cohesion and coupling and introducing overly advanced designs too early.

Basically, these legacy codebases looked “politically correct” with respect to SOLID, but were simply over-complicated and too lengthy.

How I Have Been Writing Clean and Short Code

I believe these programmers jumped directly into implementing their first workable idea without evaluating simpler alternatives, without spending enough time understanding business and technical contexts, and without following basic Agile practices: starting with basic working code, writing plenty of unit and integration tests, and actively refactoring in each iteration.

The purpose is not to make the design look elegant or impressive, but to deepen understanding of business and technical contexts through frequent communication with technical peers and business stakeholders.

Do I write 2–4 times more lines of code than average senior developers in my city?

Not really. When I lead the SDLC, I typically spend around 1/3 to 1/4 of my billable hours coding (including testing), especially during the early 1/4 to 1/3 of the SDLC, when architecture and software design are taking shape. I spend the remaining time thinking, studying, and communicating with stakeholders. Even if I produce the same amount of code—or less—the overall maintenance cost is dramatically reduced.

Let’s review what Robert C. Martin said in "UML for Java Programmers":

SRP — A class should have one and only one reason to change.
OCP — It should be possible to change the environment of a class without changing the class.
LSP — Avoid making methods of derivatives illegal or degenerate. Users of base classes should not need to know about the derivatives.
DIP — Depend on interfaces and abstract classes instead of volatile concrete classes.
ISP — Give each user of an object an interface that has just the methods that user needs.

When should these principles be applied? At the first hint of pain. It is not wise to make all systems conform to all principles all the time. You will spend an eternity imagining possible environments for OCP or sources of change for SRP, create dozens of little interfaces for ISP, and invent many worthless abstractions for DIP.

The best way to apply these principles is reactively rather than proactively. When you detect a structural problem or notice a module being affected by changes elsewhere, then consider whether one or more of these principles can help.

A reactive approach also requires a proactive effort to create pressure early. If you want to react to pain, you must diligently search for sore spots.

One of the best ways to do this is to write lots of unit tests—ideally before writing the code itself. But that is a topic for another chapter.

Do you see possible correlations between AI code agents and some senior developers?

Both tend to create advanced and complex SOLID structures with popular design patterns in advance.
When prompted progressively or via a big-bang request, AI code agents accumulate SOLID structures rather than continuously merging and simplifying based on new prompts.

Advantages of Prompt-to-AI-Generated Binary

From prompt to AI-generated binary, this approach may avoid the code bloat caused by accumulated and complex designs that other AI code agents typically produce. A sufficiently powerful AI with strong hardware can handle enormous complexity without relying on CS and SE techniques developed to aid human programmers.

Grok Code likely has its own mechanisms to avoid code bloat, and SOLID and design patterns likely play near zero role.

One Fundamental Problem of Prompt to AI-generated Binary

This approach effectively eliminates human intervention: review, verification, and validation regarding product quality.

Even if you disassemble machine code into assembly code, the resulting code is extremely difficult for humans to read, even if AI attempts to polish it by adding symbolic names.

The entire binary becomes a black box. At best, it behaves as expected but with more than you have bargained for; at worst, it may contain multiple Pandora’s boxes—unless you fully trust AI-based review, verification, and validation.

“A problem well stated is a problem half solved.”

This statement is often attributed to Charles Kettering. In the context of AI generating code, it means that clearly defining a prompt makes it significantly easier for the AI to produce code that aligns with human expectations. However, here are two questions:

How often have you stated a complex problem well without multiple iterations?
How confident are you that AI can fully understand your well‑stated problem?

Areas Where Grok Code May Shine

Pure mathematics problems and algorithms.
Development of other AI systems based on mathematical foundations
Domain-expert AI
Video games
Time-killing apps
Advanced hacking, spam, or fraud tools, with or without AI assistance at runtime
...

For example, as a mathematician, you may use Grok Code to generate the whole Matlab-like libraries.

My Usual Challenge to AI Code Generators

Given a complex Swagger/OpenAPI definition—such as those used by Medicare Online, can an AI code generator produce usable code in C#, TypeScript, Java, and other languages?

Apparently, ChatGPT and Copilot cannot. Otherwise, Microsoft would have released an online AI‑based code generator to handle this task, instead of delivering Microsoft Kiota.

A Swagger / OpenAPI definition is clearly a well stated problem.

I’ll be interested to see whether, by the end of the year, Grok Code can generate a client library in machine code—based on the Medicare Online OpenAPI definitions—running on Windows 11 and an Intel processor.

Craft Web Theme Loader using ChatGPT 4

fonlow — Thu, 26 Feb 2026 20:47:12 +0000

Requirements

User Story

As a web app user, I want to choose from multiple available themes — sometimes light, other times dark.

Work Order

Develop a TypeScript-based API that provides helper functions or classes for building a theme picker in web applications. The API should be framework‑agnostic, therefore give code snippets for Angular app and React app using this API.

Functional Requirements

Support both light and dark themes.
Support more than two themes — at least three themes must be available.
Support commonly used prebuilt themes, optionally combined with an app‑specific color stylesheet such as colors.css, with an optional dark‑mode variant like colors-dark.css.
Support dynamic switching between themes at runtime.
When the same web app/site is opened in another browser tab, the explicitly selected theme should be preserved and applied.

Technical Requirements

Reusable across multiple applications.
Minimal API surface to ensure easy customization and easy usage.
Neutral with respect to specific UI design choices.
Must be efficient and avoid visual flicker during startup and theme switching.
Usable in both SPA and PWA.
Fully functional in PWAs, offline usage, and intranet environments.
Adjustable after build, bundling, and deployment. For example, an admin should be able to change the number and order of available themes, and modify app‑specific color files.
Themes may be hosted locally or on a CDN.
Selecting a theme that is already loaded should not trigger a reload of the theme.
Core theme management must be separated from the theme‑picker UI.
The config settings must be loaded during app startup before any component is rendered.

Using the requirements as prompt, I asked ChatGpt 4 to generate sourcecode, and the following is the result.

Below is a framework-agnostic, TypeScript theme-management API plus Angular and React usage examples.
The design keeps core theme logic separate from UI, supports multiple light/dark themes, avoids startup flicker, works offline/PWA, and allows post-deployment adjustments via config and CSS files.

High-level design

Key ideas

ThemeManager (core, reusable) Loads theme config at startup, applies themes by swapping <link> tags, persists selection, syncs across tabs.
Theme config (JSON) Controls number/order of themes and URLs to CSS files (local or CDN). Editable after deployment.
Early boot loader (tiny inline script) Applies the last selected theme before the framework renders → no flicker.
UI adapters (optional) Angular/React examples only consume the core API.

Theme configuration (editable after deployment)

/assets/themes/themes.config.json

{
  "defaultThemeId": "light",
  "themes": [
    {
      "id": "light",
      "label": "Light",
      "mode": "light",
      "styles": [
        "/assets/themes/base-light.css",
        "/assets/themes/colors.css"
      ]
    },
    {
      "id": "dark",
      "label": "Dark",
      "mode": "dark",
      "styles": [
        "/assets/themes/base-dark.css",
        "/assets/themes/colors-dark.css"
      ]
    },
    {
      "id": "high-contrast",
      "label": "High Contrast",
      "mode": "dark",
      "styles": [
        "https://cdn.example.com/themes/high-contrast.css"
      ]
    }
  ]
}

Add/remove/reorder themes without rebuilding the app
Mix prebuilt themes and app-specific colors
Works offline if assets are cached by the PWA service worker

Core API (framework-agnostic)

Public types

export type ThemeMode = 'light' | 'dark';

export interface ThemeDefinition {
  id: string;
  label: string;
  mode: ThemeMode;
  styles: string[]; // URLs to CSS files
}

export interface ThemeConfig {
  defaultThemeId: string;
  themes: ThemeDefinition[];
}

ThemeManager

export class ThemeManager {
  private config!: ThemeConfig;
  private activeThemeId!: string;
  private readonly storageKey = 'app.theme';
  private readonly channel = 'app-theme-sync';
  private bc?: BroadcastChannel;

  constructor(private readonly doc: Document = document) {}

  async init(configUrl: string): Promise<void> {
    this.config = await fetch(configUrl).then(r => r.json());

    const stored =
      localStorage.getItem(this.storageKey) || this.config.defaultThemeId;

    this.applyTheme(stored, { persist: false });

    // cross-tab sync
    if ('BroadcastChannel' in window) {
      this.bc = new BroadcastChannel(this.channel);
      this.bc.onmessage = e => this.applyTheme(e.data, { persist: false });
    } else {
      window.addEventListener('storage', e => {
        if (e.key === this.storageKey && e.newValue) {
          this.applyTheme(e.newValue, { persist: false });
        }
      });
    }
  }

  getThemes(): ThemeDefinition[] {
    return this.config.themes;
  }

  getActiveTheme(): string {
    return this.activeThemeId;
  }

  applyTheme(
    themeId: string,
    opts: { persist?: boolean } = { persist: true }
  ): void {
    if (themeId === this.activeThemeId) return;

    const theme = this.config.themes.find(t => t.id === themeId);
    if (!theme) return;

    this.loadStyles(theme.styles);
    this.doc.documentElement.dataset.theme = theme.id;
    this.doc.documentElement.dataset.themeMode = theme.mode;

    this.activeThemeId = themeId;

    if (opts.persist !== false) {
      localStorage.setItem(this.storageKey, themeId);
      this.bc?.postMessage(themeId);
    }
  }

  private loadStyles(urls: string[]): void {
    const head = this.doc.head;

    // Mark existing theme styles
    const existing = Array.from(
      head.querySelectorAll<HTMLLinkElement>('link[data-theme-style]')
    );

    // Load only missing styles
    urls.forEach(url => {
      if (existing.some(l => l.href === new URL(url, location.href).href)) {
        return;
      }
      const link = this.doc.createElement('link');
      link.rel = 'stylesheet';
      link.href = url;
      link.dataset.themeStyle = 'true';
      head.appendChild(link);
    });

    // Remove styles no longer used
    existing.forEach(l => {
      if (!urls.includes(l.getAttribute('href') || '')) {
        head.removeChild(l);
      }
    });
  }
}

Why this meets the requirements

Multiple themes (≥3) ✔
Light/dark support ✔
Runtime switching ✔
No reload if already loaded ✔
Cross-tab sync ✔
CDN or local ✔
Core logic isolated from UI ✔

Zero-flicker startup (critical)

Add this tiny inline script to index.html before any CSS/framework scripts:

<script>
  (function () {
    try {
      var theme = localStorage.getItem('app.theme');
      if (theme) {
        document.documentElement.dataset.theme = theme;
      }
    } catch {}
  })();
</script>

This ensures the correct theme is applied before first paint.

Angular usage example

App initializer

// theme.provider.ts
import { APP_INITIALIZER, Provider } from '@angular/core';
import { ThemeManager } from './theme-manager';

export const themeManager = new ThemeManager();

export const ThemeInitializer: Provider = {
  provide: APP_INITIALIZER,
  multi: true,
  useFactory: () => () =>
    themeManager.init('/assets/themes/themes.config.json')
};

// app.module.ts
@NgModule({
  providers: [ThemeInitializer]
})
export class AppModule {}

Theme picker component

@Component({
  selector: 'app-theme-picker',
  template: `
    <select
      [value]="active"
      (change)="setTheme($event.target.value)">
      <option *ngFor="let t of themes" [value]="t.id">
        {{ t.label }}
      </option>
    </select>
  `
})
export class ThemePickerComponent {
  themes = themeManager.getThemes();
  active = themeManager.getActiveTheme();

  setTheme(id: string) {
    themeManager.applyTheme(id);
    this.active = id;
  }
}

React usage example

Bootstrap

// theme.ts
import { ThemeManager } from './theme-manager';

export const themeManager = new ThemeManager();

export async function initTheme() {
  await themeManager.init('/assets/themes/themes.config.json');
}

// main.tsx
await initTheme();
createRoot(document.getElementById('root')!).render(<App />);

Theme picker component

export function ThemePicker() {
  const [themes] = React.useState(themeManager.getThemes());
  const [active, setActive] = React.useState(themeManager.getActiveTheme());

  const onChange = (id: string) => {
    themeManager.applyTheme(id);
    setActive(id);
  };

  return (
    <select value={active} onChange={e => onChange(e.target.value)}>
      {themes.map(t => (
        <option key={t.id} value={t.id}>
          {t.label}
        </option>
      ))}
    </select>
  );
}

PWA & offline notes

Cache themes.config.json and CSS files via service worker
Theme switching continues offline
Admin can update theme files on intranet/CDN without rebuilding

Summary

This API:

Keeps theme logic independent of UI
Works in Angular, React, SPA, and PWA
Avoids visual flicker
Supports runtime config & post-deployment changes
Scales from 2 → many themes with minimal API surface

If you want, I can also:

Add system-prefers-color-scheme auto mode
Provide SSR support
Add a headless theme-picker hook for React or a service wrapper for Angular

Analysis

Comparing with what generated by Windows/M365 Copilot, Claude AI and Google AI Studio, ChatGTP generates the shortest sourcecode and the simplest design.

Common Pitfalls:

The AI does not understand that a JSON file is inherently loaded asynchronously, while I have stated "The config settings must be loaded during app startup before any component is rendered", though I did not give detailed background knowledge of providing startup config.

Regarding the code snippets for Angular usage, the entry is too late. Startup logic must be loaded before the bootstrap.

Regarding the code snippets for React usage, the entry looks OK. Though a little flicking may be expected, at least it won't be as severe as the Angular app.

I have crafted one from scratch based on the same functional requirements and technical requirements, conforming to my design principles for UI, UX and Developer Experience:

Yet Another Web Theme Loader

Use Claude.AI to Craft Web Theme Loader

fonlow — Thu, 19 Feb 2026 10:39:38 +0000

Use Claude.AI to Craft Web Theme Loader

Requirements

User Story

As a web app user, I want to choose from multiple available themes — sometimes light, other times dark.

Work Order

Develop a TypeScript-based API that provides helper functions or classes for building a theme picker in web applications. The API should be framework‑agnostic, while optionally offering convenient integration points for Angular applications.

Functional Requirements

Support both light and dark themes.
Support more than two themes — at least three themes must be available.
Support commonly used prebuilt themes, optionally combined with an app‑specific color stylesheet such as colors.css, with an optional dark‑mode variant like colors-dark.css.
Support dynamic switching between themes at runtime.
When the same web app/site is opened in another browser tab, the explicitly selected theme should be preserved and applied.

Technical Requirements

Reusable across multiple applications.
Minimal API surface to ensure easy customization and easy usage.
Neutral with respect to specific UI design choices.
Must be efficient and avoid visual flicker during startup and theme switching.
Usable in both SPA and PWA.
Fully functional in PWAs, offline usage, and intranet environments.
Adjustable after build, bundling, and deployment. For example, an admin should be able to change the number and order of available themes, and modify app‑specific color files.
Themes may be hosted locally or on a CDN.
Selecting a theme that is already loaded should not trigger a reload of the theme.
Core theme management must be separated from the theme‑picker UI.
The config settings must be loaded during app startup before any component is rendered.

Using the requirements as prompt, I asked Calude.ai to generate sourcecode, and the following is the result.

I'll create a comprehensive TypeScript theme management system that meets all your requirements. Let me start by reading the relevant skills to ensure I build this properly.Now I'll create a robust theme management system with the following architecture:

Core Theme Manager - Handles theme loading, switching, and persistence
Configuration System - Supports runtime-adjustable config
Angular Integration - Optional Angular service
Type Definitions - Full TypeScript support
Example Implementation - Demo showing how to use itNow let me create a comprehensive testing example and a summary document:Now let me move all the files to the outputs directory and provide you with a summary:Perfect! I've created a complete TypeScript theme management system that meets all your requirements. Here's what you have:

📦 Core System Files

Core Components:

theme-manager.ts - Main theme manager class (framework-agnostic)
config-loader.ts - Runtime-adjustable configuration loader
storage.ts - LocalStorage adapter with fallback
types.ts - Complete TypeScript type definitions
index.ts - Main export file

Angular Integration:

angular/theme.service.ts - Angular service with RxJS support
angular/theme.module.ts - Angular module with APP_INITIALIZER
angular/theme-picker.component.ts - Example UI component

🎯 All Requirements Met

✅ Functional Requirements:

✓ Light & dark theme support (isDark property)
✓ 3+ themes (enforced by validation)
✓ Prebuilt themes + custom colors (stylesheetUrl + colorStylesheetUrl)
✓ Dynamic runtime switching (switchTheme())
✓ Cross-tab persistence (localStorage + storage events)

✅ Technical Requirements:

✓ Reusable (framework-agnostic core)
✓ Minimal API (clean, focused interface)
✓ UI-neutral (core has no UI)
✓ Zero flicker (anti-FOUC inline script)
✓ SPA & PWA compatible
✓ Offline-ready (localStorage fallback)
✓ Post-deployment adjustable (JSON config)
✓ CDN support (themes can be hosted anywhere)
✓ No reload for same theme (checks before switching)
✓ Separated core from UI
✓ Config loaded before render (APP_INITIALIZER)

📚 Documentation & Examples

README.md - Complete API reference
IMPLEMENTATION_GUIDE.md - Step-by-step integration guide
examples/ - Working examples for Angular & vanilla JS
tests/ - Unit test examples
Theme CSS examples (light, dark, high-contrast)

🚀 Key Features

Anti-Flicker: Inline script loads theme before page render
Cross-Tab Sync: Theme changes propagate instantly
Preloading: Load themes in background for instant switching
TypeScript First: Full type safety
PWA Ready: Service worker integration examples
Admin Friendly: External JSON config for post-deployment changes

Start with the README for a quick overview, then dive into the IMPLEMENTATION_GUIDE for detailed setup instructions!

Theme Management System

A flexible, framework-agnostic TypeScript theme management solution with first-class Angular support. Provides flicker-free theme loading, cross-tab synchronization, and runtime-adjustable configurations.

Features

✅ Multiple Themes - Support for 3+ themes (requirement met)

✅ Light & Dark Modes - Built-in support for both modes

✅ Zero Flicker - Anti-FOUC technique for instant theme application

✅ Cross-Tab Sync - Theme changes propagate across all open tabs

✅ Persistent Preferences - User selections saved in localStorage

✅ PWA & Offline Ready - Works in Progressive Web Apps and offline

✅ Runtime Adjustable - Config can be changed after deployment

✅ CDN Support - Host themes locally or on CDN

✅ Minimal API - Simple, easy-to-use interface

✅ Framework Agnostic - Core works anywhere, Angular integration included

✅ TypeScript First - Full type safety throughout

Installation

npm install theme-manager-system
# or
yarn add theme-manager-system

Quick Start

Vanilla JavaScript/TypeScript

import { ThemeManager } from 'theme-manager-system';

const manager = new ThemeManager({
  themes: [
    {
      id: 'light',
      name: 'Light Theme',
      stylesheetUrl: '/themes/light.css',
      colorStylesheetUrl: '/themes/colors.css',
      isDark: false
    },
    {
      id: 'dark',
      name: 'Dark Theme',
      stylesheetUrl: '/themes/dark.css',
      colorStylesheetUrl: '/themes/colors-dark.css',
      isDark: true
    },
    {
      id: 'high-contrast',
      name: 'High Contrast',
      stylesheetUrl: '/themes/high-contrast.css',
      isDark: false
    }
  ],
  defaultThemeId: 'light'
});

// IMPORTANT: Initialize before rendering content
await manager.initialize();

// Switch themes
await manager.switchTheme('dark');

Angular Integration

app.module.ts:

import { ThemeModule } from 'theme-manager-system';

@NgModule({
  imports: [
    ThemeModule.forRoot({
      config: '/assets/theme-config.json'  // or static config object
    })
  ]
})
export class AppModule { }

component.ts:

import { Component } from '@angular/core';
import { ThemeService } from 'theme-manager-system';

@Component({
  selector: 'app-root',
  template: `
    <app-theme-picker></app-theme-picker>
    <div>Current theme: {{ (themeService.theme$ | async)?.name }}</div>
  `
})
export class AppComponent {
  constructor(public themeService: ThemeService) {}

  async switchToDark() {
    await this.themeService.switchTheme('dark');
  }
}

Configuration

Static Configuration

const config: ThemeConfig = {
  themes: [
    {
      id: 'light',
      name: 'Light Theme',
      stylesheetUrl: '/themes/light.css',
      colorStylesheetUrl: '/themes/colors.css',  // Optional
      isDark: false,
      metadata: { /* custom data */ }  // Optional
    },
    // ... more themes (minimum 3 total)
  ],
  defaultThemeId: 'light',
  storageKey: 'my-app-theme',  // Optional, default: 'app-theme-preference'
  preventFlicker: true,  // Optional, default: true
  dataAttribute: 'data-theme'  // Optional, default: 'data-theme'
};

External Configuration (Recommended for Admin Adjustability)

theme-config.json:

{
  "themes": [
    {
      "id": "light-default",
      "name": "Light Default",
      "stylesheetUrl": "/themes/light.css",
      "colorStylesheetUrl": "/themes/colors.css",
      "isDark": false
    },
    {
      "id": "dark-default",
      "name": "Dark Default",
      "stylesheetUrl": "/themes/dark.css",
      "colorStylesheetUrl": "/themes/colors-dark.css",
      "isDark": true
    },
    {
      "id": "blue-ocean",
      "name": "Blue Ocean",
      "stylesheetUrl": "https://cdn.example.com/themes/blue.css",
      "isDark": false
    }
  ],
  "defaultThemeId": "light-default",
  "storageKey": "my-app-theme"
}

Load it:

import { ThemeConfigLoader, ThemeManager } from 'theme-manager-system';

const config = await ThemeConfigLoader.loadFromUrl('/assets/theme-config.json');
const manager = new ThemeManager(config);
await manager.initialize();

Anti-Flicker Technique

To prevent the flash of unstyled content (FOUC), add this inline script to your HTML <head>:

<head>
  <script>
    (function() {
      const STORAGE_KEY = 'app-theme-preference';
      const DEFAULT_THEME = 'light';

      const savedThemeId = localStorage.getItem(STORAGE_KEY) || DEFAULT_THEME;
      document.documentElement.setAttribute('data-theme', savedThemeId);

      // Inject theme stylesheet synchronously
      const themeMap = {
        'light': '/themes/light.css',
        'dark': '/themes/dark.css'
      };

      const href = themeMap[savedThemeId] || themeMap[DEFAULT_THEME];
      document.write('<link rel="stylesheet" href="' + href + '">');
    })();
  </script>
</head>

API Reference

ThemeManager

Methods

initialize(): Promise<void> - Initialize the manager (call before rendering)
switchTheme(themeId: string, options?: ThemeSwitchOptions): Promise<void> - Switch to a different theme
getCurrentTheme(): Theme | null - Get the currently active theme
getAvailableThemes(): Theme[] - Get all available themes
getThemeById(themeId: string): Theme | undefined - Get a specific theme
onThemeChange(callback: ThemeChangeCallback): () => void - Subscribe to theme changes (returns unsubscribe function)
updateConfig(newConfig: Partial<ThemeConfig>): void - Update configuration at runtime
preloadTheme(themeId: string): Promise<void> - Preload a theme for faster switching

ThemeService (Angular)

Properties

theme$: Observable<Theme | null> - Observable of the current theme
currentTheme: Theme | null - Current theme (synchronous)
availableThemes: Theme[] - All available themes

Methods

switchTheme(themeId: string): Promise<void> - Switch themes
toggleDarkMode(): Promise<void> - Toggle between light and dark
preloadTheme(themeId: string): Promise<void> - Preload a theme
updateConfig(newConfig: Partial<ThemeConfig>): void - Update configuration

Advanced Usage

Runtime Configuration Updates

// Admin can update themes after deployment
manager.updateConfig({
  themes: [
    // ... new theme list
  ],
  defaultThemeId: 'new-default'
});

Preloading Themes

// Preload alternate themes for instant switching
const themes = manager.getAvailableThemes();
await Promise.all(
  themes.slice(0, 3).map(t => manager.preloadTheme(t.id))
);

Cross-Tab Synchronization

The system automatically synchronizes theme changes across browser tabs using localStorage events. No additional code needed.

PWA Support

// Listen for service worker updates
if ('serviceWorker' in navigator) {
  navigator.serviceWorker.addEventListener('controllerchange', () => {
    const current = manager.getCurrentTheme();
    if (current) {
      manager.switchTheme(current.id, { forceReload: true });
    }
  });
}

Requirements Met

Requirement	Status	Implementation
Light & dark theme support	✅	`isDark` property on themes
3+ themes	✅	Config validation enforces minimum 3 themes
Prebuilt themes + custom colors	✅	`stylesheetUrl` + optional `colorStylesheetUrl`
Dynamic theme switching	✅	`switchTheme()` method
Cross-tab persistence	✅	localStorage + storage events
Reusable across apps	✅	Framework-agnostic core
Minimal API	✅	Simple, focused interface
UI-neutral	✅	No UI components in core (examples provided)
No flicker	✅	Anti-FOUC inline script + preloading
SPA & PWA support	✅	Works in all environments
Offline functionality	✅	LocalStorage fallback
Post-deployment adjustable	✅	External JSON config + `updateConfig()`
CDN support	✅	Themes can be hosted anywhere
No reload when same theme	✅	Checks current theme before switching
Separated core from UI	✅	`ThemeManager` (core) separate from picker components
Config loaded before render	✅	`initialize()` + APP_INITIALIZER in Angular

Browser Support

Chrome/Edge 90+
Firefox 88+
Safari 14+
All modern mobile browsers

License

MIT

Contributing

Contributions welcome! Please open an issue or PR.

Implementation Guide

Complete guide for implementing the Theme Management System in your application.

Quick Start
Angular Implementation
Vanilla JS Implementation
PWA Implementation
Configuration
Anti-Flicker Setup
Customization
Testing

Quick Start

Installation

npm install theme-manager-system

Basic Setup (Vanilla JS)

import { ThemeManager } from 'theme-manager-system';

const manager = new ThemeManager({
  themes: [
    { id: 'light', name: 'Light', stylesheetUrl: '/themes/light.css', isDark: false },
    { id: 'dark', name: 'Dark', stylesheetUrl: '/themes/dark.css', isDark: true },
    { id: 'auto', name: 'Auto', stylesheetUrl: '/themes/auto.css', isDark: false }
  ],
  defaultThemeId: 'light'
});

await manager.initialize();

Angular Implementation

Step 1: Install Package

npm install theme-manager-system

Step 2: Create Configuration File

src/assets/theme-config.json:

{
  "themes": [
    {
      "id": "light-default",
      "name": "Light",
      "stylesheetUrl": "/themes/light.css",
      "colorStylesheetUrl": "/themes/colors.css",
      "isDark": false
    },
    {
      "id": "dark-default",
      "name": "Dark",
      "stylesheetUrl": "/themes/dark.css",
      "colorStylesheetUrl": "/themes/colors-dark.css",
      "isDark": true
    },
    {
      "id": "high-contrast",
      "name": "High Contrast",
      "stylesheetUrl": "/themes/high-contrast.css",
      "isDark": false
    }
  ],
  "defaultThemeId": "light-default",
  "storageKey": "my-app-theme"
}

Step 3: Configure AppModule

app.module.ts:

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { ThemeModule } from 'theme-manager-system';
import { AppComponent } from './app.component';

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    ThemeModule.forRoot({
      config: '/assets/theme-config.json'
    })
  ],
  bootstrap: [AppComponent]
})
export class AppModule { }

Step 4: Use in Components

app.component.ts:

import { Component, OnInit } from '@angular/core';
import { ThemeService } from 'theme-manager-system';
import { Observable } from 'rxjs';
import { Theme } from 'theme-manager-system';

@Component({
  selector: 'app-root',
  template: `
    <header>
      <h1>My App</h1>
      <div class="theme-controls">
        <select (change)="onThemeChange($event)">
          <option *ngFor="let theme of themes" 
                  [value]="theme.id"
                  [selected]="theme.id === (currentTheme$ | async)?.id">
            {{ theme.name }}
          </option>
        </select>
        <button (click)="toggleDarkMode()">
          {{ (currentTheme$ | async)?.isDark ? 'Light Mode' : 'Dark Mode' }}
        </button>
      </div>
    </header>
  `
})
export class AppComponent implements OnInit {
  currentTheme$!: Observable<Theme | null>;
  themes: Theme[] = [];

  constructor(private themeService: ThemeService) {}

  ngOnInit() {
    this.currentTheme$ = this.themeService.theme$;
    this.themes = this.themeService.availableThemes;
  }

  async onThemeChange(event: Event) {
    const select = event.target as HTMLSelectElement;
    await this.themeService.switchTheme(select.value);
  }

  async toggleDarkMode() {
    await this.themeService.toggleDarkMode();
  }
}

Vanilla JS Implementation

Complete Example

main.ts:

import { ThemeManager, ThemeConfigLoader } from 'theme-manager-system';

class App {
  private themeManager!: ThemeManager;

  async init() {
    // Load configuration
    const config = await ThemeConfigLoader.loadFromUrl('/assets/theme-config.json');

    // Create manager
    this.themeManager = new ThemeManager(config);

    // Initialize (MUST be called before rendering)
    await this.themeManager.initialize();

    // Setup UI
    this.setupThemePicker();
    this.preloadAlternateThemes();
  }

  private setupThemePicker() {
    const select = document.getElementById('theme-select') as HTMLSelectElement;
    const toggleBtn = document.getElementById('theme-toggle') as HTMLButtonElement;

    // Populate select
    this.themeManager.getAvailableThemes().forEach(theme => {
      const option = document.createElement('option');
      option.value = theme.id;
      option.textContent = theme.name;
      select.appendChild(option);
    });

    // Set current theme
    select.value = this.themeManager.getCurrentTheme()?.id || '';

    // Handle changes
    select.addEventListener('change', async (e) => {
      const target = e.target as HTMLSelectElement;
      await this.themeManager.switchTheme(target.value);
    });

    toggleBtn.addEventListener('click', async () => {
      const current = this.themeManager.getCurrentTheme();
      if (!current) return;

      const themes = this.themeManager.getAvailableThemes();
      const opposite = themes.find(t => t.isDark !== current.isDark);

      if (opposite) {
        await this.themeManager.switchTheme(opposite.id);
      }
    });

    // Listen for theme changes
    this.themeManager.onThemeChange((event) => {
      select.value = event.currentTheme.id;
      this.updateToggleButton(event.currentTheme);
    });
  }

  private updateToggleButton(theme: Theme) {
    const btn = document.getElementById('theme-toggle') as HTMLButtonElement;
    btn.textContent = theme.isDark ? '☀️ Light Mode' : '🌙 Dark Mode';
  }

  private async preloadAlternateThemes() {
    const currentId = this.themeManager.getCurrentTheme()?.id;
    const themes = this.themeManager.getAvailableThemes();

    const preloadPromises = themes
      .filter(t => t.id !== currentId)
      .slice(0, 2)
      .map(t => this.themeManager.preloadTheme(t.id));

    await Promise.all(preloadPromises).catch(console.warn);
  }
}

// Initialize app
const app = new App();
app.init().catch(console.error);

index.html:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My App</title>

  <!-- Anti-flicker script -->
  <script>
    (function() {
      const savedTheme = localStorage.getItem('my-app-theme') || 'light-default';
      document.documentElement.setAttribute('data-theme', savedTheme);

      const themeUrls = {
        'light-default': '/themes/light.css',
        'dark-default': '/themes/dark.css',
        'high-contrast': '/themes/high-contrast.css'
      };

      const url = themeUrls[savedTheme] || themeUrls['light-default'];
      document.write('<link rel="stylesheet" href="' + url + '">');
    })();
  </script>
</head>
<body>
  <header>
    <h1>My App</h1>
    <div>
      <select id="theme-select"></select>
      <button id="theme-toggle">Toggle Dark Mode</button>
    </div>
  </header>

  <main>
    <!-- Your content -->
  </main>

  <script type="module" src="/main.js"></script>
</body>
</html>

PWA Implementation

Service Worker Integration

service-worker.js:

// Cache theme files for offline use
const CACHE_NAME = 'theme-cache-v1';
const THEME_URLS = [
  '/themes/light.css',
  '/themes/dark.css',
  '/themes/high-contrast.css',
  '/themes/colors.css',
  '/themes/colors-dark.css',
  '/assets/theme-config.json'
];

self.addEventListener('install', (event) => {
  event.waitUntil(
    caches.open(CACHE_NAME).then((cache) => {
      return cache.addAll(THEME_URLS);
    })
  );
});

self.addEventListener('fetch', (event) => {
  // Cache-first strategy for theme files
  if (THEME_URLS.some(url => event.request.url.includes(url))) {
    event.respondWith(
      caches.match(event.request).then((response) => {
        return response || fetch(event.request);
      })
    );
  }
});

App Integration

import { ThemeManager } from 'theme-manager-system';

// Register service worker
if ('serviceWorker' in navigator) {
  navigator.serviceWorker.register('/service-worker.js');

  // Handle service worker updates
  navigator.serviceWorker.addEventListener('controllerchange', () => {
    // Reload current theme after SW update
    const currentTheme = themeManager.getCurrentTheme();
    if (currentTheme) {
      themeManager.switchTheme(currentTheme.id, { forceReload: true });
    }
  });
}

Configuration

External Configuration (Recommended)

Benefits:

Admin can modify themes without rebuilding
Easy to add/remove/reorder themes
Support for A/B testing different theme sets

theme-config.json:

{
  "themes": [
    {
      "id": "light",
      "name": "Light Theme",
      "stylesheetUrl": "/themes/light.css",
      "colorStylesheetUrl": "/themes/colors.css",
      "isDark": false,
      "metadata": {
        "description": "Clean light theme",
        "author": "Design Team"
      }
    }
  ],
  "defaultThemeId": "light",
  "storageKey": "app-theme",
  "preventFlicker": true
}

Static Configuration

const config: ThemeConfig = {
  themes: [/* ... */],
  defaultThemeId: 'light',
  storageKey: 'app-theme'
};

const manager = new ThemeManager(config);

Anti-Flicker Setup

Critical Inline Script

Place in <head> before any other stylesheets:

<script>
(function() {
  'use strict';

  const STORAGE_KEY = 'my-app-theme';
  const DEFAULT_THEME = 'light';

  // Get saved preference
  let themeId = DEFAULT_THEME;
  try {
    themeId = localStorage.getItem(STORAGE_KEY) || DEFAULT_THEME;
  } catch (e) {
    // localStorage unavailable
  }

  // Set data attribute
  document.documentElement.setAttribute('data-theme', themeId);

  // Theme URL mapping
  const themes = {
    'light': { css: '/themes/light.css', colors: '/themes/colors.css' },
    'dark': { css: '/themes/dark.css', colors: '/themes/colors-dark.css' },
    'high-contrast': { css: '/themes/high-contrast.css' }
  };

  const theme = themes[themeId] || themes[DEFAULT_THEME];

  // Inject stylesheets synchronously
  document.write('<link rel="stylesheet" href="' + theme.css + '">');
  if (theme.colors) {
    document.write('<link rel="stylesheet" href="' + theme.colors + '">');
  }
})();
</script>

Customization

Creating Custom Themes

my-theme.css:

:root[data-theme="my-custom-theme"] {
  --bg-primary: #custom-color;
  --text-primary: #another-color;
  /* ... more variables */
}

Using Theme Variables

.my-component {
  background: var(--bg-primary);
  color: var(--text-primary);
  border: 1px solid var(--border-color);
}

Dynamic Theme Generation

function generateTheme(baseColor: string): Theme {
  return {
    id: `custom-${Date.now()}`,
    name: 'Custom Theme',
    stylesheetUrl: `/api/themes/generate?color=${baseColor}`,
    isDark: false
  };
}

Testing

Unit Tests

import { ThemeManager } from 'theme-manager-system';

describe('Theme Switching', () => {
  let manager: ThemeManager;

  beforeEach(async () => {
    manager = new ThemeManager(testConfig);
    await manager.initialize();
  });

  test('switches theme correctly', async () => {
    await manager.switchTheme('dark');
    expect(manager.getCurrentTheme()?.id).toBe('dark');
  });
});

Integration Tests

test('theme persists across page reload', async () => {
  await manager.switchTheme('dark');

  // Simulate page reload
  const newManager = new ThemeManager(config);
  await newManager.initialize();

  expect(newManager.getCurrentTheme()?.id).toBe('dark');
});

Troubleshooting

Theme Not Loading

Check browser console for errors
Verify stylesheet URLs are correct
Check network tab for failed requests
Ensure config is loaded before initialization

Flicker on Load

Verify anti-flicker script is in <head>
Check script runs before other stylesheets
Ensure theme URLs in inline script match config

Cross-Tab Sync Not Working

Verify localStorage is available
Check same origin policy
Ensure storage key is consistent

Performance Tips

Preload themes for instant switching
Use CDN for theme files when possible
Cache aggressively in service worker
Minimize CSS for faster loading
Use CSS variables for dynamic theming

Best Practices

Always initialize before rendering
Use external config for flexibility
Implement anti-flicker script
Test in offline mode (PWA)
Validate theme accessibility
Document custom CSS variables
Version your theme files
Monitor theme load performance

index.ts

/**
 * Theme Management System
 * A flexible, framework-agnostic theme management solution for TypeScript applications
 */

// Core exports
export { ThemeManager } from './theme-manager';
export { ThemeConfigLoader } from './config-loader';
export { LocalStorageAdapter } from './storage';

// Type exports
export type {
  Theme,
  ThemeConfig,
  ThemeChangeEvent,
  ThemeChangeCallback,
  ThemeStorage,
  ThemeSwitchOptions
} from './types';

// Angular exports (optional - only import if using Angular)
export { ThemeService, themeInitializerFactory } from './angular/theme.service';
export { ThemeModule } from './angular/theme.module';
export { ThemePickerComponent } from './angular/theme-picker.component';
export type { ThemeModuleConfig } from './angular/theme.module';

themeManager.ts

import {
  Theme,
  ThemeConfig,
  ThemeChangeEvent,
  ThemeChangeCallback,
  ThemeStorage,
  ThemeSwitchOptions
} from './types';
import { LocalStorageAdapter } from './storage';

/**
 * Core theme manager - framework agnostic
 * Handles theme loading, switching, and persistence
 */
export class ThemeManager {
  private config: ThemeConfig;
  private currentTheme: Theme | null = null;
  private storage: ThemeStorage;
  private listeners: Set<ThemeChangeCallback> = new Set();
  private loadedStylesheets: Map<string, HTMLLinkElement> = new Map();
  private initialized: boolean = false;
  private readonly DEFAULT_STORAGE_KEY = 'app-theme-preference';
  private readonly DEFAULT_DATA_ATTRIBUTE = 'data-theme';

  constructor(config: ThemeConfig, storage?: ThemeStorage) {
    this.validateConfig(config);
    this.config = config;
    this.storage = storage ?? new LocalStorageAdapter();
  }

  /**
   * Initialize the theme manager
   * MUST be called before any components render
   */
  async initialize(): Promise<void> {
    if (this.initialized) {
      console.warn('ThemeManager already initialized');
      return;
    }

    // Determine which theme to load
    const savedThemeId = this.getSavedThemeId();
    const themeToLoad = this.getThemeById(savedThemeId) ?? this.getDefaultTheme();

    // Apply theme synchronously to prevent flicker
    await this.applyTheme(themeToLoad, { skipPersistence: !!savedThemeId });

    // Listen for cross-tab theme changes
    this.setupCrossTabSync();

    this.initialized = true;
  }

  /**
   * Switch to a different theme
   */
  async switchTheme(themeId: string, options?: ThemeSwitchOptions): Promise<void> {
    const theme = this.getThemeById(themeId);
    if (!theme) {
      throw new Error(`Theme not found: ${themeId}`);
    }

    // Skip if already active (unless forced)
    if (!options?.forceReload && this.currentTheme?.id === themeId) {
      return;
    }

    await this.applyTheme(theme, options);
  }

  /**
   * Get the currently active theme
   */
  getCurrentTheme(): Theme | null {
    return this.currentTheme;
  }

  /**
   * Get all available themes
   */
  getAvailableThemes(): Theme[] {
    return [...this.config.themes];
  }

  /**
   * Get a theme by ID
   */
  getThemeById(themeId: string | null): Theme | undefined {
    if (!themeId) return undefined;
    return this.config.themes.find(t => t.id === themeId);
  }

  /**
   * Subscribe to theme change events
   */
  onThemeChange(callback: ThemeChangeCallback): () => void {
    this.listeners.add(callback);
    // Return unsubscribe function
    return () => this.listeners.delete(callback);
  }

  /**
   * Update configuration (supports post-deployment changes)
   */
  updateConfig(newConfig: Partial<ThemeConfig>): void {
    if (newConfig.themes) {
      this.validateThemes(newConfig.themes);
      this.config.themes = newConfig.themes;
    }
    if (newConfig.defaultThemeId) {
      this.config.defaultThemeId = newConfig.defaultThemeId;
    }
    if (newConfig.storageKey !== undefined) {
      this.config.storageKey = newConfig.storageKey;
    }
    if (newConfig.dataAttribute !== undefined) {
      this.config.dataAttribute = newConfig.dataAttribute;
    }
  }

  /**
   * Preload a theme's stylesheets without activating
   */
  async preloadTheme(themeId: string): Promise<void> {
    const theme = this.getThemeById(themeId);
    if (!theme) {
      throw new Error(`Theme not found: ${themeId}`);
    }

    await Promise.all([
      this.loadStylesheet(theme.stylesheetUrl, false),
      theme.colorStylesheetUrl ? this.loadStylesheet(theme.colorStylesheetUrl, false) : Promise.resolve()
    ]);
  }

  // Private methods

  private validateConfig(config: ThemeConfig): void {
    if (!config.themes || config.themes.length < 3) {
      throw new Error('At least 3 themes must be provided');
    }
    this.validateThemes(config.themes);

    if (!config.defaultThemeId) {
      throw new Error('defaultThemeId is required');
    }

    const defaultTheme = config.themes.find(t => t.id === config.defaultThemeId);
    if (!defaultTheme) {
      throw new Error(`Default theme '${config.defaultThemeId}' not found in themes list`);
    }

    // Ensure at least one light and one dark theme
    const hasLight = config.themes.some(t => !t.isDark);
    const hasDark = config.themes.some(t => t.isDark);
    if (!hasLight || !hasDark) {
      throw new Error('Configuration must include at least one light and one dark theme');
    }
  }

  private validateThemes(themes: Theme[]): void {
    const ids = new Set<string>();
    for (const theme of themes) {
      if (!theme.id || !theme.name || !theme.stylesheetUrl) {
        throw new Error('Each theme must have id, name, and stylesheetUrl');
      }
      if (ids.has(theme.id)) {
        throw new Error(`Duplicate theme ID: ${theme.id}`);
      }
      ids.add(theme.id);
    }
  }

  private async applyTheme(theme: Theme, options?: ThemeSwitchOptions): Promise<void> {
    const previousTheme = this.currentTheme;

    // Load new theme stylesheets
    await Promise.all([
      this.loadStylesheet(theme.stylesheetUrl, true),
      theme.colorStylesheetUrl ? this.loadStylesheet(theme.colorStylesheetUrl, true) : Promise.resolve()
    ]);

    // Remove old theme stylesheets
    if (previousTheme) {
      this.unloadStylesheet(previousTheme.stylesheetUrl);
      if (previousTheme.colorStylesheetUrl) {
        this.unloadStylesheet(previousTheme.colorStylesheetUrl);
      }
    }

    // Update current theme
    this.currentTheme = theme;

    // Set data attribute on document element
    const attrName = this.config.dataAttribute ?? this.DEFAULT_DATA_ATTRIBUTE;
    document.documentElement.setAttribute(attrName, theme.id);

    // Set dark mode indicator
    document.documentElement.setAttribute('data-theme-mode', theme.isDark ? 'dark' : 'light');

    // Persist to storage
    if (!options?.skipPersistence) {
      const storageKey = this.config.storageKey ?? this.DEFAULT_STORAGE_KEY;
      this.storage.set(storageKey, theme.id);
    }

    // Notify listeners
    this.notifyListeners({
      previousTheme,
      currentTheme: theme,
      timestamp: Date.now()
    });
  }

  private loadStylesheet(url: string, activate: boolean): Promise<void> {
    return new Promise((resolve, reject) => {
      // Check if already loaded
      if (this.loadedStylesheets.has(url)) {
        const link = this.loadedStylesheets.get(url)!;
        if (activate && link.disabled) {
          link.disabled = false;
        }
        resolve();
        return;
      }

      // Create new link element
      const link = document.createElement('link');
      link.rel = 'stylesheet';
      link.href = url;
      link.disabled = !activate;

      link.onload = () => {
        this.loadedStylesheets.set(url, link);
        resolve();
      };

      link.onerror = () => {
        reject(new Error(`Failed to load stylesheet: ${url}`));
      };

      // Insert at the beginning of head for proper cascade
      const head = document.head;
      if (head.firstChild) {
        head.insertBefore(link, head.firstChild);
      } else {
        head.appendChild(link);
      }
    });
  }

  private unloadStylesheet(url: string): void {
    const link = this.loadedStylesheets.get(url);
    if (link) {
      link.disabled = true;
      // Don't remove from DOM - keep for fast reactivation
    }
  }

  private getSavedThemeId(): string | null {
    const storageKey = this.config.storageKey ?? this.DEFAULT_STORAGE_KEY;
    return this.storage.get(storageKey);
  }

  private getDefaultTheme(): Theme {
    const theme = this.getThemeById(this.config.defaultThemeId);
    if (!theme) {
      throw new Error(`Default theme '${this.config.defaultThemeId}' not found`);
    }
    return theme;
  }

  private notifyListeners(event: ThemeChangeEvent): void {
    this.listeners.forEach(callback => {
      try {
        callback(event);
      } catch (err) {
        console.error('Error in theme change listener:', err);
      }
    });
  }

  private setupCrossTabSync(): void {
    if (typeof window === 'undefined') return;

    window.addEventListener('storage', (event) => {
      const storageKey = this.config.storageKey ?? this.DEFAULT_STORAGE_KEY;
      if (event.key === storageKey && event.newValue) {
        const themeId = event.newValue;
        if (this.currentTheme?.id !== themeId) {
          this.switchTheme(themeId, { skipPersistence: true }).catch(err => {
            console.error('Failed to sync theme from another tab:', err);
          });
        }
      }
    });
  }
}

configLoader.ts

import { ThemeConfig } from './types';

/**
 * Configuration loader for theme settings
 * Supports loading from JSON files for post-deployment adjustments
 */
export class ThemeConfigLoader {
  /**
   * Load configuration from a JSON file
   * Useful for admin-adjustable configurations
   */
  static async loadFromUrl(url: string): Promise<ThemeConfig> {
    try {
      const response = await fetch(url);
      if (!response.ok) {
        throw new Error(`Failed to load config from ${url}: ${response.statusText}`);
      }
      const config = await response.json();
      return this.normalizeConfig(config);
    } catch (error) {
      console.error('Error loading theme configuration:', error);
      throw error;
    }
  }

  /**
   * Load configuration from inline script tag
   * Useful for server-side rendered configurations
   */
  static loadFromScriptTag(scriptId: string): ThemeConfig {
    const scriptElement = document.getElementById(scriptId);
    if (!scriptElement) {
      throw new Error(`Script tag with id '${scriptId}' not found`);
    }

    try {
      const config = JSON.parse(scriptElement.textContent || '{}');
      return this.normalizeConfig(config);
    } catch (error) {
      console.error('Error parsing theme configuration from script tag:', error);
      throw error;
    }
  }

  /**
   * Create a static configuration
   * Useful for simple setups without external config files
   */
  static createStatic(config: ThemeConfig): ThemeConfig {
    return this.normalizeConfig(config);
  }

  /**
   * Merge configuration with defaults and normalize URLs
   */
  private static normalizeConfig(config: any): ThemeConfig {
    if (!config.themes || !Array.isArray(config.themes)) {
      throw new Error('Invalid configuration: themes array is required');
    }

    // Normalize theme URLs (support relative paths)
    const normalizedThemes = config.themes.map((theme: any) => ({
      ...theme,
      stylesheetUrl: this.normalizeUrl(theme.stylesheetUrl),
      colorStylesheetUrl: theme.colorStylesheetUrl 
        ? this.normalizeUrl(theme.colorStylesheetUrl) 
        : undefined
    }));

    return {
      themes: normalizedThemes,
      defaultThemeId: config.defaultThemeId,
      storageKey: config.storageKey,
      preventFlicker: config.preventFlicker ?? true,
      dataAttribute: config.dataAttribute
    };
  }

  /**
   * Normalize URL to absolute path or full URL
   */
  private static normalizeUrl(url: string): string {
    // Already absolute URL
    if (url.startsWith('http://') || url.startsWith('https://') || url.startsWith('//')) {
      return url;
    }

    // Absolute path
    if (url.startsWith('/')) {
      return url;
    }

    // Relative path - resolve against base
    const base = document.baseURI || window.location.href;
    try {
      return new URL(url, base).href;
    } catch {
      // Fallback to simple concatenation
      return url;
    }
  }

  /**
   * Validate configuration before use
   */
  static validate(config: ThemeConfig): boolean {
    try {
      if (!config.themes || config.themes.length < 3) {
        console.error('Configuration must have at least 3 themes');
        return false;
      }

      if (!config.defaultThemeId) {
        console.error('Configuration must specify defaultThemeId');
        return false;
      }

      const defaultExists = config.themes.some(t => t.id === config.defaultThemeId);
      if (!defaultExists) {
        console.error(`Default theme '${config.defaultThemeId}' not found in themes`);
        return false;
      }

      const hasLight = config.themes.some(t => !t.isDark);
      const hasDark = config.themes.some(t => t.isDark);
      if (!hasLight || !hasDark) {
        console.error('Configuration must include at least one light and one dark theme');
        return false;
      }

      return true;
    } catch (error) {
      console.error('Configuration validation error:', error);
      return false;
    }
  }
}

theme.service.ts

import { Injectable, OnDestroy } from '@angular/core';
import { BehaviorSubject, Observable } from 'rxjs';
import { ThemeManager } from './theme-manager';
import { Theme, ThemeConfig, ThemeSwitchOptions } from './types';
import { ThemeConfigLoader } from './config-loader';

/**
 * Angular service for theme management
 * Provides reactive theme state and Angular-friendly API
 */
@Injectable({
  providedIn: 'root'
})
export class ThemeService implements OnDestroy {
  private manager: ThemeManager | null = null;
  private currentTheme$ = new BehaviorSubject<Theme | null>(null);
  private unsubscribe: (() => void) | null = null;

  /**
   * Observable of the current theme
   */
  get theme$(): Observable<Theme | null> {
    return this.currentTheme$.asObservable();
  }

  /**
   * Get the current theme synchronously
   */
  get currentTheme(): Theme | null {
    return this.manager?.getCurrentTheme() ?? null;
  }

  /**
   * Get all available themes
   */
  get availableThemes(): Theme[] {
    return this.manager?.getAvailableThemes() ?? [];
  }

  /**
   * Initialize the theme service with configuration
   * MUST be called in APP_INITIALIZER before app renders
   */
  async initialize(config: ThemeConfig): Promise<void> {
    if (this.manager) {
      console.warn('ThemeService already initialized');
      return;
    }

    this.manager = new ThemeManager(config);

    // Subscribe to theme changes
    this.unsubscribe = this.manager.onThemeChange(event => {
      this.currentTheme$.next(event.currentTheme);
    });

    // Initialize the manager
    await this.manager.initialize();

    // Set initial value
    this.currentTheme$.next(this.manager.getCurrentTheme());
  }

  /**
   * Initialize from a configuration file URL
   */
  async initializeFromUrl(configUrl: string): Promise<void> {
    const config = await ThemeConfigLoader.loadFromUrl(configUrl);
    await this.initialize(config);
  }

  /**
   * Switch to a different theme
   */
  async switchTheme(themeId: string, options?: ThemeSwitchOptions): Promise<void> {
    if (!this.manager) {
      throw new Error('ThemeService not initialized');
    }
    await this.manager.switchTheme(themeId, options);
  }

  /**
   * Toggle between light and dark theme
   */
  async toggleDarkMode(): Promise<void> {
    if (!this.manager) {
      throw new Error('ThemeService not initialized');
    }

    const current = this.manager.getCurrentTheme();
    if (!current) return;

    const themes = this.manager.getAvailableThemes();

    // Find a theme with opposite mode
    const targetTheme = themes.find(t => t.isDark !== current.isDark);
    if (targetTheme) {
      await this.switchTheme(targetTheme.id);
    }
  }

  /**
   * Preload a theme for faster switching
   */
  async preloadTheme(themeId: string): Promise<void> {
    if (!this.manager) {
      throw new Error('ThemeService not initialized');
    }
    await this.manager.preloadTheme(themeId);
  }

  /**
   * Update configuration (supports admin changes)
   */
  updateConfig(newConfig: Partial<ThemeConfig>): void {
    if (!this.manager) {
      throw new Error('ThemeService not initialized');
    }
    this.manager.updateConfig(newConfig);
  }

  ngOnDestroy(): void {
    if (this.unsubscribe) {
      this.unsubscribe();
    }
    this.currentTheme$.complete();
  }
}

/**
 * Factory function for APP_INITIALIZER
 * Ensures theme is loaded before app renders
 */
export function themeInitializerFactory(
  themeService: ThemeService,
  configUrlOrConfig: string | ThemeConfig
): () => Promise<void> {
  return async () => {
    if (typeof configUrlOrConfig === 'string') {
      await themeService.initializeFromUrl(configUrlOrConfig);
    } else {
      await themeService.initialize(configUrlOrConfig);
    }
  };
}

theme.module.ts

import { NgModule, APP_INITIALIZER, ModuleWithProviders } from '@angular/core';
import { CommonModule } from '@angular/common';
import { ThemeService, themeInitializerFactory } from './theme.service';
import { ThemeConfig } from '../types';

/**
 * Configuration for ThemeModule
 */
export interface ThemeModuleConfig {
  /** URL to load configuration from, or static config object */
  config: string | ThemeConfig;
}

/**
 * Angular module for theme management
 * Import this in your AppModule with forRoot()
 */
@NgModule({
  imports: [CommonModule]
})
export class ThemeModule {
  /**
   * Configure the theme module with initialization
   * Use this in your AppModule imports
   * 
   * Example:
   * ```

typescript
   * ThemeModule.forRoot({
   *   config: '/assets/theme-config.json'
   * })
   *

*/
static forRoot(config: ThemeModuleConfig): ModuleWithProviders {
return {
ngModule: ThemeModule,
providers: [
ThemeService,
{
provide: APP_INITIALIZER,
useFactory: themeInitializerFactory,
deps: [ThemeService],
multi: true,
useValue: () => themeInitializerFactory(
// These will be injected by Angular
null as any,
config.config
)
}
]
};
}
}




themeConfig.json


```json
{
  "themes": [
    {
      "id": "light-default",
      "name": "Light Default",
      "stylesheetUrl": "/themes/light.css",
      "colorStylesheetUrl": "/themes/colors.css",
      "isDark": false,
      "metadata": {
        "description": "Clean light theme with blue accents"
      }
    },
    {
      "id": "dark-default",
      "name": "Dark Default",
      "stylesheetUrl": "/themes/dark.css",
      "colorStylesheetUrl": "/themes/colors-dark.css",
      "isDark": true,
      "metadata": {
        "description": "Elegant dark theme with reduced eye strain"
      }
    },
    {
      "id": "high-contrast",
      "name": "High Contrast",
      "stylesheetUrl": "/themes/high-contrast.css",
      "isDark": false,
      "metadata": {
        "description": "Maximum contrast for accessibility"
      }
    },
    {
      "id": "blue-ocean",
      "name": "Blue Ocean",
      "stylesheetUrl": "https://cdn.example.com/themes/blue-ocean.css",
      "colorStylesheetUrl": "/themes/colors.css",
      "isDark": false,
      "metadata": {
        "description": "Calming blue theme",
        "cdnHosted": true
      }
    },
    {
      "id": "midnight",
      "name": "Midnight",
      "stylesheetUrl": "https://cdn.example.com/themes/midnight.css",
      "colorStylesheetUrl": "/themes/colors-dark.css",
      "isDark": true,
      "metadata": {
        "description": "Deep blue dark theme",
        "cdnHosted": true
      }
    }
  ],
  "defaultThemeId": "light-default",
  "storageKey": "my-app-theme",
  "preventFlicker": true,
  "dataAttribute": "data-theme"
}

vanilla usage.ts

/**
 * Vanilla JavaScript/TypeScript Usage Example
 * Shows how to use the theme system without Angular
 */

import { ThemeManager, ThemeConfigLoader } from './theme-system';

// Example 1: Initialize with static configuration
async function initializeWithStaticConfig() {
  const manager = new ThemeManager({
    themes: [
      {
        id: 'light',
        name: 'Light Theme',
        stylesheetUrl: '/themes/light.css',
        colorStylesheetUrl: '/themes/colors.css',
        isDark: false
      },
      {
        id: 'dark',
        name: 'Dark Theme',
        stylesheetUrl: '/themes/dark.css',
        colorStylesheetUrl: '/themes/colors-dark.css',
        isDark: true
      },
      {
        id: 'sepia',
        name: 'Sepia Theme',
        stylesheetUrl: '/themes/sepia.css',
        isDark: false
      }
    ],
    defaultThemeId: 'light',
    storageKey: 'my-app-theme'
  });

  // IMPORTANT: Initialize before rendering any content
  await manager.initialize();

  return manager;
}

// Example 2: Initialize with external config file
async function initializeWithConfigFile() {
  const config = await ThemeConfigLoader.loadFromUrl('/assets/theme-config.json');
  const manager = new ThemeManager(config);

  await manager.initialize();

  return manager;
}

// Example 3: Build a simple theme picker UI
function createThemePicker(manager: ThemeManager) {
  const container = document.createElement('div');
  container.className = 'theme-picker';

  // Create select dropdown
  const select = document.createElement('select');
  select.id = 'theme-selector';

  const themes = manager.getAvailableThemes();
  themes.forEach(theme => {
    const option = document.createElement('option');
    option.value = theme.id;
    option.textContent = theme.name;
    if (manager.getCurrentTheme()?.id === theme.id) {
      option.selected = true;
    }
    select.appendChild(option);
  });

  // Handle theme changes
  select.addEventListener('change', async (e) => {
    const target = e.target as HTMLSelectElement;
    await manager.switchTheme(target.value);
  });

  // Create dark mode toggle button
  const toggleBtn = document.createElement('button');
  toggleBtn.className = 'dark-mode-toggle';

  const updateToggleButton = () => {
    const current = manager.getCurrentTheme();
    toggleBtn.textContent = current?.isDark ? '☀️ Light Mode' : '🌙 Dark Mode';
  };

  updateToggleButton();

  toggleBtn.addEventListener('click', async () => {
    const current = manager.getCurrentTheme();
    if (!current) return;

    const themes = manager.getAvailableThemes();
    const oppositeMode = themes.find(t => t.isDark !== current.isDark);

    if (oppositeMode) {
      await manager.switchTheme(oppositeMode.id);
    }
  });

  // Listen for theme changes to update UI
  manager.onThemeChange((event) => {
    select.value = event.currentTheme.id;
    updateToggleButton();
    console.log('Theme changed:', event);
  });

  container.appendChild(select);
  container.appendChild(toggleBtn);

  return container;
}

// Example 4: Complete initialization with UI
async function initializeApp() {
  try {
    // Load configuration
    const config = await ThemeConfigLoader.loadFromUrl('/assets/theme-config.json');

    // Validate before use
    if (!ThemeConfigLoader.validate(config)) {
      throw new Error('Invalid theme configuration');
    }

    // Create manager
    const manager = new ThemeManager(config);

    // Initialize (must happen before render)
    await manager.initialize();

    // Preload alternate themes for smooth switching
    const themes = manager.getAvailableThemes();
    const currentId = manager.getCurrentTheme()?.id;
    const preloadPromises = themes
      .filter(t => t.id !== currentId)
      .slice(0, 2) // Preload first 2 alternate themes
      .map(t => manager.preloadTheme(t.id));

    // Preload in background (don't await)
    Promise.all(preloadPromises).catch(err => {
      console.warn('Failed to preload some themes:', err);
    });

    // Create and mount theme picker
    const picker = createThemePicker(manager);
    document.getElementById('theme-picker-container')?.appendChild(picker);

    // Log successful initialization
    console.log('Theme system initialized successfully');
    console.log('Current theme:', manager.getCurrentTheme());

    return manager;
  } catch (error) {
    console.error('Failed to initialize theme system:', error);
    throw error;
  }
}

// Example 5: Usage in PWA with service worker
async function initializeForPWA() {
  const manager = await initializeWithConfigFile();

  // Listen for service worker updates
  if ('serviceWorker' in navigator) {
    navigator.serviceWorker.addEventListener('controllerchange', () => {
      // Reload theme after service worker update
      const currentTheme = manager.getCurrentTheme();
      if (currentTheme) {
        manager.switchTheme(currentTheme.id, { forceReload: true });
      }
    });
  }

  return manager;
}

// Export for use
export {
  initializeWithStaticConfig,
  initializeWithConfigFile,
  createThemePicker,
  initializeApp,
  initializeForPWA
};

// Auto-initialize if this is the main script
if (typeof window !== 'undefined') {
  // Wait for DOM ready
  if (document.readyState === 'loading') {
    document.addEventListener('DOMContentLoaded', initializeApp);
  } else {
    initializeApp();
  }
}

index.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Theme System Example - Anti-Flicker Demo</title>

  <!-- 
    ANTI-FLICKER TECHNIQUE:
    This inline script loads and applies the theme BEFORE the page renders,
    preventing the flash of unstyled content (FOUC).
  -->
  <script>
    (function() {
      // Load saved theme preference
      const STORAGE_KEY = 'app-theme-preference';
      const DEFAULT_THEME = 'light';

      let savedThemeId;
      try {
        savedThemeId = localStorage.getItem(STORAGE_KEY);
      } catch (e) {
        // localStorage unavailable
      }

      const themeId = savedThemeId || DEFAULT_THEME;

      // Set data attribute immediately
      document.documentElement.setAttribute('data-theme', themeId);

      // Inline critical theme configuration
      const themeMap = {
        'light': {
          stylesheet: '/themes/light.css',
          colors: '/themes/colors.css',
          isDark: false
        },
        'dark': {
          stylesheet: '/themes/dark.css',
          colors: '/themes/colors-dark.css',
          isDark: true
        },
        'high-contrast': {
          stylesheet: '/themes/high-contrast.css',
          isDark: false
        }
      };

      const theme = themeMap[themeId] || themeMap[DEFAULT_THEME];

      // Set theme mode
      document.documentElement.setAttribute('data-theme-mode', theme.isDark ? 'dark' : 'light');

      // Inject stylesheets synchronously
      function injectStylesheet(href) {
        document.write('<link rel="stylesheet" href="' + href + '">');
      }

      injectStylesheet(theme.stylesheet);
      if (theme.colors) {
        injectStylesheet(theme.colors);
      }
    })();
  </script>

  <!-- Base styles that work with all themes -->
  <style>
    * {
      margin: 0;
      padding: 0;
      box-sizing: border-box;
    }

    body {
      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
      line-height: 1.6;
      padding: 2rem;
      background: var(--bg-primary, #ffffff);
      color: var(--text-primary, #000000);
      transition: background-color 0.3s ease, color 0.3s ease;
    }

    .container {
      max-width: 1200px;
      margin: 0 auto;
    }

    .theme-picker {
      display: flex;
      gap: 1rem;
      align-items: center;
      padding: 1rem;
      background: var(--bg-secondary, #f5f5f5);
      border-radius: 8px;
      margin-bottom: 2rem;
    }

    select, button {
      padding: 0.75rem 1rem;
      border: 1px solid var(--border-color, #ddd);
      border-radius: 6px;
      background: var(--input-bg, #fff);
      color: var(--input-text, #000);
      font-size: 1rem;
      cursor: pointer;
      transition: all 0.2s ease;
    }

    button:hover {
      background: var(--input-hover-bg, #f0f0f0);
    }

    .card {
      background: var(--card-bg, #ffffff);
      border: 1px solid var(--border-color, #e0e0e0);
      border-radius: 8px;
      padding: 2rem;
      margin-bottom: 1rem;
      box-shadow: 0 2px 4px var(--shadow-color, rgba(0, 0, 0, 0.1));
    }

    h1, h2 {
      margin-bottom: 1rem;
      color: var(--heading-color, #333);
    }

    .info {
      padding: 1rem;
      background: var(--info-bg, #e3f2fd);
      border-left: 4px solid var(--info-border, #2196f3);
      border-radius: 4px;
      margin: 1rem 0;
    }
  </style>
</head>
<body>
  <div class="container">
    <header>
      <h1>Theme System Demo</h1>
      <p>Demonstrating flicker-free theme loading and switching</p>
    </header>

    <div id="theme-picker-container" class="theme-picker">
      <!-- Theme picker will be inserted here by JavaScript -->
    </div>

    <main>
      <div class="card">
        <h2>Anti-Flicker Technique</h2>
        <p>
          This page loads the theme <strong>before</strong> rendering any content, 
          preventing the flash of unstyled content (FOUC). The inline script in the 
          <code>&lt;head&gt;</code> section:
        </p>
        <ul>
          <li>Reads the saved theme preference from localStorage</li>
          <li>Sets data attributes on the document element</li>
          <li>Injects theme stylesheets synchronously</li>
          <li>All before the page renders</li>
        </ul>
      </div>

      <div class="card">
        <h2>Features Demonstrated</h2>
        <ul>
          <li>✅ Multiple theme support (3+ themes)</li>
          <li>✅ Light and dark mode support</li>
          <li>✅ No visual flicker on load or theme switch</li>
          <li>✅ Cross-tab synchronization</li>
          <li>✅ Persistent theme preference</li>
          <li>✅ PWA and offline support</li>
        </ul>
      </div>

      <div class="info">
        <strong>Try it:</strong> Switch themes using the picker above, then open this page 
        in a new tab. Your theme preference will be preserved. Try switching themes in one 
        tab and watch it update in the other!
      </div>
    </main>
  </div>

  <!-- Main application script -->
  <script type="module">
    import { initializeApp } from './examples/vanilla-usage.js';

    // Initialize the full theme system
    // The anti-flicker script above already applied the theme,
    // this just sets up the interactive features
    initializeApp().catch(err => {
      console.error('Failed to initialize theme system:', err);
    });
  </script>
</body>
</html>

Analysis

I have crafted one from scratch based on the same functional requirements and technical requirements, conforming to my design principles for UI, UX and Developer Experience:

Yet Another Web Theme Loader

Comparing with my hand-crafted sourcecode and what generated by Copilot, as a dedicated AI code generator, Claude.ai is much more diligent in crafting codes with more complex implementation, while the API design is as complex as those generated by Copilot.

Use M365 Copilot to Craft Web Theme Loader

fonlow — Wed, 18 Feb 2026 18:54:27 +0000

Requirements

User Story

As a web app user, I want to choose from multiple available themes — sometimes light, other times dark.

Work Order

Functional Requirements

Support both light and dark themes.
Support more than two themes — at least three themes must be available.
Support commonly used prebuilt themes, optionally combined with an app‑specific color stylesheet such as colors.css, with an optional dark‑mode variant like colors-dark.css.
Support dynamic switching between themes at runtime.
When the same web app/site is opened in another browser tab, the explicitly selected theme should be preserved and applied.

Technical Requirements

Reusable across multiple applications.
Minimal API surface to ensure easy customization and easy usage.
Neutral with respect to specific UI design choices.
Must be efficient and avoid visual flicker during startup and theme switching.
Usable in both SPA and PWA.
Fully functional in PWAs, offline usage, and intranet environments.
Adjustable after build, bundling, and deployment. For example, an admin should be able to change the number and order of available themes, and modify app‑specific color files.
Themes may be hosted locally or on a CDN.
Selecting a theme that is already loaded should not trigger a reload of the theme.
Core theme management must be separated from the theme‑picker UI.
The config settings must be loaded during app startup before any component is rendered.

Using the requirements as prompt, I asked M365 Copilot to generate sourcecode, and the following is the result.

Below is a framework‑agnostic TypeScript API (with an optional Angular PWA integration) that lets you configure, preload, and switch among multiple themes (≥3), with instant cross‑tab sync, no FOUC/flicker, offline/PWA support, and post‑deployment reconfigurability.

What you get

✅ Core theme management in a standalone, reusable class (ThemeManager)
✅ Neutral API (no opinionated UI) — you plug it into any UI (React, Vue, Angular, plain HTML)
✅ Support for light & dark + any number of additional themes
✅ Prebuilt theme CSS + app‑specific colors.css (and colors-dark.css)
✅ Runtime switching with no flicker and no redundant reloads
✅ Cross‑tab persistence (Storage + BroadcastChannel)
✅ Config from JSON (editable after deployment) or embedded <script> JSON
✅ Local or CDN hosting, optional SRI/CORS
✅ SPA & PWA ready with early-boot snippet to avoid flash
✅ Optional: Angular Service + APP_INITIALIZER + ngsw-config hints

1) Core Types

// src/theme.types.ts
export type ThemeMode = 'light' | 'dark';

export interface ThemeEntry {
  /** Unique theme identifier (e.g., 'light', 'dark', 'nord') */
  id: string;
  /** Human-readable name for pickers ("Light", "Dark", "Nord") */
  label: string;
  /** Light or dark; used for system color-scheme and optional color variants */
  mode: ThemeMode;

  /** URL for the base/prebuilt theme stylesheet (CDN or local) */
  css: string;

  /**
   * App-specific color overrides for light mode (optional).
   * e.g., '/assets/colors.css' or 'https://cdn/.../colors.css'
   */
  colors?: string;

  /**
   * App-specific color overrides for dark mode (optional).
   * If absent and mode === 'dark', `colors` is used (if present).
   */
  colorsDark?: string;

  /** Optional Subresource Integrity and CORS for CDN-hosted CSS */
  integrity?: string;
  crossorigin?: 'anonymous' | 'use-credentials';

  /** Preload this theme’s CSS at startup (non-blocking) */
  preload?: boolean;
}

export interface ThemeConfig {
  /** Order matters; you can re-order after deployment */
  themes: ThemeEntry[];

  /**
   * Default theme id to apply on first load if nothing is stored.
   * If omitted, first theme in `themes` is used.
   */
  defaultThemeId?: string;
}

export interface ThemeManagerOptions {
  /** Key names for storage (allow multiple apps on same origin) */
  storageKeyActiveId?: string;     // default: 'theme.active'
  storageKeyLinks?: string;        // default: 'theme.links'
  broadcastChannelName?: string;   // default: 'theme-channel'
  /** Optional element IDs if you want fixed link IDs */
  coreLinkId?: string;             // default: 'tm-core'
  colorsLinkId?: string;           // default: 'tm-colors'
}

2) Core Theme Manager (framework‑agnostic)

// src/theme.manager.ts
import { ThemeConfig, ThemeEntry, ThemeManagerOptions } from './theme.types';

type Unsubscribe = () => void;

export class ThemeManager {
  private config: ThemeConfig | null = null;
  private activeThemeId: string | null = null;
  private listeners = new Set<(id: string) => void>();

  private readonly storageKeyActiveId: string;
  private readonly storageKeyLinks: string;
  private readonly broadcastChannelName: string;

  private channel: BroadcastChannel | null = null;

  private readonly coreLinkId: string;
  private readonly colorsLinkId: string;

  private initializing = false;

  constructor(opts: ThemeManagerOptions = {}) {
    this.storageKeyActiveId = opts.storageKeyActiveId ?? 'theme.active';
    this.storageKeyLinks    = opts.storageKeyLinks ?? 'theme.links';
    this.broadcastChannelName = opts.broadcastChannelName ?? 'theme-channel';
    this.coreLinkId = opts.coreLinkId ?? 'tm-core';
    this.colorsLinkId = opts.colorsLinkId ?? 'tm-colors';

    // Cross-tab sync via BroadcastChannel + storage events
    try {
      this.channel = new BroadcastChannel(this.broadcastChannelName);
      this.channel.onmessage = (ev) => {
        if (ev?.data?.type === 'theme-change' && ev?.data?.id) {
          if (ev.data.id !== this.activeThemeId) {
            // Don’t await to keep handler responsive
            this.applyTheme(ev.data.id).catch(console.error);
          }
        }
      };
    } catch {
      // BroadcastChannel may not exist — storage event fallback below
      this.channel = null;
    }

    window.addEventListener('storage', (e) => {
      if (e.key === this.storageKeyActiveId && typeof e.newValue === 'string') {
        const id = e.newValue;
        if (id && id !== this.activeThemeId) {
          this.applyTheme(id).catch(console.error);
        }
      }
    });
  }

  /** Initialize from one of: inline script JSON, direct config, or URL */
  async init(options: {
    embeddedScriptId?: string;      // <script type="application/json" id="theme-config">…</script>
    config?: ThemeConfig;
    configUrl?: string;             // '/theme.config.json'
  } = {}): Promise<void> {
    if (this.initializing) return;
    this.initializing = true;

    // Load configuration
    if (options.config) {
      this.setConfig(options.config);
    } else if (options.embeddedScriptId) {
      const el = document.getElementById(options.embeddedScriptId);
      if (!el) throw new Error(`Theme config script#${options.embeddedScriptId} not found`);
      const json = el.textContent?.trim() || '{}';
      this.setConfig(JSON.parse(json));
    } else if (options.configUrl) {
      // Fetch at runtime → adjustable after deployment (works offline with SW)
      const resp = await fetch(options.configUrl, { cache: 'no-cache' });
      if (!resp.ok) throw new Error(`Failed to fetch theme config from ${options.configUrl}`);
      this.setConfig(await resp.json());
    } else {
      throw new Error('ThemeManager.init requires one of: config, embeddedScriptId, or configUrl');
    }

    // Determine initial theme: stored → config.default → first theme
    const storedId = localStorage.getItem(this.storageKeyActiveId);
    const initialId =
      (storedId && this.findTheme(storedId) ? storedId : null) ||
      this.config!.defaultThemeId ||
      this.config!.themes[0].id;

    await this.applyTheme(initialId, { skipIfActive: true, fastPathIfCached: true });

    // Optional: preload other themes marked with `preload: true`
    this.preloadMarkedThemes().catch(console.error);

    this.initializing = false;
  }

  /** In-memory config update (e.g., admin can swap order after deployment) */
  setConfig(config: ThemeConfig) {
    if (!config?.themes?.length) {
      throw new Error('ThemeConfig must include at least one theme');
    }
    this.config = {
      ...config,
      themes: config.themes.map(t => ({ ...t })),
    };
  }

  getThemes(): ReadonlyArray<Pick<ThemeEntry, 'id' | 'label' | 'mode'>> {
    if (!this.config) return [];
    return this.config.themes.map(({ id, label, mode }) => ({ id, label, mode }));
  }

  getActiveThemeId(): string | null {
    return this.activeThemeId;
  }

  /** Subscribe to theme changes */
  onChange(cb: (id: string) => void): Unsubscribe {
    this.listeners.add(cb);
    return () => this.listeners.delete(cb);
  }

  /** Apply a theme by id */
  async applyTheme(id: string, opts: { skipIfActive?: boolean; forceReload?: boolean; fastPathIfCached?: boolean } = {}): Promise<void> {
    if (!this.config) throw new Error('ThemeManager not initialized');
    const theme = this.findTheme(id);
    if (!theme) throw new Error(`Unknown theme id: ${id}`);

    if (opts.skipIfActive && this.activeThemeId === id) return;

    // If already active and not forced → no-op
    if (!opts.forceReload && this.activeThemeId === id) return;

    const { coreHref, colorsHref } = this.resolveHrefs(theme);

    // If already loaded with same hrefs → no-op
    const current = this.readCurrentLinkHrefs();
    if (!opts.forceReload && current.coreHref === coreHref && current.colorsHref === colorsHref) {
      if (this.activeThemeId !== id) {
        this.activeThemeId = id;
        this.afterApplied(theme);
      }
      return;
    }

    // Load core CSS first (swap seamlessly), then colors if provided
    await this.swapStylesheet(this.coreLinkId, coreHref, theme.integrity, theme.crossorigin, { fastPathIfCached: opts.fastPathIfCached });

    if (colorsHref) {
      await this.swapStylesheet(this.colorsLinkId, colorsHref, theme.integrity, theme.crossorigin, { fastPathIfCached: opts.fastPathIfCached });
    } else {
      // Remove colors link if it exists
      const colorsEl = document.getElementById(this.colorsLinkId);
      if (colorsEl?.parentNode) colorsEl.parentNode.removeChild(colorsEl);
    }

    this.activeThemeId = id;
    this.persist(id, coreHref, colorsHref);
    this.afterApplied(theme);
    this.broadcast(id);
  }

  /** Preload all themes flagged with `preload: true` */
  async preloadMarkedThemes(): Promise<void> {
    if (!this.config) return;
    const tasks: Promise<unknown>[] = [];
    for (const t of this.config.themes) {
      if (t.preload) {
        const { coreHref, colorsHref } = this.resolveHrefs(t);
        tasks.push(this.preloadStylesheet(coreHref, t.integrity, t.crossorigin));
        if (colorsHref) tasks.push(this.preloadStylesheet(colorsHref, t.integrity, t.crossorigin));
      }
    }
    await Promise.allSettled(tasks);
  }

  destroy() {
    this.channel?.close();
    this.listeners.clear();
  }

  // ===== Internals =====

  private findTheme(id: string): ThemeEntry | undefined {
    return this.config!.themes.find(t => t.id === id);
  }

  private resolveHrefs(theme: ThemeEntry): { coreHref: string; colorsHref?: string } {
    const coreHref = theme.css;
    let colorsHref: string | undefined;
    if (theme.mode === 'dark') {
      colorsHref = theme.colorsDark || theme.colors; // Prefer dark override
    } else {
      colorsHref = theme.colors;
    }
    return { coreHref, colorsHref };
  }

  private afterApplied(theme: ThemeEntry) {
    // Set DOM attributes for CSS hooks and accessibility
    document.documentElement.setAttribute('data-theme', theme.id);
    document.documentElement.setAttribute('data-theme-mode', theme.mode);

    // Hint to UA for form controls, etc.
    const colorScheme = theme.mode === 'dark' ? 'dark' : 'light';
    let meta = document.querySelector('meta[name="color-scheme"]') as HTMLMetaElement | null;
    if (!meta) {
      meta = document.createElement('meta');
      meta.name = 'color-scheme';
      document.head.appendChild(meta);
    }
    meta.content = colorScheme;

    // Notify listeners
    for (const cb of this.listeners) {
      try { cb(theme.id); } catch (e) { console.error(e); }
    }
  }

  private persist(id: string, coreHref: string, colorsHref?: string) {
    localStorage.setItem(this.storageKeyActiveId, id);
    localStorage.setItem(this.storageKeyLinks, JSON.stringify({ coreHref, colorsHref: colorsHref || '' }));
  }

  private broadcast(id: string) {
    try { this.channel?.postMessage({ type: 'theme-change', id }); } catch {}
  }

  private readCurrentLinkHrefs(): { coreHref: string; colorsHref: string } {
    const coreEl = document.getElementById(this.coreLinkId) as HTMLLinkElement | null;
    const colorsEl = document.getElementById(this.colorsLinkId) as HTMLLinkElement | null;
    return {
      coreHref: coreEl?.href || '',
      colorsHref: colorsEl?.href || '',
    };
    // Note: .href returns absolute URL; comparisons still work because we set via .href later.
  }

  private async swapStylesheet(
    linkId: string,
    href: string,
    integrity?: string,
    crossorigin?: 'anonymous' | 'use-credentials',
    opts: { fastPathIfCached?: boolean } = {}
  ): Promise<void> {
    const existing = document.getElementById(linkId) as HTMLLinkElement | null;

    // If existing already points to same URL → no-op
    if (existing && sameUrl(existing.href, href)) return;

    // Create new link (preload then promote to stylesheet to avoid flash)
    const preload = document.createElement('link');
    preload.rel = 'preload';
    preload.as = 'style';
    preload.href = href;
    preload.id = `${linkId}-preload`;
    if (integrity) preload.integrity = integrity;
    if (crossorigin) preload.crossOrigin = crossorigin;

    const whenLoaded = new Promise<void>((resolve, reject) => {
      preload.addEventListener('load', () => resolve());
      preload.addEventListener('error', () => reject(new Error(`Failed to preload ${href}`)));
    });

    document.head.appendChild(preload);

    // If CSS is cached, browsers often fulfill immediately (fast path).
    if (opts.fastPathIfCached) {
      // small microtask delay to allow load handler; then continue
      await Promise.race([whenLoaded, microDelay(12)]);
    } else {
      await whenLoaded;
    }

    // Promote to real stylesheet
    const next = document.createElement('link');
    next.rel = 'stylesheet';
    next.href = href;
    next.id = linkId;
    if (integrity) next.integrity = integrity;
    if (crossorigin) next.crossOrigin = crossorigin;

    // Ensure new stylesheet is ready before removing the old one
    const onReady = new Promise<void>((resolve, reject) => {
      next.addEventListener('load', () => resolve());
      next.addEventListener('error', () => reject(new Error(`Failed to load ${href}`)));
    });

    document.head.appendChild(next);
    await onReady;

    // Remove preload and previous link
    safeRemove(preload);
    if (existing) safeRemove(existing);
  }

  private async preloadStylesheet(href: string, integrity?: string, crossorigin?: 'anonymous' | 'use-credentials') {
    const link = document.createElement('link');
    link.rel = 'preload';
    link.as = 'style';
    link.href = href;
    if (integrity) link.integrity = integrity;
    if (crossorigin) link.crossOrigin = crossorigin;
    link.setAttribute('data-theme-preload', 'true');

    const whenLoaded = new Promise<void>((resolve, reject) => {
      link.addEventListener('load', () => resolve());
      link.addEventListener('error', () => reject(new Error(`Failed to preload ${href}`)));
    });

    document.head.appendChild(link);
    return whenLoaded.finally(() => safeRemove(link));
  }
}

function sameUrl(a: string, b: string): boolean {
  try {
    return new URL(a, document.baseURI).href === new URL(b, document.baseURI).href;
  } catch {
    return a === b;
  }
}

function safeRemove(node: Element | null) {
  if (node && node.parentNode) node.parentNode.removeChild(node);
}

function microDelay(ms: number) {
  return new Promise<void>(r => setTimeout(r, ms));
}

3) Configuration (editable after deployment)

You can deliver the theme list in any of these ways (choose one):

External JSON file (/theme.config.json) — easy for admins to replace without rebuilding
Inline JSON inside an HTML <script type="application/json" id="theme-config">
Direct object in code (less flexible after deployment)

Example: `/theme.config.json`

{
  "defaultThemeId": "light",
  "themes": [
    {
      "id": "light",
      "label": "Light",
      "mode": "light",
      "css": "/themes/prebuilt/light.css",
      "colors": "/themes/app/colors.css",
      "preload": true
    },
    {
      "id": "dark",
      "label": "Dark",
      "mode": "dark",
      "css": "/themes/prebuilt/dark.css",
      "colors": "/themes/app/colors.css",
      "colorsDark": "/themes/app/colors-dark.css",
      "preload": true
    },
    {
      "id": "nord",
      "label": "Nord",
      "mode": "dark",
      "css": "https://cdn.example.com/themes/nord.min.css",
      "colors": "/themes/app/colors.css",
      "colorsDark": "/themes/app/colors-dark.css",
      "integrity": "sha384-...your-sri-hash...",
      "crossorigin": "anonymous"
    }
  ]
}

Local or CDN: URLs can be relative or absolute. SRI/CORS fields support CDN integrity checks.

4) Early‑Boot No‑Flicker Snippet (insert in `<head>`)

This tiny, blocking snippet applies the last chosen theme before first paint, avoiding any “flash of unthemed content (FOUC)”.\
It uses only what’s in localStorage (no network):

This ensures the exact same CSS URLs as last time are used immediately (usually from cache), eliminating flicker.\
The full ThemeManager will load/validate config after your app boots and keep everything in sync.

5) Vanilla Usage (no framework)

// main.ts
import { ThemeManager } from './theme.manager';

const theme = new ThemeManager();

await theme.init({
  // Pick one:
  configUrl: '/theme.config.json',
  // or embeddedScriptId: 'theme-config',
  // or config: { ... }
});

// Wire up your UI picker (example)
const select = document.getElementById('theme-select') as HTMLSelectElement;
for (const t of theme.getThemes()) {
  const opt = document.createElement('option');
  opt.value = t.id;
  opt.textContent = t.label;
  select.appendChild(opt);
}

select.value = theme.getActiveThemeId() || '';
select.addEventListener('change', () => theme.applyTheme(select.value));

// React to changes made in other tabs
theme.onChange((id) => {
  select.value = id;
});

HTML example:

6) Optional Angular Integration (PWA‑friendly)

Angular Service (wrapper)

// theme.service.ts
import { Injectable, Inject } from '@angular/core';
import { ThemeManager } from './theme.manager';
import { ThemeConfig } from './theme.types';

@Injectable({ providedIn: 'root' })
export class ThemeService {
  private manager = new ThemeManager();

  async initFromUrl(configUrl: string) {
    await this.manager.init({ configUrl });
  }

  async initFromScript(scriptId: string) {
    await this.manager.init({ embeddedScriptId: scriptId });
  }

  async initFromConfig(config: ThemeConfig) {
    await this.manager.init({ config });
  }

  themes() { return this.manager.getThemes(); }
  activeId() { return this.manager.getActiveThemeId(); }
  onChange(cb: (id: string) => void) { return this.manager.onChange(cb); }
  set(id: string) { return this.manager.applyTheme(id); }
}

Ensure config loads before first component renders

// app.config.ts (Angular standalone) or app.module.ts providers
import { APP_INITIALIZER, Provider } from '@angular/core';
import { ThemeService } from './theme.service';

export function initTheme(theme: ThemeService) {
  return () => theme.initFromUrl('/theme.config.json'); // or initFromScript('theme-config')
}

export const THEME_INIT_PROVIDER: Provider = {
  provide: APP_INITIALIZER,
  multi: true,
  useFactory: initTheme,
  deps: [ThemeService]
};

Add THEME_INIT_PROVIDER to your bootstrap providers.

Simple Angular Picker Component

// theme-picker.component.ts
import { Component, OnDestroy, OnInit } from '@angular/core';
import { ThemeService } from './theme.service';

@Component({
  selector: 'app-theme-picker',
  template: `
    <label>
      Theme
      <select [value]="activeId" (change)="onSelect($any($event.target).value)">
        <option *ngFor="let t of themes" [value]="t.id">{{ t.label }}</option>
      </select>
    </label>
  `
})
export class ThemePickerComponent implements OnInit, OnDestroy {
  themes: { id: string; label: string; mode: 'light'|'dark' }[] = [];
  activeId = '';
  private unsub: () => void = () => {};

  constructor(private theme: ThemeService) {}

  ngOnInit() {
    this.themes = this.theme.themes() as any;
    this.activeId = this.theme.activeId() || '';
    this.unsub = this.theme.onChange(id => this.activeId = id);
  }

  ngOnDestroy() { this.unsub(); }

  onSelect(id: string) { this.theme.set(id); }
}

Angular Service Worker (offline) caching of theme CSS

In ngsw-config.json, add your theme assets so they’re available offline:

{
  "assetGroups": [
    {
      "name": "app",
      "installMode": "prefetch",
      "resources": {
        "files": [
          "/index.html",
          "/*.css",
          "/*.js",
          "/theme.config.json",
          "/themes/**"
        ]
      }
    }
  ]
}

Rebuild with ng add @angular/pwa if you haven’t, then deploy.\
Now PWAs work offline and theme CSS stays cached.

7) Non‑Angular PWA (Workbox) hint

If you use Workbox:

// sw.js (simplified)
workbox.routing.registerRoute(
  ({url}) => url.pathname.startsWith('/themes/'),
  new workbox.strategies.StaleWhileRevalidate({
    cacheName: 'theme-css',
    plugins: [
      new workbox.expiration.ExpirationPlugin({ maxEntries: 30, purgeOnQuotaError: true })
    ]
  })
);

workbox.routing.registerRoute(
  ({url}) => url.pathname === '/theme.config.json',
  new workbox.strategies.NetworkFirst({ cacheName: 'theme-config' })
);

8) Design Notes vs Requirements

Light & Dark: ThemeEntry.mode ensures both are supported.
≥3 themes: Config supports any number; example shows 3.
Prebuilt + app colors: Use css + optional colors/colorsDark.
Runtime switching: applyTheme(id) dynamically swaps stylesheets (preload → promote).
Cross‑tab persistence: localStorage + BroadcastChannel.
Reusable, minimal, neutral: One core class, no UI opinions.
No flicker: Early‑boot snippet + preloading + seamless swap.
SPA & PWA: Works with any SPA; SW examples for offline; Angular APP_INITIALIZER.
Adjustable post‑deploy: Load /theme.config.json or editable inline JSON script.
Local/CDN: URLs are free-form; optional integrity + crossorigin.
No redundant reloads: Skips if same theme/URLs are active.
Core separated from UI: Manager has no UI; simple examples for any framework.
Startup config before rendering: Angular APP_INITIALIZER, or call init() before bootstrapping; plus early‑boot snippet ensures visual consistency even before init completes.

9) CSS authoring tips (optional but helpful)

Define CSS variables in your prebuilt theme files, and scope app styles to :root or [data-theme="id"] for per‑theme overrides.
To suppress transition “flashes” during theme switch, you may temporarily disable transitions while swapping:

/* Disable transitions during theme change (optional) */
html.theme-switching * { transition: none !important; }

And briefly add/remove that class around applyTheme if you like.

10) Security with CDN (SRI)

When hosting styles on a CDN, add Subresource Integrity (integrity) and, if needed, crossorigin: "anonymous" in the theme config. ThemeManager will place these attributes on the <link> elements.

11) Testing Checklist

[ ] Switching themes updates <html data-theme> and meta color-scheme
[ ] No stylesheet reload when reselecting current theme
[ ] Cross-tab/theme persists instantly
[ ] Offline usage still loads previously used theme (via early-boot + SW cache)
[ ] Config edits (file replaced) change available themes/order without rebuild
[ ] CDN-hosted themes load with SRI/CORS
[ ] Angular boot waits for config (APP_INITIALIZER)
[ ] No flash/flicker on startup and on theme switch

12) Next steps

If you’d like, tell me:

Do you prefer inline JSON or a separate /theme.config.json file?
Which prebuilt theme(s) and app color files do you plan to use?
Should I generate a ready-to-drop Angular demo (module + component + config), or a plain TS+Vite starter?

I can tailor the code scaffolding to your stack and deliver a small sample repo layout.

Analysis

I have crafted one from scratch based on the same functional requirements and technical requirements, conforming to my design principles for UI, UX and Developer Experience:

Web Theme Loader in TypeScript with Minimum API Surface

Comparing with my hand-crafted sourcecode, this one generated is much more complex, while I haven't tested if the sourcecode can be built successfully and executed properly.

And comparing with "Use Windows Copilot to Craft Web Theme Loader", the requirements has one more technical requirement:

The config settings must be loaded during app startup before any component is rendered.

And the high level requirement "The implementation may provide friendly integrations for Angular or React" has been changed to "The implementation may provide friendly integrations for Angular".

Both AI code generators have defined class ThemeManager to contain the core algorithm. Windows Copilot crafted 162 lines, and M365 Copilot crafted 327 lines with overall more complex design.

Despite the technical requirement "The config settings must be loaded during app startup before any component is rendered", M365 Copilot still use JSON for config, obviously don't understand that the implicit technical context: a JSON file is inherently loaded asynchronously, and only JSON object in JavaScript can be loaded synchronously so to become the startup settings of the Web app.

I realize that the prompt presented by the requirements does not explicitly state the need for the config to be loaded as JSON object in JavaScript referenced in index.html.

As an experienced developer, when writing codes, I have many implicit contexts in my mind, and have muscle memory of writing codes according to contents and contexts explicit and implicit, along with many background knowledge in mind or in subconscious.

Often only when writing codes, many more prompts could be popping up from my mind. Without writing codes, I could write very little prompts, mostly based on explicit knowledge and visual hints. If I have to write sufficient prompts for the AI code generator to write quality code, my time spent on writing the prompt may be longer than hand-crafting code.

Nevertheless, I will be looking forward to trying again with some dedicated AI code generators, like Claude.AI.

Use Windows Copilot to Craft Web Theme Loader

fonlow — Tue, 17 Feb 2026 09:20:16 +0000

Use Windows Copilot to Craft Web Theme Loader

I have crafted a Web theme loader from scratch based on specific functional requirements and technical requirements below, conforming to my design principles for UI, UX and Developer Experience. Please check: "Web Theme Loader in TypeScript with Minimum API Surface".

Requirements

User Story

As a web app user, I want to choose from multiple available themes — sometimes light, other times dark.

Work Order

Functional Requirements

Support both light and dark themes.
Support more than two themes — at least three themes must be available.
Support commonly used prebuilt themes, optionally combined with an app‑specific color stylesheet such as colors.css, with an optional dark‑mode variant like colors-dark.css.
Support dynamic switching between themes at runtime.
When the same web app/site is opened in another browser tab, the explicitly selected theme should be preserved and applied.

Technical Requirements

Reusable across multiple applications.
Minimal API surface to ensure easy customization and easy usage.
Neutral with respect to specific UI design choices.
Must be efficient and avoid visual flicker during startup and theme switching.
Usable in both SPA and PWA.
Fully functional in PWAs, offline usage, and intranet environments.
Adjustable after build, bundling, and deployment. For example, an admin should be able to change the number and order of available themes, and modify app‑specific color files.
Themes may be hosted locally or on a CDN.
Selecting a theme that is already loaded should not trigger a reload of the theme.
Core theme management must be separated from the theme‑picker UI.

Using the requirements as prompt, I asked Windows Copilot to generate sourcecode, and the following is the result.

Designing TS API

I need to design a minimal but complete TypeScript API with helpers. It should include core components like ThemeManager, storage, config, CSS loading, and eventing. I’ll also add optional Angular/React hooks. I must ensure no flicker, using an inline bootstrap script example. Admins should be able to adjust config after deployment via JSON or data-attributes. Multi-tab sync via storage events is necessary, and I’ll avoid reloads if already active. I’ll structure it with an overview, core types, ThemeRegistry, persistence, runtime config, and integration snippets. Keeping it concise but detailed.

You’re basically asking for a small, framework‑agnostic theming kernel that can be dropped into any app, with optional Angular/React sugar. Let’s design it as:

A core TypeScript API (ThemeManager) that:
- Knows about themes and their CSS files (prebuilt + app‑specific).
- Loads/unloads CSS at runtime without flicker.
- Persists selection (localStorage) and syncs across tabs.
A runtime‑configurable registry so admins can change themes after deployment.
Optional UI bindings for Angular/React that just talk to the core.

1. Core types and configuration

// theme-types.ts
export type ThemeId = string;

export interface ThemeCssFile {
  /** Absolute or relative URL; can be CDN or local */
  href: string;
  /** Optional media attribute, e.g. "(prefers-color-scheme: dark)" */
  media?: string;
  /** Optional integrity / crossorigin if you want CSP/CDN hardening */
  integrity?: string;
  crossOrigin?: '' | 'anonymous' | 'use-credentials';
}

export interface ThemeDefinition {
  id: ThemeId;
  /** Human-friendly label for pickers */
  label: string;
  /** Optional semantic tag: 'light' | 'dark' | 'high-contrast' | etc. */
  kind?: 'light' | 'dark' | 'other';
  /** One or more CSS files that together define this theme */
  cssFiles: ThemeCssFile[];
}

export interface ThemeManagerOptions {
  /** Storage key for persistence */
  storageKey?: string;
  /** Optional default theme id if nothing is stored */
  defaultThemeId?: ThemeId;
  /** Optional callback when theme changes */
  onThemeChange?: (theme: ThemeDefinition) => void;
  /** Optional attribute on <html> or <body> for styling hooks */
  htmlAttributeName?: string; // e.g. "data-theme"
  /** Where to attach <link> tags; defaults to document.head */
  linkParent?: HTMLElement;
}

2. Core ThemeManager implementation

Key goals:

No flicker: we keep previous theme until new CSS is loaded, then swap.
No redundant reload: selecting the active theme is a no‑op.
Multi‑tab sync: use storage event.
Runtime adjustable: registry can be replaced or extended at any time.

// theme-manager.ts
import {
  ThemeDefinition,
  ThemeId,
  ThemeManagerOptions,
  ThemeCssFile,
} from './theme-types';

export class ThemeManager {
  private themes: Map<ThemeId, ThemeDefinition> = new Map();
  private options: Required<ThemeManagerOptions>;
  private currentThemeId: ThemeId | null = null;
  private linkElements: Map<string, HTMLLinkElement> = new Map(); // key: href

  constructor(
    initialThemes: ThemeDefinition[] = [],
    options: ThemeManagerOptions = {}
  ) {
    this.options = {
      storageKey: options.storageKey ?? 'app.theme',
      defaultThemeId: options.defaultThemeId ?? (initialThemes[0]?.id ?? ''),
      onThemeChange: options.onThemeChange ?? (() => {}),
      htmlAttributeName: options.htmlAttributeName ?? 'data-theme',
      linkParent: options.linkParent ?? document.head,
    };

    initialThemes.forEach(t => this.themes.set(t.id, t));

    this.handleStorageEvent = this.handleStorageEvent.bind(this);
    window.addEventListener('storage', this.handleStorageEvent);

    const stored = this.getStoredThemeId();
    const initialId = stored || this.options.defaultThemeId;
    if (initialId && this.themes.has(initialId)) {
      void this.applyTheme(initialId, { persist: false });
    }
  }

  /** Clean up listeners if needed */
  dispose(): void {
    window.removeEventListener('storage', this.handleStorageEvent);
  }

  /** Replace all themes at runtime (e.g. admin updates config JSON) */
  setThemes(themes: ThemeDefinition[]): void {
    this.themes.clear();
    themes.forEach(t => this.themes.set(t.id, t));
    // Keep current theme if still present; otherwise fall back
    if (!this.currentThemeId || !this.themes.has(this.currentThemeId)) {
      const fallback = this.options.defaultThemeId || themes[0]?.id;
      if (fallback) {
        void this.applyTheme(fallback);
      }
    }
  }

  /** Add or update a single theme at runtime */
  upsertTheme(theme: ThemeDefinition): void {
    this.themes.set(theme.id, theme);
  }

  /** Remove a theme; if it's active, fallback to default */
  removeTheme(id: ThemeId): void {
    this.themes.delete(id);
    if (this.currentThemeId === id) {
      const fallback =
        this.options.defaultThemeId || Array.from(this.themes.keys())[0];
      if (fallback) {
        void this.applyTheme(fallback);
      }
    }
  }

  getAvailableThemes(): ThemeDefinition[] {
    return Array.from(this.themes.values());
  }

  getCurrentTheme(): ThemeDefinition | null {
    return this.currentThemeId ? this.themes.get(this.currentThemeId) ?? null : null;
  }

  async applyTheme(id: ThemeId, opts?: { persist?: boolean }): Promise<void> {
    if (id === this.currentThemeId) {
      // Requirement 9: selecting already loaded theme does nothing
      return;
    }
    const theme = this.themes.get(id);
    if (!theme) {
      throw new Error(`Unknown theme id: ${id}`);
    }

    // Load all CSS files for the new theme first
    await this.ensureCssFilesLoaded(theme.cssFiles);

    // Now "activate" the theme: update attribute, currentThemeId, storage, callback
    this.currentThemeId = id;
    this.setHtmlAttribute(theme);
    if (opts?.persist !== false) {
      this.storeThemeId(id);
    }
    this.options.onThemeChange(theme);
  }

  /** For SSR or early bootstrapping: just set attribute without loading CSS */
  setHtmlAttribute(theme: ThemeDefinition): void {
    const attr = this.options.htmlAttributeName;
    document.documentElement.setAttribute(attr, theme.id);
    if (theme.kind) {
      document.documentElement.setAttribute(`${attr}-kind`, theme.kind);
    }
  }

  private async ensureCssFilesLoaded(files: ThemeCssFile[]): Promise<void> {
    const parent = this.options.linkParent;
    const promises = files.map(file => {
      const existing = this.linkElements.get(file.href);
      if (existing) {
        // Already loaded; no need to reload
        return Promise.resolve();
      }
      const link = document.createElement('link');
      link.rel = 'stylesheet';
      link.href = file.href;
      if (file.media) link.media = file.media;
      if (file.integrity) link.integrity = file.integrity;
      if (file.crossOrigin !== undefined) link.crossOrigin = file.crossOrigin;

      const p = new Promise<void>((resolve, reject) => {
        link.onload = () => resolve();
        link.onerror = () => reject(new Error(`Failed to load CSS: ${file.href}`));
      });

      parent.appendChild(link);
      this.linkElements.set(file.href, link);
      return p;
    });

    await Promise.all(promises);
  }

  private getStoredThemeId(): ThemeId | null {
    try {
      return localStorage.getItem(this.options.storageKey) as ThemeId | null;
    } catch {
      return null;
    }
  }

  private storeThemeId(id: ThemeId): void {
    try {
      localStorage.setItem(this.options.storageKey, id);
    } catch {
      // ignore (offline/intranet with restricted storage)
    }
  }

  private handleStorageEvent(ev: StorageEvent): void {
    if (ev.key !== this.options.storageKey) return;
    const newId = ev.newValue as ThemeId | null;
    if (!newId || newId === this.currentThemeId) return;
    // Sync across tabs
    void this.applyTheme(newId, { persist: false });
  }
}

3. Example theme configuration (light/dark/extra + app colors)

You can host CSS locally or on a CDN. You can also split prebuilt theme vs app‑specific colors.

// theme-config.ts
import { ThemeDefinition } from './theme-types';

export const THEMES: ThemeDefinition[] = [
  {
    id: 'light-default',
    label: 'Light',
    kind: 'light',
    cssFiles: [
      // Prebuilt UI library theme (e.g. Angular Material, MUI, etc.)
      { href: '/assets/themes/material-light.css' },
      // App-specific colors
      { href: '/assets/colors.css' },
    ],
  },
  {
    id: 'dark-default',
    label: 'Dark',
    kind: 'dark',
    cssFiles: [
      { href: '/assets/themes/material-dark.css' },
      { href: '/assets/colors-dark.css' },
    ],
  },
  {
    id: 'solarized',
    label: 'Solarized',
    kind: 'other',
    cssFiles: [
      { href: 'https://cdn.example.com/themes/solarized.css' },
      { href: '/assets/colors-solarized.css' },
    ],
  },
];

Admins can change THEMES after deployment by:

Serving it as a JSON file (/theme-config.json) and fetching it at runtime.
Or embedding it in a <script type="application/json" id="theme-config"> tag that can be edited without rebuilding.

4. Using ThemeManager in a vanilla SPA/PWA

// main.ts
import { ThemeManager } from './theme-manager';
import { THEMES } from './theme-config';

export const themeManager = new ThemeManager(THEMES, {
  storageKey: 'myapp.theme',
  defaultThemeId: 'light-default',
  htmlAttributeName: 'data-theme',
  onThemeChange: theme => {
    console.log('Theme changed to', theme.id);
  },
});

// Example: wire to a simple select element
const select = document.getElementById('theme-select') as HTMLSelectElement | null;
if (select) {
  // Populate options
  themeManager.getAvailableThemes().forEach(t => {
    const opt = document.createElement('option');
    opt.value = t.id;
    opt.textContent = t.label;
    select.appendChild(opt);
  });

  const current = themeManager.getCurrentTheme();
  if (current) {
    select.value = current.id;
  }

  select.addEventListener('change', () => {
    void themeManager.applyTheme(select.value);
  });
}

This works in:

SPA: just import themeManager once.
PWA/offline/intranet: CSS files are local or cached by the service worker; localStorage works offline; no external dependencies required.

5. Avoiding flicker on first paint

To avoid a flash of wrong theme before JS runs, you can:

Store the last theme id in localStorage (already done by ThemeManager).
Add a tiny inline script in your HTML <head> that:
- Reads the stored theme id.
- Sets data-theme (and optionally injects a <link> for the base theme) before the page renders.

<!doctype html>
<html lang="en" data-theme="light-default">
  <head>
    <script>
      (function () {
        try {
          var key = 'myapp.theme';
          var id = localStorage.getItem(key);
          if (id) {
            document.documentElement.setAttribute('data-theme', id);
          }
        } catch (e) {
          // ignore
        }
      })();
    </script>
    <!-- Optionally preload the most common theme CSS -->
    <link rel="stylesheet" href="/assets/themes/material-light.css" />
    <link rel="stylesheet" href="/assets/colors.css" />
  </head>
  <body>
    <!-- app root -->
  </body>
</html>

The ThemeManager will later load any missing CSS files for the selected theme, but the attribute is already correct, so your CSS can avoid flicker (e.g. by scoping theme rules under [data-theme="dark-default"] etc.).

6. Optional Angular integration

A minimal Angular service that wraps the core:

// theme.service.ts
import { Injectable } from '@angular/core';
import { BehaviorSubject } from 'rxjs';
import { ThemeManager } from './theme-manager';
import { THEMES } from './theme-config';
import { ThemeDefinition } from './theme-types';

@Injectable({ providedIn: 'root' })
export class ThemeService {
  private manager = new ThemeManager(THEMES, {
    storageKey: 'myapp.theme',
    defaultThemeId: 'light-default',
    htmlAttributeName: 'data-theme',
    onThemeChange: theme => this._currentTheme.next(theme),
  });

  private _currentTheme = new BehaviorSubject<ThemeDefinition | null>(
    this.manager.getCurrentTheme()
  );
  currentTheme$ = this._currentTheme.asObservable();

  getAvailableThemes(): ThemeDefinition[] {
    return this.manager.getAvailableThemes();
  }

  setTheme(id: string): Promise<void> {
    return this.manager.applyTheme(id);
  }
}

Simple Angular component:

// theme-picker.component.ts
import { Component } from '@angular/core';
import { ThemeService } from './theme.service';

@Component({
  selector: 'app-theme-picker',
  template: `
    <label>
      Theme:
      <select [ngModel]="currentId" (ngModelChange)="onChange($event)">
        <option *ngFor="let t of themes" [value]="t.id">
          {{ t.label }}
        </option>
      </select>
    </label>
  `,
})
export class ThemePickerComponent {
  themes = this.themeService.getAvailableThemes();
  currentId = this.themeService.getAvailableThemes()[0]?.id;

  constructor(private themeService: ThemeService) {
    this.themeService.currentTheme$.subscribe(t => {
      if (t) this.currentId = t.id;
    });
  }

  onChange(id: string): void {
    void this.themeService.setTheme(id);
  }
}

7. Optional React integration

A small hook that talks to the same core:

// theme-context.tsx
import React, { createContext, useContext, useEffect, useState } from 'react';
import { ThemeManager } from './theme-manager';
import { THEMES } from './theme-config';
import { ThemeDefinition } from './theme-types';

const manager = new ThemeManager(THEMES, {
  storageKey: 'myapp.theme',
  defaultThemeId: 'light-default',
  htmlAttributeName: 'data-theme',
});

interface ThemeContextValue {
  themes: ThemeDefinition[];
  currentTheme: ThemeDefinition | null;
  setTheme: (id: string) => Promise<void>;
}

const ThemeContext = createContext<ThemeContextValue | undefined>(undefined);

export const ThemeProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
  const [currentTheme, setCurrentTheme] = useState<ThemeDefinition | null>(
    manager.getCurrentTheme()
  );

  useEffect(() => {
    const unsubscribe = (theme: ThemeDefinition) => setCurrentTheme(theme);
    // Patch onThemeChange dynamically
    (manager as any).options.onThemeChange = unsubscribe;
    return () => {
      (manager as any).options.onThemeChange = () => {};
    };
  }, []);

  const value: ThemeContextValue = {
    themes: manager.getAvailableThemes(),
    currentTheme,
    setTheme: (id: string) => manager.applyTheme(id),
  };

  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
};

export function useTheme(): ThemeContextValue {
  const ctx = useContext(ThemeContext);
  if (!ctx) throw new Error('useTheme must be used within ThemeProvider');
  return ctx;
}

Example React picker:

// ThemePicker.tsx
import React from 'react';
import { useTheme } from './theme-context';

export const ThemePicker: React.FC = () => {
  const { themes, currentTheme, setTheme } = useTheme();

  return (
    <label>
      Theme:
      <select
        value={currentTheme?.id ?? ''}
        onChange={e => void setTheme(e.target.value)}
      >
        {themes.map(t => (
          <option key={t.id} value={t.id}>
            {t.label}
          </option>
        ))}
      </select>
    </label>
  );
};

If you want, we can next:

Add a JSON‑driven config loader for admins (/theme-config.json).
Sketch a CSS pattern for [data-theme] that plays nicely with Angular Material or other libraries.

Analysis

Comparing with my hand-crafted one, this one generated is much more complex, while I haven't tested if the sourcecode can be built successfully and executed properly.

And the configuration is stored in a JSON file which can be loaded only asynchronously, while for the sake of theme, the config had better be loaded synchronously during startup.

I realize that the prompt presented by the requirements does not explicitly state the need for the config to be loaded as early as possible.

Often only when writing codes, many more prompts could be popping up from my mind. Without writing codes, I can write very little prompts, mostly based on explicit knowledge and visual hints.

Nevertheless, I will add a few more technical requirements when I prompt M365 Copilot to craft code.

Web Theme Loader in TypeScript with Minimum API Surface

fonlow — Mon, 16 Feb 2026 07:31:04 +0000

You can use this simple, powerful and flexible Web theme loader in your Web app especially SPA+PWA to realize similar UX as seen in these prominent sites:

Web Sites and Apps that Use This ThemeLoader

Summary

The Web theme loader API exposes 3 contracts:

static init() of themeLoader to be called during app startup.
static loadTheme(picked: string | null, appColorsDir?: string | null) to be called when the app user picks one from available themes.
static get selectedTheme(): string | null of themeLoader to give the URL of the selected theme, so GUI may display which theme is in-use.

Because the theme should be loaded at startup before the Web app rendering, the respective config must be loaded synchronously ASAP.

The GUI of theme selection is independent of the Web theme loader API. For example, in addition to Select and Menu for multiple themes, you may use Switch for switching between light and dark.

Remarks:

Modern browsers like Chrome, Edge, Safari, and Firefox support a built-in concept of light/dark preference. Depending on your UX design, if you would not provide UI component for changing theme, then CSS only solution works well:

<link rel="stylesheet" href="my-light.css" media="(prefers-color-scheme: light)">
<link rel="stylesheet" href="my-dark.css" media="(prefers-color-scheme: dark)">

Installation

Install theme-loader-api:

npm install theme-loader-api

Integration

Call ThemeLoader.loadTheme() before the bootstrap of the Web app.
In the UI component presenting the theme picker, convert the themes dictionary to an array which will be used to present the list. And call ThemeLoader.loadTheme() when the picker picks a theme.
Prepare siteconfig.js and add <script src="conf/siteconfig.js"></script> to index.html if you want flexibility after build and deployment. Or, simply provide constant SITE_CONFIG in app code.

Angular Example

main.ts

ThemeLoader.init();
bootstrapApplication(AppComponent, appConfig);

theme-select.component.ts

    constructor() {
        this.themes = AppConfigConstants.themesDic ? Object.keys(AppConfigConstants.themesDic).map(k => {
            const c = AppConfigConstants.themesDic![k];
            const obj: ThemeDef = {
                display: c.display,
                filePath: k,
                dark: c.dark
            };
            return obj;
        }) : undefined;
    }

    themeSelectionChang(e: MatSelectChange) {
        ThemeLoader.loadTheme(e.value);
    }

theme-select.component.html

<mat-select #themeSelect (selectionChange)="themeSelectionChang($event)" [value]="currentTheme">
    @for (item of themes; track $index) {
    <mat-option [value]="item.filePath">{{item.display}}</mat-option>
    }
</mat-select>

siteconfig.js

const THEME_CONFIG = {
    themesDic: {
        "assets/themes/azure-blue.css": { display: "Azure & Blue", dark: false },
        "assets/themes/rose-red.css": { display: "Roes & Red", dark: false },
        "assets/themes/magenta-violet.css": { display: "Magenta & Violet", dark: true },
        "assets/themes/cyan-orange.css": { display: "Cyan & Orange", dark: true }
    },
    themeLoaderSettings: {
        storageKey: 'app.theme',
        themeLinkId: 'theme',
        appColorsDir: 'conf/',
        appColorsLinkId: 'app-colors',
        colorsCss: 'colors.css',
        colorsDarkCss: 'colors-dark.css'
    }
}

index.html

    <script src="conf/siteconfig.js"></script>
</head>

React Example

index.tsx

ThemeLoader.init();

const root = ReactDOM.createRoot(
  document.getElementById('root') as HTMLElement
);
root.render(...

Home.tsx

    const themes = AppConfigConstants.themesDic ? Object.keys(AppConfigConstants.themesDic).map(k => {
        const c = AppConfigConstants.themesDic![k];
        const obj: ThemeDef = {
            display: c.display,
            filePath: k,
            dark: c.dark
        };
        return obj;
    }) : undefined;

    const [currentTheme, setCurrentTheme] = useState(() => ThemeLoader.selectedTheme ?? undefined);
    const handleChange = (event: React.ChangeEvent<HTMLSelectElement>) => {
        const v = event.target.value;
        setCurrentTheme(v);
        ThemeLoader.loadTheme(v);
    };

    return (
        <>
            <h1>React Heroes!</h1>
            <div>
                <label htmlFor="theme-select">Themes </label>
                <select
                    id="theme-select"
                    value={currentTheme ?? ""}
                    onChange={handleChange}
                >
                    {themes?.map((item) => (
                        <option key={item.filePath} value={item.filePath}>
                            {item.display}
                        </option>
                    ))}
                </select>
            </div>

siteconfig.js

const THEME_CONFIG = {
    themesDic: {
        "assets/themes/light-theme.css": { display: "Light", dark: false },
        "assets/themes/dark-theme.css": { display: "Dark", dark: true },
        "assets/themes/pink-theme.css": { display: "Pink", dark: false }
    },
    themeLoaderSettings: {
        storageKey: 'app.theme',
        themeLinkId: 'theme',
        appColorsDir: 'conf/',
        appColorsLinkId: 'app-colors',
        colorsCss: 'colors.css',
        colorsDarkCss: 'colors-dark.css'
    }
}

index.html

    <script src="conf/siteconfig.js"></script>
</head>

Respect prefers-color-scheme

By default, this API will pick the first available theme in the dictionary during the first startup of the Web app, and use last pick afterward. If you want to respect prefers-color-scheme during the initial load of the Web app, you may use the following in the app's bootstrap:

const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
var r = findFirstTheme(isDark);
if (r) {
    ThemeLoader.loadTheme(r.filePath);
}

platformBrowser().bootstrapModule(AppModule, { applicationProviders: [provideZoneChangeDetection()], })
    .catch(err => console.error(err));

function findFirstTheme(dark: boolean): { filePath: string; theme: ThemeValue } | undefined {
    const entry = Object.entries(ThemeConfigConstants.themesDic!).find(
        ([, theme]) => theme.dark === dark
    );

    return entry ? { filePath: entry[0], theme: entry[1] } : undefined;
}

How About I18N and L10N?

The only things need to be translated is the display name of each theme.

Solution 1: No need for I18N and Use Icon To Represent Theme Impression

You may extend interface ThemeDef, and make it contain some meta info of generating SVG icons presenting respective theme. And the icons will be inline with the HTML template. Angular Material Components site uses this approach.

Or you may just hand-draw some SVG icons and linked them in the HTML template.

Solution 2: Create Dictionary in App Code

Depending the framework like Angular or the library like React, there could be a few ways to create a dictionary to lookup translations and create translations.

Solution 3: Post Build Processing

If you are using siteconfig.js, the JS file should not be included in the hash tables of the service worker for automatic app update.

In Angular, each locale has its own build, therefore, you may craft some post build script to inject the translated names into the siteconfig.js of each build.

WebApiClientGen vs Kiota regarding ASP.NET backend + Angular Frontend

fonlow — Sat, 22 Nov 2025 08:00:30 +0000

Introduction

When building modern applications with an ASP.NET Core backend and an Angular frontend, one recurring challenge is how to generate strongly typed client APIs. Developers want to avoid repetitive boilerplate, ensure type safety, and keep backend and frontend models in sync. Two tools often considered are WebApiClientGen and Kiota. While both aim to simplify client generation, they differ fundamentally in approach and fit.

WebApiClientGen: A Component Set for Native Angular Integration

WebApiClientGen is a modular toolkit that generates C# and TypeScript client APIs directly from ASP.NET Core Web API controllers — without requiring Swagger/OpenAPI.

Key Features

C# client generation for .NET, Xamarin.Forms, MAUI, Blazor.
TypeScript client generation for Angular, Aurelia, Axios, Fetch API, jQuery.
POCO → TypeScript conversion for schema fidelity.
Angular-native clients that use Angular’s HttpClient and RxJS observables.
No Swagger/OpenAPI dependency — leverages runtime type info.

Why It Fits Angular Developers

Generated Angular services plug directly into Angular’s DI system.
Methods return Observable<T>, aligning with Angular’s async patterns.
Eliminates manual HTTP boilerplate.
Ideal for teams following a Code First approach in ASP.NET Core.

Kiota: An OpenAPI-Based Generator

Kiota, developed by Microsoft, generates strongly typed clients from OpenAPI specifications. It supports multiple languages, including TypeScript, C#, Java, Python, and Go.

Key Features

OpenAPI-driven: requires a Swagger/OpenAPI definition.
Framework-agnostic TypeScript clients using Fetch API by default.
Pluggable request adapters (Fetch, Node.js).
Broad language support beyond C# and TypeScript.

Limitations for Angular Developers

No native Angular HttpClient integration.
Generated TypeScript clients use Fetch promises, not RxJS observables.
Requires maintaining OpenAPI specs, adding overhead for Code First projects.
Angular integration possible only via custom adapters or wrappers.

Side-by-Side Comparison

Feature	WebApiClientGen	Kiota
Input	ASP.NET Core controllers (runtime types)	OpenAPI/Swagger spec required
C# client generation	✅ Yes	✅ Yes
TypeScript client generation	✅ Yes (Angular, Aurelia, Axios, Fetch, jQuery)	✅ Yes (Fetch API, Node.js)
Angular HttpClient support	✅ Native, RxJS Observables	❌ Not supported (Fetch only)
Swagger/OpenAPI dependency	❌ None	✅ Required
POCO → TypeScript conversion	✅ Built-in	❌ Not available
Best fit	ASP.NET + Angular (Code First)	Multi-language SDKs (OpenAPI)

Recommendation for ASP.NET + Angular Developers

If your stack is ASP.NET Core backend + Angular frontend, and you want native Angular HttpClient integration without Swagger/OpenAPI, the most appropriate choice is:

WebApiClientGen Component Set

Use WebApiClientGenCore to generate C# clients for backend consumers.
Use the Angular TypeScript plugin to generate Angular services with HttpClient + RxJS.
Use POCO2TS to keep your TypeScript interfaces aligned with backend models.
Run the provided test harnesses to validate serializer fidelity and frontend integration.

Kiota is powerful if you need multi-language SDKs from OpenAPI specs (e.g., distributing APIs to external developers in Java, Python, Go). But for internal Angular + ASP.NET projects, WebApiClientGen offers a more direct, developer-friendly pipeline.

Conclusion

For an application developer building ASP.NET Core + Angular solutions, the choice is clear:

WebApiClientGen provides a component set tailored for Angular, delivering native HttpClient services, RxJS observables, and schema fidelity — all without Swagger/OpenAPI.
Kiota shines in broader OpenAPI ecosystems but requires extra work to fit Angular naturally.

By adopting WebApiClientGen, you streamline your workflow, reduce boilerplate, and ensure type safety across backend and frontend — exactly what modern full-stack teams need.

Using WebApiClientGen in ASP.NET Core + Angular

1. Install the NuGet Packages

On your ASP.NET Core Web API project, add the required packages:

dotnet add package Fonlow.WebApiClientGenCore
dotnet add package WebApiClientGenCore.NG2
or
dotnet add package WebApiClientGenCore.NG2FormGroup

WebApiClientGenCore → generates C# client APIs and host plugins.
WebApiClientGenCore.NG2FormGroup → generates TypeScript codes support native HttpClient and FormGroup with validations.

For more details, please check "Generate Typed FormGroup of Angular Reactive Forms with ASP.NET Core Web API"

Migrate from Material Icons to Material Symbols

fonlow — Tue, 28 Oct 2025 00:11:20 +0000

Since 2016, I have developed a few complex business applications with frontend on Angular and Angular Material Components. Event though Angular Material Components Suite is still primarily utilizing Material Icons, the suite is working well with Material Symbols.

I would typically host the icons/symbols in the same host with the SPA codes, rather than having references to CDN. In fact, one of my apps can work well offline totally without the Internet even during the first launch.

Import Material Symbols package

In package.json:

Remove "@fontsource/material-icons-outlined" or alike.
Add "@fontsource/material-symbols-outlined"
Run npm i

Remove locally hosted material icons from the assets folder.

I had typically "src/assets/material-icons" to contain what copied from "node_modules/@fontsource/material-icons-outlined".

Because the architectural design of material symbols is different from material icons, such folder is not needed under "assets". Instead, "ng build" will generate folder "media" under app root to contain the artifacts of material symbols.

Remove the reference to material icons in index.html

    <link rel="stylesheet" type="text/css" href="assets/icons/material-icons/index.css" />

This line should be removed.

Tell Angular app to use material symbols

In app.component.ts, add the following in the constructor:

private iconRegistry: MatIconRegistry){
iconRegistry.setDefaultFontSetClass('material-symbols-outlined');

Import Material Symbols to app build

In global stylesheet styles.css, add the following:

@import "@fontsource/material-symbols-outlined/400.css";

.mat-icon.material-symbols-outlined {
  vertical-align: middle;
  line-height: 1;
}

.material-symbols-outlined {
    font-family: 'Material Symbols Outlined';
    font-size: 24px;
    font-variation-settings: 'FILL' 1, 'wght' 400, 'GRAD' 0, 'opsz' 48;
}

Material Symbols (material-symbols-outlined) use different font metrics compared to the older Material Icons. They often have more baseline padding and vertical centering assumptions that don’t play well with mat-button-toggle, which uses inline-flex and align-items: center by default.
In mat-button-toggle, the icon is treated like text content, and the font's vertical metrics push it slightly downward compared to other components like mat-icon-button or mat-menu.

Therefore .mat-icon.material-symbols-outlined is important for the vertical alignment of material symbols appearing in some components like MatButtonTootle and suffix button in FormField etc.

Update for Angular Service Worker

In ngsw-config.json, under "assetGroups", add the following:

{
    "name": "Material Symbols",
    "installMode": "lazy",
    "updateMode": "lazy",
    "resources": {
        "files": [
            "/media/**"
        ]
    }
}

Run `ng build` and test

You will see folder "media" in root containing "material-symbols-outlined-latin-400-normal.woff2" in development build or "material-symbols-outlined-latin-400-normal-hash.woff2" in production build.

Tools and Demo Based on Existing .NET JSON Schema Components

fonlow — Thu, 22 May 2025 19:50:17 +0000

Tools and Demo Based on Existing .NET JSON Schema Components

While there are variety of JSON schema tools since the introduction of JSON schema, this project is focused on the following:

Existing .NET (Framework) components that can generate JSON schema from POCO classes or generate POCO classes from JSON Schema.
Introduce locally run tools.
Develop CLI tools for transforming POCO to JSON schema.
Compare with different components of generating JSON schema.

If a .NET developer who prefer code first approach, you would often create POCO classes first for various purposes, and generate meta data like XML schema, JSON schema, database schema, WSDL and Swagger/OpenAPI definition. The goal of these project is to find the "best" .NET component that can generate JSON schema from a complex POCO class, and the schema can make the hand-crafting of JSON data become convenient with a decent text editor like Visual Studio Code and alike, fully utilizing the data constraints defined in the data model.

Validation Tools

Visual Studio

References:

https://visualstudiomagazine.com/articles/2018/01/24/json-messages-schema.aspx

Visual Studio Code

References:

https://code.visualstudio.com/docs/languages/json

From Schema to C# Codes

Visual Studio

Go "Main Menu -> Edit -> Paste Special -> Paste JSON as Classes".

Generating Schema From C#

Plain Old Classes can provide enough info for XML schema and JSON schema. This open source project provides side by side comparisons of some popular components of generating schema from a POCO class.

JsonSchemaComponents provides 4 CLI tools utilizing 4 JSON schema components, so you can choose the right one after comparing their outputs.

GenerateJsonSchema.exe using .NET 9 Extract SChema

Usage:

GenerateJsonSchema.exe
Generate JSON Schema from a POCO class.
JSON Schema Generator  version 1.0
Fonlow (c) 2025


   /ClassName, /C      Class name including namespace, e.g., /C=My.Namespace.MyClass
   /ClassFile, /CF     Class file path in C# or VB.NET, e.g., /CF=c:/myCsharpClass.cs
   /AssemblyFile, /A   Assembly file name including file extension. e.g., /A=abc.dll
   /OutputPath, /OP    File path of the JSON schema output. e.g., /OP=c:/temp/MyJsonSchema.json
   /Title, /T          Title of schema. e.g., /t='CodeGen meta of WebApiClientGen'
   /Description, /D    Description of schema. e.g., /d 'Post to CodeGen controller of Web API'
   /Help, /h, /?       Shows this help text

Example:

GenerateJsonSchema.exe /op=c:/temp/demoSchema.json /c=Fonlow.CodeDom.Web.CodeGenSettings /a=DataModels.dll

Hints:

The other CLI apps have the same set of arguments.

GenerateSchemaWithNJsonSchema.exe using NJsonSchema

GenerateSchemaWithNewtonSoft.exe using NewtonSoft.Json

Online validator on: https://www.jsonschemavalidator.net/ which can validate draft v3 to 2020-12.

GenerateSchemaWithJsonSchemaNet.exe using JSON Everything

Online validator on: https://json-everything.net/json-schema for Draft 6 to 2020-12

Comparison of .NET Components of Generating JSON schema from POCO.

The JSON data is CodeGen.json that is the CodeGen definition of WebApiClientGen, and the schemas are those generated by various .NET components.

The POCO classes are defined in DataModels/Models.cs:

...
    public class CodeGenSettingsBase
    {
        [Required]
        [JsonRequired]
        [Description("Cherry picking of data models and API controllers.")]
        public required CodeGenConfig ApiSelections { get; set; }
    }

    /// <summary>
    /// What CodeGenController is expecting 
    /// </summary>
    public class CodeGenSettings : CodeGenSettingsBase
    {
        [Required]
        [JsonRequired]
        [Description("Options of output")]
        public required CodeGenOutputs ClientApiOutputs { get; set; }
    }

    /// <summary>
    /// For cherry picking APIs and data models 
    /// </summary>
    public class CodeGenConfig
    {
        /// <summary>
        /// To exclude some controllers. For example, [My.Namespace.Home, My.Namespace.FileUpload] for My.Namespace.HomeController and My.Namespace.FileUploadController.
        /// </summary>
        public string[] ExcludedControllerNames { get; set; }

        string[] dataModelAssemblyNames;

        /// <summary>
        /// To include assemblies containing data models. Assembly names should be without file extension. 
        /// An assembly should appear in either DataModelAssemblyNames or DataModels, not both.
        /// If the Web API assembly is also included, it should be behind those data model assemblies that it depends on.
        /// </summary>
        [Description("Exclusive to DataModels.")]
        public string[] DataModelAssemblyNames
        {
            get { return dataModelAssemblyNames; }
            set
            {
                dataModelAssemblyNames = value;
                AllDataModelAssemblyNames = this.GetAllDataModelAssemblyNames();
            }
        }

        DataModel[] dataModels;
...

The comparison is done through the following:

The JSOn file has a reference to the schema file, and display and edit the JSON data in Visual Studio Code
Online validator on: https://www.jsonschemavalidator.net/
Online validator on: https://jsonschema.dev/

.NET 9 Extract SChema

{
  "type": [
    "object",
    "null"
  ],
  "properties": {
    "ClientApiOutputs": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "ClientLibraryProjectFolderName": {
          "type": [
            "string",
            "null"
          ]
        },
        "FileName": {
          "type": [
            "string",
            "null"
          ]
        },
        "GenerateBothAsyncAndSync": {
          "type": "boolean"
        },

By default:

All string fields are nullable and can be absent, unless required.
All value type fields can be absent and must have a value, unless nullable, unless required.

Nullable Value Type

        "StringAsString": {
          "type": "boolean"
        },
        "CamelCase": {
          "type": [
            "boolean",
            "null"
          ]
        },

For Required Field

It honours JsonRequiredAttribute of .NET, and create the following:

            "properties": {
              "AssemblyName": {
                "type": [
                  "string",
                  "null"
                ]
              },

            },
            "required": [
              "AssemblyName"
            ]

Remarks:

Visual Studio Code does not care about the missing required field.
Visual Studio cares and enforces. For new entry, only after inputting the required fields, the optional fields will appear in intellisense.
https://www.jsonschemavalidator.net/ pick the missing field.

For Enum Field

              "CherryPickingMethods": {
                "type": [
                  "integer",
                  "null"
                ]
              },

Overall it is good.

NJsonSchema

It declares schema version and a default title. And both VS and VS Code are not working well with the draft-04 schema, keeping saying whatever property not allowed.

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "CodeGen Meta of WebApiClientGen",
  "description": "POST to CodeGen controller",
  "definitions": {
    "CodeGenOutputs": {
      "allOf": [
        {
          "$ref": "#/definitions/ModelGenOutputs"
        },
        {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "ClientLibraryProjectFolderName": {
              "type": [
                "null",
                "string"
              ]
            },
            "FileName": {
              "type": [
                "null",
                "string"
              ]
            },
            "GenerateBothAsyncAndSync": {
              "type": [
                "boolean",
                "null"
              ]
            },

For Required Field

It respects RequiredAttribute but not others like JsonRequiredAttribute.

For Enum fields

    "CherryPickingMethods": {
      "type": "integer",
      "description": "",
      "x-enumFlags": true,
      "x-enumNames": [
        "All",
        "DataContract",
        "NewtonsoftJson",
        "Serializable",
        "AspNet",
        "NetCore",
        "ApiOnly"
      ],
      "enum": [
        0,
        1,
        2,
        4,
        8,
        16,
        32
      ]
    }

While there is "x-enumFlags": true as mentioned on flagged enum (bitwise), JSON Schema standard body apparently hasn't reach and aggrement, according to https://github.com/json-schema-org/json-schema-vocabularies/issues/24. Not sure which editor will respect this?

Nullable boolean and Alike

            "StringAsString": {
              "type": "boolean"
            },
            "CamelCase": {
              "type": [
                "boolean",
                "null"
              ]
            },

NewtonSoft.Json

{
  "title": "CodeGen Meta of WebApiClientGen",
  "description": "POST to CodeGen controller",
  "definitions": {
    "CodeGenConfig": {
      "description": "Cherry picking of data models and API controllers.",
      "type": "object",
      "properties": {
        "ExcludedControllerNames": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "DataModelAssemblyNames": {
          "description": "Exclusive to DataModels.",
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "DataModels": {
          "description": "Exclusive to DataModelAssemblyNames",
          "type": [
            "array",
            "null"
          ],
          "items": {
            "$ref": "#/definitions/DataModel"
          }
        },

Therefore:

https://www.jsonschemavalidator.net/ reports 5 errors
https://jsonschema.dev/ reports 26 errors, however, this validator is "The home of JSON Schema validation right in your browser 🚧 Alpha 🚧 draft-7 only"

For Required Field

It honours JsonRequiredAttribute and RequiredAttribute, but not DataMember(IsRequired = true) and not the required keyword, and generate the following:

        "AssemblyName": {
          "type": "string"
        },

Remarks:

In Visual Studio Code, giving it null the editor won't complain.
Visual Studio can pick the invalid null value.
https://www.jsonschemavalidator.net/ pick the missing field, and the invalid null value.

However, all other sibling fields are required by default:

      "required": [
        "AssemblyName",
        "TargetDir",
        "TSFile",
        "ContentType",
        "AsModule",
        "ClientNamespaceSuffix",
        "ContainerNameSuffix",
        "DataAnnotationsToComments",
        "HelpStrictMode",
        "NgDateOnlyFormControlEnabled"
      ]

To avoid, need to do this:

JSchemaGenerator generator = new JSchemaGenerator();
generator.DefaultRequired = Required.Default;

For enum field

        "CherryPickingMethods": {
          "type": [
            "integer",
            "null"
          ]
        },

Nullable boolean and Alike

        "StringAsString": {
          "type": "boolean"
        },
        "CamelCase": {
          "type": [
            "boolean",
            "null"
          ]
        },

JSON Everything

Online validator on: https://jsonschema.net/

{
  "title": "CodeGen Meta of WebApiClientGen",
  "description": "POST to CodeGen controller",
  "type": "object",
  "properties": {
    "ApiSelections": {
      "type": "object",
      "properties": {
        "ExcludedControllerNames": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string"
          }
        },
        "DataModelAssemblyNames": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string"
          }
        },
        "DataModels": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "object",
            "properties": {
              "AssemblyName": {
                "type": "string"
              },
              "CherryPickingMethods": {
                "enum": [
                  "All",
                  "DataContract",
                  "NewtonsoftJson",
                  "Serializable",
                  "AspNet",
                  "NetCore",
                  "ApiOnly",
                  null
                ]
              },

Nullable boolean and alike

        "StringAsString": {
          "type": "boolean"
        },
        "CamelCase": {
          "type": [
            "boolean",
            "null"
          ]
        },

For enum Field

        "CherryPickingMethods": {
          "enum": [
            "All",
            "DataContract",
            "NewtonsoftJson",
            "Serializable",
            "AspNet",
            "NetCore",
            "ApiOnly",
            null
          ]
        },

However, this is unfriendly to flagged enum and int.

For Required Field

It does not care about JsonRequiredAttribute and RequiredAttribute, while respecting the "required" keyword of C#.

Summary

For nullable boolean and alike, all can generate correct codes allowing null.

Some schemas generated declares Schema Identification, while others don't by default.

NJsonSchema uses literal enum and int, seemly supports flagged enum, but a good editor respecting this is not yet found.

JSON Everything exports literal enum. Not good.

NewtonJson and NJsonSchema can read what declared in DescriptionAttribute and make it become the Description field of the schema, while Visual Studio Code displays Description.

.NET 9 Schema Export does not support Title and Description.

So, basically for my cases, particularly for the CodeGen settings, I can use only what exported by .NET 9 or NewtonSoft JSON Schema.

So the verdict is, Newtonsoft.Json.Schema.Generation is the best, at least for my cases. .NET 9 Schema Export is the 2nd best.

Batch Processing of Translation Resource for Angular Apps

fonlow — Sat, 26 Apr 2025 01:51:21 +0000

Introduction

You have been developing SPA using Angular 2+, and familiar with i18n with Angular.

Typically, the production build outputs such multiple deployment images for each locale:

And the build retrieves the translated XLIFF files:

Different software shops may have different collaboration workflows of handling localization/translation. If you are a full-stack developer working in a small shop, likely you will the one who proceeds the machine translation, before involving human translators.

There are wide variety of tools available to automate the machine translation as much as possible, most of them are with interactive GUI. If you prefer CLI and batch processing for the sake of Continuous Integration, you may be interested in using GoogleTranslateXliff introduced in this article.

Continuous Integration with Machine Translation

Write Codes and Test with Development Build

Most of the time during coding, you would be using the development build in a default language.

Update Translation Resource Files

Once you (your team) feel confident of making a release, you update, add or merge the translation resource files through this command:

ng extract-i18n

By default, all the new translation units are with state "new" (XLIFF 1.2) or "initial" (XLIFF 2.0).

As of Angular 19, it is better to update this command with ng-extract-i18n-merge which can merge the updates well.

The .angular.json file should have the following:

        "extract-i18n": {
            "builder": "ng-extract-i18n-merge:ng-extract-i18n-merge",
            "options": {
    "buildTarget": "myng:build",
    "format": "xlf",
    "outputPath": "src/locales",
    "targetFiles": [
        "messages.zh-hans.xlf",
        "messages.zh-hant.xlf",
        "messages.ja.xlf",
        "messages.th.xlf",
        "messages.es.xlf",
        "messages.pt.xlf",
        "messages.fr.xlf",
        "messages.hi.xlf"
    ],

References:

https://stackoverflow.com/questions/71775495/update-merge-i18n-translation-files-in-angular
ng add ng-extract-i18n-merge from https://github.com/daniel-sc/ng-extract-i18n-merge .

Translate Using Google Translate API v2 or v3

Prerequisites:

You have Google Cloud API account, and have acquired API Key for Google Translate v2 or client secret for v3.
You have GoogleTranslateStrings.exe installed in your dev PC. The build scripts for Windows, MacOS and Linux are located in the app code folder for any of the stable releases, presumably you know how to build DotNet programs on Linux or MacOS.

Run this to translate the Spanish resource file:

GoogleTranslateXliff.exe /AK=YourGoogleTranslateV2ApiKey /F=messages.es.xlf

By default, the CLI app will translate those units with state "new" or "initial" only, and then mark the state as "translated".

For multiple locales, it is reasonable to have a shell script to automate further, and this PowerShell script could be a starting point:

$commandPath='C:/Green/GoogleTranslateXliff/GoogleTranslateXliff.exe'
$apiKey='MyGoogleTranslateV2ApiKey'

foreach ($lang in 'es', 'fr', 'hi', 'ja', 'pt', 'th', 'zh-hans', 'zh-hant'){
    $cmd='$commandPath /AK=$apiKey /B /F=messages.$lang.xlf'
    Invoke-Expression $ExecutionContext.InvokeCommand.ExpandString($cmd)
}

Optionally you may involve some human translators to review and finalize the translations and mark those units "signed-off" or "final".

Hints:

Production Build of Angular App

Typically you may run something like:

ng build --configuration=production

Next Release Cycle

For the sake of Agile Software Development, likely you will produce frequent releases, daily, weekly, fortnightly or monthly. Hopefully this CLI tool along with some PowerShell scripts may reduce the operation overhead and make the CI smoother.