Index: docs/optimizing_web_uis.md |
diff --git a/docs/optimizing_web_uis.md b/docs/optimizing_web_uis.md |
new file mode 100644 |
index 0000000000000000000000000000000000000000..366bd2e1d8e5cca4711366744d1e5df69d344a24 |
--- /dev/null |
+++ b/docs/optimizing_web_uis.md |
@@ -0,0 +1,138 @@ |
+# Optimizing Chrome Web UIs |
+ |
+## How do I do it? |
+ |
+In order to build with a fast configuration, try setting these options in your |
+GN args: |
+ |
+``` |
+use_vulcanize = true |
+is_debug = false |
+``` |
+ |
+If you make local changes, you likely need to re-run: |
+ |
+``` |
+$ chrome/browser/resources/vulcanize.py |
+``` |
+ |
+And rebuild Chrome to see effects. vulcanize.py will result in local changes to |
+*crisper* and *vulcanized* files that you must currently check in. |
+ |
+*NOTE: This is likely to change soon to be more tightly integrated with GN / |
dpapad
2017/01/23 19:20:53
Perhaps add a link to https://bugs.chromium.org/p/
Dan Beam
2017/01/24 01:50:24
Done.
|
+Chrome's build.* |
+ |
+## How is the code optimized? |
+ |
+### Resource combination |
+ |
+[HTML imports](https://www.html5rocks.com/en/tutorials/webcomponents/imports/) |
+are a swell technology, but can be used is slow ways. Each import may also |
+contain additional imports, which must be satisfied before certain things can |
+continue (i.e. script execution may be paused). |
+ |
+```html |
+<!-- If a.html contains more imports... --> |
+<link rel="import" href="a.html"> |
+<!-- This script is blocked until done. --> |
+<script> startThePageUp(); </script> |
+``` |
+ |
+To reduce this latency, Chrome uses a tool created by the Polymer project named |
+[vulcanize](https://github.com/Polymer/vulcanize). It processes a page starting |
dpapad
2017/01/23 19:20:53
This URL just redirects to polymer-bundler repo. P
Dan Beam
2017/01/24 01:50:24
Done.
|
+from a URL entry point and inlines resources the first time they're encountered. |
+This greatly decreases latency due to HTML imports. |
+ |
+```html |
+<!-- Contents of a.html and all its dependencies. --> |
+<script> startThePageUp(); </script> |
+``` |
+ |
+### CSS @apply to --var transformation |
+ |
+We also use |
+[polymer-css-build](https://github.com/PolymerLabs/polymer-css-build) to |
+transform CSS @apply mixins (which are not yet natively supported) into faster |
+--css-variables. This turns something like this: |
+ |
+```css |
+:host { |
+ --mixin-name: { |
+ color: red; |
+ display: block; |
+ }; |
+} |
+/* In a different place */ |
+.red-thing { |
+ @apply(--mixin-name); |
+} |
+``` |
+ |
+into the more performant: |
+ |
+```css |
+:host { |
+ --mixin-name_-_color: red; |
+ --mixin-name_-_display: block; |
+} |
+/* In a different place */ |
+.red-thing { |
+ color: var(--mixin-name_-_color); |
+ display: var(--mixin-name_-_display); |
+} |
+``` |
+ |
+### JavaScript Minification |
+ |
+In order to minimize disk size, we run |
+[uglifyjs](https://github.com/mishoo/UglifyJS2) on all combined JavaScript. This |
+reduces installer and the size of resources required to load to show a UI. |
+ |
+Code like this: |
+ |
+```js |
+function fizzBuzz() { |
+ for (var i = 1; i <= 100; i++) { |
+ var fizz = i % 3 == 0 ? 'fizz' : ''; |
+ var buzz = i % 5 == 0 ? 'buzz' : ''; |
+ console.log(fizz + buzz || i); |
+ } |
+} |
+fizzBuzz(); |
+``` |
+ |
+would be minified to: |
+ |
+```js |
+function fizzBuzz(){for(var z=1;100>=z;z++){var f=z%3==0?"fizz":"",o=z%5==0?"buzz":"";console.log(f+o||z)}}fizzBuzz(); |
+``` |
+ |
+If you'd like to more easily debug minified code, click the "{}" prettify button |
+in Chrome's developer tools, which will beautify the code and allow setting |
+breakpoints on the un-minified version. |
+ |
+### Gzip compression of web resources |
+ |
+In certain cases, it might be preferable to leave web resources compressed on |
+disk and inflate them when needed (i.e. when a user wants to see a page). |
+ |
+In this case, you can run `gzip --rsyncable` on a resource before it's put into |
+a .pak file via GRIT with this syntax: |
+ |
+```xml |
+<include name="IDR_MY_PAGE" file="my/page.html" type="BINDATA" compress="gzip" /> |
+``` |
+ |
+Gzip is currently set up to apply to a whole WebUI's data source, though it's |
+possible to exclude specific paths for things like dynamically generated content |
+(i.e. many pages load translations dynamically from a path named "strings.js"). |
+ |
+To mark a WebUI's resources compressed, you'll need to do something like: |
+ |
+```c++ |
+WebUIDataSource* data_source = WebUIDataSource::Create(...); |
+data_source->SetDefaultResource(IDR_MY_PAGE); |
+std::unordered_set<std::string> exclusions; |
+exclusions.insert("strings.js"); // if required |
+data_source->UseGzip(exclusions); |
+``` |