Skip to content

Angular never loads an external library .css asset #31017

Closed as not planned
Closed as not planned

Description

@maxpatiiuk

Command

build

Is this a regression?

  • Yes, this behavior used to work in the previous version

The previous version in which this bug was not present was

No response

Description

If external library has a CSS import, the asset will be processed by Angular (in both dev server and build), but never actually loaded in the browser.

Minimal Reproduction

  1. Clone this repo

    git clone https://github.com/maxpatiiuk/angular-css-asset-lost
    cd angular-css-asset-lost
  2. Install dependencies

    # To keep reproduction size minimal, I hardcoded a minimal root-level node_modules
    # So, install Angular dependencies only in the app folder:
    cd app
    npm install
  3. Start the development server in the app folder

    npx ng serve

    See that the CSS is never loaded in the browser (page would turn green if it was loaded).

  4. Build the app

    npx ng build

    Build output:

    > ng build
    
    Initial chunk files | Names         | Raw size | Estimated transfer size
    main.js             | main          | 91.03 kB |                27.28 kB
    
                        | Initial total | 91.03 kB |                27.28 kB
    
    Lazy chunk files    | Names         | Raw size | Estimated transfer size
    main.css            | -             | 56 bytes |                56 bytes

    The lazy chunk is created, but never referenced in the index.html or any .js file.

    You can serve the build in the browser to verify:

    npx serve dist/reproduction/browser -p 4200

See node_modules/external-library/ for the dummy external library with a CSS file.

Exception or Error


Your Environment

Angular CLI: 20.2.0
Node: 22.16.0
Package Manager: npm 10.9.2
OS: darwin arm64
    

Angular: 20.2.1
... compiler-cli, core, platform-browser

Package                      Version
------------------------------------
@angular-devkit/architect    0.2002.0
@angular-devkit/core         20.2.0
@angular-devkit/schematics   20.2.0
@angular/build               20.2.0
@angular/cli                 20.2.0
@schematics/angular          20.2.0
rxjs                         7.8.2
typescript                   5.9.2

Anything else relevant?

What I tried and does not fix the issue:

  • package.json sideEffects setting (saying that .css or everything is side effect).
  • package.json exports (explicitly exporting the .css file).
  • reproduced in a real package that exports real things besides .css so this dummy package is not the issue.

In development server, setting "optimization": true build option fixes the issue, but that does not work in production.

Older related issue: #23273

Activity

  1. maxpatiiuk commented on Aug 22, 2025

    @maxpatiiuk
    Author

    Use case:

    • My component library has global css (for css variables). It also consumes several other component libraries, each of which also has global css. I wish to auto-load the styles for my consumers to simplify the "Get started" instructions.

    This works in most bundlers, but not in Angular.

  2. alan-agius4 commented on Aug 22, 2025

    @alan-agius4
    Collaborator

    This expected and is the same behaviour of esbuild which is documented in their documentation: https://esbuild.github.io/content-types/#css-from-js

    The fact that under certain conditions it works in ng serve seems to be an unexpected behaviour.

  3. maxpatiiuk commented on Aug 24, 2025

    @maxpatiiuk
    Author

    Thanks for a quick reply!

    Assuming that this is expected behavior, could you please advise how should an end user handle this?

    Should the user manually import such CSS file in their index.html? Unfortunately, while that fixes the build, it causes a 404 error in the dev server.

    Moreover, if outputHashing is enabled, the output CSS file name is not stable, so manually importing it is not possible.


    For reference, here is how other bundlers & frameworks handled such case:

    • Vite, Webpack (css-loader or experiments.css), Rspack, AnalogJS, Next.js, Parcel: css is bundled & auto-loaded automatically
    • ESBuild: all CSS is bundled into a single CSS file with a controllable name (regardless if the CSS file was imported in CSS or in JS). Plus, the user can customize this with a plugin.
    • Rollup, Rolldown: a community plugin can be used (I am not sure if this is possible in angular-cli)
  4. imaksp commented on Aug 25, 2025

    @imaksp
    Contributor

    Hi, you can include it in angular.json file like this:

     "styles": [
                  "node_modules/primeicons/primeicons.css",
                  "node_modules/quill/dist/quill.core.css",
                  "node_modules/quill/dist/quill.snow.css",
                  "node_modules/video.js/dist/video-js.min.css",
                  "src/styles.css"
                ]

    you can also import it in main style.css file using css @import.

  5. alan-agius4 commented on Aug 25, 2025

    @alan-agius4
    Collaborator

    IMHO, importing CSS as a JavaScript module is not to be considered a good practice and should be avoided, especially when building a library. This approach relies on specific build tools to transform the CSS into a valid JS module, and different tools may handle this process in different ways, leading to inconsistent behavior.

    Instead, a better approach is to provide a pre-compiled CSS file or a SCSS file. Users can then import and include these files as part of their own build pipeline, which gives them more control and ensures consistency. In Angular users can use the style option. This is also approach that is used by the majority of JS and CSS frameworks.

  6. maxpatiiuk commented on Aug 26, 2025

    @maxpatiiuk
    Author

    Please let me tell you more about our use case for this.
    Our component library (includes css) depends on other component libraries (which also include css).
    The sub-libraries may only be needed by some entrypoints so always importing their css is wasteful.
    In addition, if we wish to add a new sub-library dependency in the future, if css is not imported automatically, we would have to declare a breaking change and make our consumers manually add the new css import.

    As it stands, we have a nice story "css is handled automatically, don't worry" for most users, with a red warning message for Angular users.

    In Angular users can use the style option. This is also approach that is used by the majority of JS and CSS frameworks.

    Per my testing, a library .js file importing .css is handled correctly in:

    • React (Next.js, React-router)
    • SvelteKit
    • AnalogJS
    • Nuxt. Vanilla Vue (Vite)
    • Preact (default Vite starter)

    I was not able to find any other framework where this use case is not handled.

  7. maxpatiiuk commented on Aug 30, 2025

    @maxpatiiuk
    Author

    monaco-editor, a 2 million weekly downloads library, include .css imports in hundreds of their .css files. This ensures that only the CSS for the bundles you imported will be bundled in.

    My component library uses monaco-editor. For most of my users, the CSS just works automatically. However, Angular users face issue with CSS not working.
    The only way I could think of working around this is if I bundle in the monaco-editor's css - but that means users of every other bundler will get CSS twice (the one I bundled in, and the one from .css imports in monaco-editor's .js files).

    For now, I have to tell my users to explicitly import monaco's css. This is not scalable as it means when I add a new UI dependency, I have to declare a breaking change, forcing Angular users to add yet another CSS import.

    For reference, monaco's get started does not mention css at all because it "just works" for most users.

    I hope you reconsider the position given the use cases I provided. Importing .css in .js is very useful for library developers.
    Let me know if I can provide more examples.
    Thank you for your time.

  8. angular-automatic-lock-bot commented on Sep 30, 2025

    @angular-automatic-lock-bot

    This issue has been automatically locked due to inactivity.
    Please file a new issue if you are encountering a similar or related problem.

    Read more about our automatic conversation locking policy.

    This action has been performed automatically by a bot.

  9. locked and limited conversation to collaborators on Sep 30, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions