Differences and Use Cases Between --base-href and --deploy-url Parameters in Angular CLI

Functional Differences Between Parameters

In Angular application deployment, the --base-href and --deploy-url build parameters are often confused. --base-href is primarily used to set the <base href> tag in the HTML document, which directly affects Angular routing URL composition and relative path resource resolution. For instance, when an app is deployed in a subdirectory like /my/app/, setting --base-href /my/app/ generates <base href="/my/app/">, ensuring that routing and relative resource requests are based on this path.

In contrast, the --deploy-url parameter only modifies the URL prefix for static assets (e.g., JavaScript and CSS files) referenced in index.html. For example, after running ng build --prod --deploy-url /public/, the original <script src="main.HASH.js"></script> is replaced with <script src="/public/main.HASH.js"></script>. However, note that this parameter does not affect relative resource paths in templates or XMLHttpRequests.

Use Cases and Code Examples

In most deployment scenarios, using only --base-href suffices. For example, if the app is deployed at https://example.com/my/app/, the build command should be:

ng build --prod --base-href /my/app/

This automatically sets the correct <base href> and ensures that routing and all relative path resources (e.g., images, templates) are resolved based on this path.

However, when static assets need to be deployed at a different path, both parameters can be combined. Suppose the app is accessible at https://example.com/users/, but static resources are stored in the https://example.com/public/ directory. The build command would be:

ng build --prod --base-href /users/ --deploy-url /public/

The generated index.html will include <base href="/users/"> and resource links like <script src="/public/main.HASH.js"></script>. But note that relative resources in templates (e.g., <img src="assets/logo.jpg">) are still resolved based on base-href, potentially causing failures due to path mismatches.

Limitations and Deprecation of --deploy-url

The --deploy-url parameter has significant limitations. First, it only modifies resource links in index.html and does not handle relative paths in templates. For instance, <img src="assets/icon.png"> in a component template won't automatically gain the /public/ prefix, leading to resource loading failures. Second, the parameter value must include a trailing slash; otherwise, it generates invalid links (e.g., publicmain.HASH.js).

More importantly, Angular officially deprecated --deploy-url starting from v13, mainly because its functionality can be replaced by base-href and manual configuration; using it slightly reduces build speed; and it fails to comprehensively cover relative resource location needs. The recommended alternative is: if the resource path differs from the application path, set --base-href to the resource path and manually specify the app base path via dependency injection of APP_BASE_HREF. For example:

// Provide APP_BASE_HREF in AppModule
providers: [{ provide: APP_BASE_HREF, useValue: '/users/' }]

Meanwhile, use the build command with --base-href /public/, so resources load based on /public/, while routing operates based on /users/.

Summary and Best Practices

--base-href is the core parameter for defining the overall base path of the application, impacting routing, relative resource requests, and template links. It should be prioritized for subdirectory deployments. --deploy-url serves only as a historical feature for specific resource path separation scenarios but is not recommended for new projects due to deprecation and incomplete functionality. Developers should follow official guidelines, using --base-href and APP_BASE_HREF configuration to flexibly handle path requirements, ensuring stable operation in production environments.