mirror of
https://github.com/angular/angular
synced 2026-05-24 09:28:37 +00:00
786ea441e9
Update the `esbuild` macro in devtools to use `external` sourcemaps by default and remove the ability to override the `sourcemap` and `sources_content` options. This change is necessary to ensure that the build is deterministic and 100% reproducible as otherwise Firefox will not publish the build.
131 lines
4.7 KiB
Markdown
131 lines
4.7 KiB
Markdown
# Angular DevTools
|
|
|
|
Angular DevTools is a browser DevTools extension for debugging and profiling Angular applications.
|
|
|
|
## Developing Locally
|
|
|
|
<!-- This duplicates some general content for setting up the angular/angular repository, however it is important to
|
|
have complete instructions here for Mozilla Add-On reviewers who need to be able to reproduce Angular DevTools
|
|
builds and will use the same documentation. -->
|
|
|
|
### Set up
|
|
|
|
Follow the instructions below to set up your Angular DevTools development
|
|
environment. Note that all commands should be executed in the repository root, not
|
|
`devtools/`. All file paths are also relative to the repository root.
|
|
|
|
Debian Linux, MacOS, and Windows via WSL should build successfully. Building
|
|
natively on Windows without WSL is not supported at the moment.
|
|
|
|
To set up your development environment, first install the [correct version of Node](/.nvmrc). If you have
|
|
[`nvm`](https://github.com/nvm-sh/nvm) set up, this can be done with:
|
|
|
|
```shell
|
|
nvm install
|
|
```
|
|
|
|
Second, install [pnpm](https://pnpm.io/):
|
|
|
|
```shell
|
|
npm install -g pnpm
|
|
```
|
|
|
|
Third, install NPM dependencies:
|
|
|
|
```shell
|
|
pnpm install --frozen-lockfile
|
|
```
|
|
|
|
Now you should be ready to build the DevTools extension.
|
|
|
|
### Dev builds
|
|
|
|
To run the extension in development mode run:
|
|
|
|
```shell
|
|
pnpm devtools:devserver
|
|
```
|
|
|
|
This would start a development server that you can access on <http://localhost:4200>. In development, Angular DevTools
|
|
uses a "development shell." This is different from "chrome shell" in a way, that it runs the user's app in an iframe.
|
|
DevTools then communicate with the user's app via message passing.
|
|
|
|
#### Dev Install
|
|
|
|
To actually build and install as a real browser extension in dev mode, use:
|
|
|
|
```shell
|
|
pnpm devtools:build:chrome:debug
|
|
```
|
|
|
|
This will build the extension at `dist/bin/devtools/projects/shell-browser/src/prodapp`. Then go to `chrome://extensions`,
|
|
enable developer mode, and click "Load unpacked" to load the extension from that directory.
|
|
|
|
Whenever you rebuild the extension, make sure to reload the extension in `chrome://extensions`, right click on the
|
|
Angular DevTools panel and click "Reload frame", and refresh the page you're inspecting to make sure changes are applied.
|
|
|
|
#### Debugging
|
|
|
|
Depending on which script you want to debug, you can find them in different locations. In debug mode, these should all
|
|
have sourcemaps loaded and be unminified.
|
|
|
|
- The main "Angular DevTools" panel UI runs in its own frame and can be found by clicking "Inspect Element" directly
|
|
on that UI.
|
|
- Note that this inspects _all_ of Chrome DevTools, which loads Angular DevTools in an iframe.
|
|
- The right entry point is under `index.html/ienfalfjdbdpebioblfackkekamfmbnh/...`
|
|
- Scripts directly executed in the inspected page content's can be found in the normal Sources panel under "Angular DevTools".
|
|
- `backend_bundle.js`
|
|
- `detect_angular_bundle.js`
|
|
- Content scripts are executed in the inspected page, but within an isolated environment and found in the normal Sources panel,
|
|
but under the "Content Scripts" section (as opposed to "Page", "Workspace", "Overrides", etc., you may need to click an
|
|
arrow to expand the list of sections).
|
|
- `content_script_bundle.js`
|
|
- `ng_validate_bundle.js`
|
|
- The background service worker is found at `chrome://extensions`.
|
|
- Click on the "Angular DevTools" extension and the "Inspect Views > service worker" button to open a debugger.
|
|
|
|
### Enabling sourcemaps
|
|
|
|
To enable sourcemaps you need to add the `sourcemap = "inline"` flag to the `esbuild` macro located in `tools/defaults.bzl`.
|
|
|
|
### Running End-to-End Tests
|
|
|
|
Before running end-to-end tests, you need to start the development server using:
|
|
|
|
```shell
|
|
pnpm devtools:devserver
|
|
```
|
|
|
|
You have two options for running cypress, you can use the interactive cypress UI or you can run Cypress in headless mode.
|
|
|
|
To open Cypress for Angular DevTools in interactive mode, run:
|
|
|
|
```shell
|
|
pnpm devtools:e2e:open
|
|
```
|
|
|
|
To run Cypress tests headless, use:
|
|
|
|
```shell
|
|
pnpm devtools:test:e2e
|
|
```
|
|
|
|
### Release builds
|
|
|
|
You can build the release version of Angular DevTools for either Chrome or Firefox with:
|
|
|
|
```shell
|
|
pnpm devtools:build:chrome:release
|
|
pnpm devtools:build:firefox:release
|
|
```
|
|
|
|
Either way, the built extension will be at `dist/bin/devtools/projects/shell-browser/src/prodapp`.
|
|
|
|
#### Installation
|
|
|
|
For Chrome, you can install the extension from `dist/bin/devtools/projects/shell-browser/src/prodapp` by following the
|
|
guide from [here](https://developer.chrome.com/docs/extensions/get-started/tutorial/hello-world#load-unpacked).
|
|
|
|
For Firefox, to load the extension, you can go to the about:debugging page, click the "This Firefox" option and then
|
|
click the Load Temporary Add-on button. You'll have to select the manifest file in
|
|
`dist/bin/devtools/projects/shell-browser/src/prodapp` directly.
|