Angular Workspace Configuration with angular.json

This guide explains how to configure an Angular workspace using the angular.json file. You’ll learn how to define projects, set build and test options, manage environments, and customize your development server. By the end, you’ll be able to tweak your workspace to fit your project’s needs.

What You’ll Need

• An Angular project created with the Angular CLI (version 6 or later). If you don’t have one, run ng new my-project.
• Basic familiarity with JSON syntax and the command line.
• Node.js and npm installed on your machine.

Step-by-Step

1. Locate and open angular.json. It sits at the root of your Angular workspace. Open it in any text editor.
2. Understand the top-level structure. The file has a version field, a newProjectRoot (where new projects are created), and a projects object that holds every project in the workspace. There’s also a defaultProject field that tells the CLI which project to use when none is specified.
3. Inspect a project definition. Inside projects, each project has a projectType (application or library), root, sourceRoot, prefix (used for component selectors), and an architect section. The architect section defines targets like build, test, and serve.
4. Configure the build target. Under architect.build, set the builder (e.g., @angular-devkit/build-angular:browser). In options, you can set outputPath, index, main, polyfills, tsConfig, and assets. For example, to change the output folder to dist/my-app, set "outputPath": "dist/my-app".
5. Add a development configuration. Under architect.build.configurations, you’ll see a development configuration. You can add or modify configurations here. For instance, to enable source maps in development, add "sourceMap": true to that configuration.
6. Set up production configuration. The production configuration usually includes optimization: true, fileReplacements (to swap environment files), and budgets. You can adjust these to match your performance goals.
7. Configure the serve target. Under architect.serve, set the builder to @angular-devkit/build-angular:dev-server. In options, you can set browserTarget to point to a build target, like my-app:build. Add configurations for development and production that reference the corresponding build configurations.
8. Customize the test target. For unit tests, the builder is @angular-devkit/build-angular:karma. Set main to your test entry file, polyfills to your test polyfills, and tsConfig to your test tsconfig. You can also set codeCoverage to true to generate coverage reports.
9. Add or modify file replacements. In the production build configuration, you’ll often see fileReplacements that swap src/environments/environment.ts with environment.prod.ts. You can add more replacements for other configurations.
10. Define asset globs. In the build.options.assets array, list files or folders to be copied as-is to the output. For example, add "src/favicon.ico" or "src/assets".
11. Set up style and script bundles. In build.options.styles and scripts, list global CSS/SCSS files and JavaScript files to include in the bundle. For instance, add "src/styles.css" to styles.
12. Save and test. After making changes, run ng serve or ng build to see if everything works. Use ng build --configuration production to test the production build.

Common Mistakes

• Invalid JSON syntax. A missing comma or an extra bracket will break the file. Use a JSON validator or an editor with JSON support.
• Wrong paths. Paths in angular.json are relative to the project root or workspace root, depending on the field. Double-check that your paths exist.
• Forgetting to update fileReplacements. If you add a new environment file, you must add the corresponding replacement in the production configuration, or the wrong file will be used.
• Using the wrong builder. Each target has a specific builder. Copying a builder from another target can cause errors.
• Not using configurations. Putting all settings in options instead of configurations makes it hard to switch between development and production.

Tips

• Use the CLI to generate configurations. Running ng generate config or ng add can update angular.json automatically, reducing errors.
• Keep the file readable. Use comments? JSON doesn’t support comments, but you can use a separate documentation file or keep the structure clean.
• Leverage defaultProject. If you have multiple projects, set the default so you don’t have to specify it every time.
• Use ng serve --configuration=production to preview production behavior locally.
• Check the official Angular documentation for the full list of options for each builder.

Troubleshooting

• Build fails with “Invalid configuration”. Check the JSON syntax and ensure all referenced files exist. Use ng build --verbose for more details.
• Changes to angular.json don’t take effect. Restart the dev server or build process. The CLI reads the file at startup.
• Cannot find module ‘x’. Check that the path in main or polyfills is correct and that the file exists.
• Styles not loading. Ensure the style file path is correct and that the file is not empty. Also check for CSS syntax errors.
• Environment variables are undefined. Verify that fileReplacements is correctly set and that the replacement file exports the same variables.

Frequently Asked Questions

Can I have multiple projects in one workspace?

Yes, the projects object can contain multiple entries. Each project has its own configuration. Use ng generate application my-app2 to add a new one.

How do I change the port for the dev server?

In the serve target, add "port": 4201 to options. Alternatively, run ng serve --port 4201.

What is the difference between options and configurations?

options are the default settings for the target. configurations are named sets of overrides that you can apply with --configuration. For example, ng build --configuration production merges the production configuration over the defaults.

How do I add a new global stylesheet?

Add the path to the styles array in the build target’s options. For example, "styles": ["src/styles.css", "src/theme.scss"].

Can I use environment variables in angular.json?

No, angular.json is static JSON. For dynamic values, use file replacements or a custom builder/plugin.

Why does my build output go to a different folder?

Check the outputPath in the build target’s options. It is relative to the workspace root. Also, ensure you are not overriding it with a configuration.

Related

• Music Unblocked at School: How It Works
• Office 365 vs Office: What’s the Difference?
• How Self-Destructing Circuits Work in Mission: Impossible