angular-compiler

Choose the Right Budget Types

"budgets": [
    {
        "type": "initial",
        "baseline": "800kb",
        "maximumWarning": "20%",
        "maximumError": "35%"
    },
    {
        "type": "anyComponentStyle",
        "maximumWarning": "4kb",
        "maximumError": "8kb"
    },
    {
        "type": "all",
        "baseline": "1mb",
        "maximumWarning": "20%",
        "maximumError": "35%"
    }
],

For most applications, configuring initial and anyComponentStyle budgets is a great starting point.

Angular provides several budget types to monitor different parts of your application:

• initial: This is the most important budget to configure. It targets the initial JavaScript and CSS needed to bootstrap your application. A smaller initial bundle size leads to faster initial load times.
• anyComponentStyle: This budget type checks the size of each individual component's stylesheet. It's a great way to prevent a single component's CSS from becoming bloated.
• all: This covers the total size of all files in your application.
• allScript: This is the combined size of all JavaScript files.
• bundle: This allows you to set a budget for a specific, named bundle.
• any: This checks the size of any single file.

Making the choice of where to place your stylesheet files—specifically whether to put them in the root src folder or the src/assets folder—comes down to a simple question: Is this a core, application-wide style that should be processed and bundled by Angular, or is it a static asset that needs to be served as-is?

Here's a breakdown of the thought process and best practices for making that decision.

1. Root src/styles.scss (or a similar location)

This is the default and most common location for your primary global styles. The file at src/styles.scss is explicitly referenced in your angular.json file.

When to choose this location:

• For core, global application styles. This is where you should define styles that apply to your entire application, such as:

  • Typography: The default font family, sizes, and colors for h1, p, etc.
  • Reset or Normalize CSS: Styles that standardize browser renderings.
  • Layout Helpers: Global utility classes like .text-center or .flex-container.
  • Sass/SCSS variables, mixins, and functions: If you're using a preprocessor, this file is the perfect place to import your Sass partials (_variables.scss, _mixins.scss) so they can be used throughout your entire application.

• For third-party CSS libraries that you want to bundle. If you're using a CSS framework like Bootstrap, Tailwind CSS, or a component library's CSS, you can @import or include the library's main file in your styles.scss. The Angular build process will then include this CSS in your main application bundle.

How it works: The Angular build system sees the styles.scss file specified in angular.json. It compiles it (if it's a preprocessor like Sass) and bundles the resulting CSS into your main styles.css file, which is loaded when the application starts. This ensures your global styles are available from the get-go.

2. src/assets/styles folder

This location is for files that are treated as static assets. The contents of the assets folder are simply copied to the dist directory during the build process, without any special compilation or bundling.

When to choose this location:

• For dynamic themes. If your application supports multiple themes (e.g., "light" and "dark"), you might place the theme-specific CSS files in assets. This allows you to load the appropriate theme CSS file dynamically at runtime based on user preferences.

  • Example: src/assets/styles/light-theme.css, src/assets/styles/dark-theme.css.

• For files that are conditionally loaded. You might have a large CSS file that is only needed for a specific, rarely used feature. Rather than bundling it with your main styles.css and increasing the initial load time for all users, you can place it in assets and load it dynamically when that feature is accessed.

• For files that you don't want to process with the Angular build. In rare cases, you might have a very specific CSS file that should not be compiled or manipulated in any way. Placing it in assets ensures it remains untouched.

How it works: The assets folder is configured in angular.json. The build process simply copies the entire folder to the output directory. You would then load these stylesheets in your HTML or dynamically via TypeScript using a method like document.head.appendChild(...).

Summary Guideline

Location	Purpose	How it's handled by Angular
src/styles.scss	Core, global application styles and third-party libraries you want bundled.	Compiled, bundled, and included in the main styles.css file that is loaded on application startup.
src/assets/styles/	Static CSS files for dynamic loading, themes, or conditional features.	Copied directly to the build output directory without bundling. Must be referenced and loaded manually.

In the vast majority of cases, you should use the root src/styles.scss file for all your global styling needs. It's the simplest and most efficient way to handle a cohesive design system. You would only deviate to the assets folder if you have a specific, advanced use case that requires a stylesheet to be handled separately from the main application bundle.