Skip to content

Commit d8125fd

Browse files
lacolacolacolaco
authored
feat(docs): translate CLI build documentation to Japanese (#1066)
1 parent d72f6b0 commit d8125fd

File tree

2 files changed

+210
-61
lines changed

2 files changed

+210
-61
lines changed

‎adev-ja/src/content/tools/cli/build.en.md

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
# Building Angular apps
2+
3+
You can build your Angular CLI application or library with the `ng build` command.
4+
This will compile your TypeScript code to JavaScript, as well as optimize, bundle, and minify the output as appropriate.
5+
6+
`ng build` only executes the builder for the `build` target in the default project as specified in `angular.json`.
7+
Angular CLI includes four builders typically used as `build` targets:
8+
9+
| Builder | Purpose |
10+
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
11+
| `@angular-devkit/build-angular:application` | Builds an application with a client-side bundle, a Node server, and build-time prerendered routes with [esbuild](https://esbuild.github.io/). |
12+
| `@angular-devkit/build-angular:browser-esbuild` | Bundles a client-side application for use in a browser with [esbuild](https://esbuild.github.io/). See [`browser-esbuild` documentation](tools/cli/build-system-migration#manual-migration-to-the-compatibility-builder) for more information. |
13+
| `@angular-devkit/build-angular:browser` | Bundles a client-side application for use in a browser with [webpack](https://webpack.js.org/). |
14+
| `@angular-devkit/build-angular:ng-packagr` | Builds an Angular library adhering to [Angular Package Format](tools/libraries/angular-package-format). |
15+
16+
Applications generated by `ng new` use `@angular-devkit/build-angular:application` by default.
17+
Libraries generated by `ng generate library` use `@angular-devkit/build-angular:ng-packagr` by default.
18+
19+
You can determine which builder is being used for a particular project by looking up the `build` target for that project.
20+
21+
<docs-code language="json">
22+
23+
{
24+
"projects": {
25+
"my-app": {
26+
"architect": {
27+
// `ng build` invokes the Architect target named `build`.
28+
"build": {
29+
"builder": "@angular-devkit/build-angular:application",
30+
…
31+
},
32+
"serve": { … }
33+
"test": { … }
34+
…
35+
}
36+
}
37+
}
38+
}
39+
40+
</docs-code>
41+
42+
This page discusses usage and options of `@angular-devkit/build-angular:application`.
43+
44+
## Output directory
45+
46+
The result of this build process is output to a directory (`dist/${PROJECT_NAME}` by default).
47+
48+
## Configuring size budgets
49+
50+
As applications grow in functionality, they also grow in size.
51+
The CLI lets you set size thresholds in your configuration to ensure that parts of your application stay within size boundaries that you define.
52+
53+
Define your size boundaries in the CLI configuration file, `angular.json`, in a `budgets` section for each [configured environment](tools/cli/environments).
54+
55+
<docs-code language="json">
56+
57+
{
58+
…
59+
"configurations": {
60+
"production": {
61+
…
62+
"budgets": [
63+
{
64+
"type": "initial",
65+
"maximumWarning": "250kb",
66+
"maximumError": "500kb"
67+
},
68+
]
69+
}
70+
}
71+
}
72+
73+
</docs-code>
74+
75+
You can specify size budgets for the entire app, and for particular parts.
76+
Each budget entry configures a budget of a given type.
77+
Specify size values in the following formats:
78+
79+
| Size value | Details |
80+
| :-------------- | :-------------------------------------------------------------------------- |
81+
| `123` or `123b` | Size in bytes. |
82+
| `123kb` | Size in kilobytes. |
83+
| `123mb` | Size in megabytes. |
84+
| `12%` | Percentage of size relative to baseline. \(Not valid for baseline values.\) |
85+
86+
When you configure a budget, the builder warns or reports an error when a given part of the application reaches or exceeds a boundary size that you set.
87+
88+
Each budget entry is a JSON object with the following properties:
89+
90+
| Property | Value |
91+
| :------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
92+
| type | The type of budget. One of: <table> <thead> <tr> <th> Value </th> <th> Details </th> </tr> </thead> <tbody> <tr> <td> <code>bundle</code> </td> <td> The size of a specific bundle. </td> </tr> <tr> <td> <code>initial</code> </td> <td> The size of JavaScript and CSS needed for bootstrapping the application. Defaults to warning at 500kb and erroring at 1mb. </td> </tr> <tr> <td> <code>allScript</code> </td> <td> The size of all scripts. </td> </tr> <tr> <td> <code>all</code> </td> <td> The size of the entire application. </td> </tr> <tr> <td> <code>anyComponentStyle</code> </td> <td> This size of any one component stylesheet. Defaults to warning at 2kb and erroring at 4kb. </td> </tr> <tr> <td> <code>anyScript</code> </td> <td> The size of any one script. </td> </tr> <tr> <td> <code>any</code> </td> <td> The size of any file. </td> </tr> </tbody> </table> |
93+
| name | The name of the bundle (for `type=bundle`). |
94+
| baseline | The baseline size for comparison. |
95+
| maximumWarning | The maximum threshold for warning relative to the baseline. |
96+
| maximumError | The maximum threshold for error relative to the baseline. |
97+
| minimumWarning | The minimum threshold for warning relative to the baseline. |
98+
| minimumError | The minimum threshold for error relative to the baseline. |
99+
| warning | The threshold for warning relative to the baseline (min & max). |
100+
| error | The threshold for error relative to the baseline (min & max). |
101+
102+
## Configuring CommonJS dependencies
103+
104+
Always prefer native [ECMAScript modules](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/import) (ESM) throughout your application and its dependencies.
105+
ESM is a fully specified web standard and JavaScript language feature with strong static analysis support. This makes bundle optimizations more powerful than other module formats.
106+
107+
Angular CLI also supports importing [CommonJS](https://nodejs.org/api/modules.html) dependencies into your project and will bundle these dependencies automatically.
108+
However, CommonJS modules can prevent bundlers and minifiers from optimizing those modules effectively, which results in larger bundle sizes.
109+
For more information, see [How CommonJS is making your bundles larger](https://web.dev/commonjs-larger-bundles).
110+
111+
Angular CLI outputs warnings if it detects that your browser application depends on CommonJS modules.
112+
When you encounter a CommonJS dependency, consider asking the maintainer to support ECMAScript modules, contributing that support yourself, or using an alternative dependency which meets your needs.
113+
If the best option is to use a CommonJS dependency, you can disable these warnings by adding the CommonJS module name to `allowedCommonJsDependencies` option in the `build` options located in `angular.json`.
114+
115+
<docs-code language="json">
116+
117+
"build": {
118+
"builder": "@angular-devkit/build-angular:browser",
119+
"options": {
120+
"allowedCommonJsDependencies": [
121+
"lodash"
122+
]
123+
…
124+
}
125+
…
126+
},
127+
128+
</docs-code>
129+
130+
## Configuring browser compatibility
131+
132+
The Angular CLI uses [Browserslist](https://github.com/browserslist/browserslist) to ensure compatibility with different browser versions.
133+
Depending on supported browsers, Angular will automatically transform certain JavaScript and CSS features to ensure the built application does not use a feature which has not been implemented by a supported browser. However, the Angular CLI will not automatically add polyfills to supplement missing Web APIs. Use the `polyfills` option in `angular.json` to add polyfills.
134+
135+
By default, the Angular CLI uses a `browserslist` configuration which [matches browsers supported by Angular](reference/versions#browser-support) for the current major version.
136+
137+
To override the internal configuration, run [`ng generate config browserslist`](cli/generate/config), which generates a `.browserslistrc` configuration file in the project directory matching Angular's supported browsers.
138+
139+
See the [browserslist repository](https://github.com/browserslist/browserslist) for more examples of how to target specific browsers and versions.
140+
Avoid expanding this list to more browsers. Even if your application code more broadly compatible, Angular itself might not be.
141+
You should only ever _reduce_ the set of browsers or versions in this list.
142+
143+
HELPFUL: Use [browsersl.ist](https://browsersl.ist) to display compatible browsers for a `browserslist` query.
144+
145+
## Configuring Tailwind
146+
147+
Angular supports [Tailwind](https://tailwindcss.com/), a utility-first CSS framework.
148+
149+
Follow the [Tailwind documentation](https://tailwindcss.com/docs/installation/framework-guides/angular) for integrating with Angular CLI.

0 commit comments

Comments
 (0)