adding in documentation for this next release

examples/hello_world/README.md

@@ -51,7 +51,7 @@ node --version
 Install the dfx command line tools for managing ICP applications:
 
 ```bash
-DFX_VERSION=0.19.0 sh -ci "$(curl -fsSL https://sdk.dfinity.org/install.sh)"
+DFX_VERSION=0.20.1 sh -ci "$(curl -fsSL https://sdk.dfinity.org/install.sh)"
 ```
 
 Check that the installation went smoothly by looking for clean output from the following command:
@@ -74,6 +74,8 @@ cd hello_world
 
 npm install
 
+npx azle install-dfx-extension
+
 dfx start --clean --host 127.0.0.1:8000
 ```
 

the_azle_book/book/deployment.html

@@ -176,6 +176,9 @@ <h2 id="starting-the-local-replica"><a class="header" href="#starting-the-local-
 <pre><code class="language-bash">dfx start --clean --host 127.0.0.1:8000
 </code></pre>
 <h2 id="deploying-to-the-local-replica"><a class="header" href="#deploying-to-the-local-replica">Deploying to the local replica</a></h2>
+<p>Make sure you have installed the <code>azle dfx extension</code> (only needs to be done once per install per version of Azle):</p>
+<pre><code class="language-bash">npx azle install-dfx-extension
+</code></pre>
 <p>To deploy all canisters defined in your <code>dfx.json</code>:</p>
 <pre><code class="language-bash">dfx deploy
 </code></pre>
@@ -201,6 +204,9 @@ <h2 id="interacting-with-your-canister"><a class="header" href="#interacting-wit
 </code></pre>
 <h2 id="deploying-to-mainnet"><a class="header" href="#deploying-to-mainnet">Deploying to mainnet</a></h2>
 <p>Assuming you are <a href="https://internetcomputer.org/docs/current/developer-docs/getting-started/cycles/cycles-wallet">setup with a cycles wallet</a>, then you are ready to deploy to mainnet.</p>
+<p>Make sure you have installed the <code>azle dfx extension</code> (only needs to be done once per install per version of Azle):</p>
+<pre><code class="language-bash">npx azle install-dfx-extension
+</code></pre>
 <p>To deploy all canisters defined in your dfx.json:</p>
 <pre><code class="language-bash">dfx deploy --network ic
 </code></pre>

the_azle_book/src/assets.md

@@ -8,25 +8,10 @@ Here's an example that copies the `src/frontend/dist` directory on the deploying
 {
     "canisters": {
         "backend": {
-            "type": "custom",
+            "type": "azle",
             "main": "src/backend/index.ts",
-            "candid": "src/backend/index.did",
-            "candid_gen": "http",
-            "build": "npx azle backend",
-            "wasm": ".azle/backend/backend.wasm",
-            "gzip": true,
             "assets": [["src/frontend/dist", "dist"]],
-            "build_assets": "npm run build",
-            "metadata": [
-                {
-                    "name": "candid:service",
-                    "path": "src/backend/index.did"
-                },
-                {
-                    "name": "cdk:name",
-                    "content": "azle"
-                }
-            ]
+            "build_assets": "npm run build"
         }
     }
 }

the_azle_book/src/deployment.md

@@ -52,6 +52,12 @@ dfx start --clean --host 127.0.0.1:8000
 
 ## Deploying to the local replica
 
+Make sure you have installed the `azle dfx extension` (only needs to be done once per install per version of Azle):
+
+```bash
+npx azle install-dfx-extension
+```
+
 To deploy all canisters defined in your `dfx.json`:
 
 ```bash
@@ -92,6 +98,12 @@ curl -X POST -H "Content-Type: application/json" -d "{ \"hello\": \"world\" }" h
 
 Assuming you are [setup with a cycles wallet](https://internetcomputer.org/docs/current/developer-docs/getting-started/cycles/cycles-wallet), then you are ready to deploy to mainnet.
 
+Make sure you have installed the `azle dfx extension` (only needs to be done once per install per version of Azle):
+
+```bash
+npx azle install-dfx-extension
+```
+
 To deploy all canisters defined in your dfx.json:
 
 ```bash

the_azle_book/src/get_started.md

@@ -48,7 +48,7 @@ node --version
 Install the dfx command line tools for managing ICP applications:
 
 ```bash
-DFX_VERSION=0.19.0 sh -ci "$(curl -fsSL https://sdk.dfinity.org/install.sh)"
+DFX_VERSION=0.20.1 sh -ci "$(curl -fsSL https://sdk.dfinity.org/install.sh)"
 ```
 
 Check that the installation went smoothly by looking for clean output from the following command:
@@ -71,6 +71,8 @@ cd hello_world
 
 npm install
 
+npx azle install-dfx-extension
+
 dfx start --clean --host 127.0.0.1:8000
 ```
 

the_azle_book/src/project_structure.md

@@ -13,32 +13,205 @@ hello_world/
     └── api.ts
 ```
 
-And the corresponding `dfx.json` file:
+For an HTTP server canister this would be the simplest corresponding `dfx.json` file:
 
 ```json
 {
     "canisters": {
         "api": {
-            "type": "custom",
+            "type": "azle",
+            "main": "src/api.ts"
+        }
+    }
+}
+```
+
+For a Candid RPC canister this would be the simplest corresponding `dfx.json` file:
+
+```json
+{
+    "canisters": {
+        "api": {
+            "type": "azle",
+            "main": "src/api.ts",
+            "candid_gen": "automatic"
+        }
+    }
+}
+```
+
+Once you have created this directory structure you can [deploy to mainnet](./deployment.md#deploying-to-mainnet) or a [locally running replica](./deployment.md#starting-the-local-replica) by running the `dfx deploy` command in the same directory as your `dfx.json` file.
+
+## dfx.json
+
+The `dfx.json` file is the main ICP-specific configuration file for your canisters. The following are various examples of `dfx.json` files.
+
+### Automatic Candid File Generation
+
+The command-line tools `dfx` require a Candid file to deploy your canister. HTTP server canisters will automatically have their Candid files generated and stored in the `.azle` directory without any extra property in the `dfx.json` file. Candid RPC canisters must specify `"candid_gen": "automatic"` for their Candid files to be generated automatically in the `.azle` directory:
+
+```json
+{
+    "canisters": {
+        "api": {
+            "type": "azle",
+            "main": "src/api.ts",
+            "candid_gen": "automatic"
+        }
+    }
+}
+```
+
+### Custom Candid File
+
+If you would like to provide your own custom Candid file you can specify `"candid_gen": "custom"`:
+
+```json
+{
+    "canisters": {
+        "api": {
+            "type": "azle",
             "main": "src/api.ts",
             "candid": "src/api.did",
-            "candid_gen": "http",
-            "build": "npx azle api",
-            "wasm": ".azle/api/api.wasm",
-            "gzip": true,
-            "metadata": [
-                {
-                    "name": "candid:service",
-                    "path": "src/api.did"
-                },
-                {
-                    "name": "cdk:name",
-                    "content": "azle"
-                }
+            "candid_gen": "custom"
+        }
+    }
+}
+```
+
+### Environment Variables
+
+You can provide environment variables to Azle canisters by specifying their names in your `dfx.json` file and then accessing them through the `process.env` object in Azle.
+
+You must provide the environment variables that you want included in the same process as your `dfx deploy` command.
+
+Be aware that the environment variables that you specify in your `dfx.json` file will be included in plain text in your canister's Wasm binary.
+
+```json
+{
+    "canisters": {
+        "api": {
+            "type": "azle",
+            "main": "src/api.ts",
+            "env": ["MY_ENVIRONMENT_VARIABLE"]
+        }
+    }
+}
+```
+
+### Assets
+
+See [the Assets chapter](./assets.md) for more information:
+
+```json
+{
+    "canisters": {
+        "api": {
+            "type": "azle",
+            "main": "src/api.ts",
+            "assets": [
+                ["src/frontend/dist", "dist"],
+                ["src/backend/media/audio.ogg", "media/audio.ogg"],
+                ["src/backend/media/video.ogv", "media/video.ogv"]
             ]
         }
     }
 }
 ```
 
-Once you have created this directory structure you can [deploy to mainnet](./deployment.md#deploying-to-mainnet) or a [locally running replica](./deployment.md#starting-the-local-replica) by running the `dfx deploy` command in the same directory as your `dfx.json` file.
+### Assets Large
+
+See [the Assets chapter](./assets.md) for more information:
+
+```json
+{
+    "canisters": {
+        "api": {
+            "type": "azle",
+            "main": "src/api.ts",
+            "assets_large": [
+                ["assets/auto", "assets"],
+                ["assets/permanent", "assets"],
+                ["assets/single_asset.txt", "assets/text/single.txt"]
+            ]
+        }
+    }
+}
+```
+
+### Build Assets
+
+See [the Assets chapter](./assets.md) for more information:
+
+```json
+{
+    "canisters": {
+        "api": {
+            "type": "azle",
+            "main": "src/api.ts",
+            "assets": [
+                ["src/frontend/dist", "dist"],
+                ["src/backend/media/audio.ogg", "media/audio.ogg"],
+                ["src/backend/media/video.ogv", "media/video.ogv"]
+            ],
+            "build_assets": "npm run build"
+        }
+    }
+}
+```
+
+### ESM Externals
+
+This will instruct Azle's TypeScript/JavaScript build process to ignore bundling the provided named packages.
+
+Sometimes the build process is overly eager to include packages that won't actually be used at runtime. This can be a problem if those packages wouldn't even work at runtime due to limitations in ICP or Azle. It is thus useful to be able to exclude them:
+
+```json
+{
+    "canisters": {
+        "api": {
+            "type": "azle",
+            "main": "src/api.ts",
+            "esm_externals": ["@nestjs/microservices", "@nestjs/websockets"]
+        }
+    }
+}
+```
+
+### ESM Aliases
+
+This will instruct Azle's TypeScript/JavaScript build process to alias a package name to another pacakge name.
+
+This can be useful if you need to polyfill certain packages that might not exist in Azle:
+
+```json
+{
+    "canisters": {
+        "api": {
+            "type": "azle",
+            "main": "src/api.ts",
+            "esm_aliases": {
+                "crypto": "crypto-browserify"
+            }
+        }
+    }
+}
+```
+
+### Opt Level
+
+To optimize the Wasm binary of an Azle canister, you can add the `opt_level` property to your `dfx.json` with the following options: `"0"`, `"1"`, `"2"`, `"3"`, or `"4"`. `"0"` is the default option if `opt_level` is not specified.
+
+Each option is intended to reduce the size of your Wasm binary as the value increases. Each option is likely to take longer to compile than the previous option. It is recommended to start at `"1"` and increase only as necessary.
+
+```json
+{
+    "canisters": {
+        "api": {
+            "type": "azle",
+            "main": "src/api.ts",
+            "opt_level": "4"
+        }
+    }
+}
+```

the_azle_book/src/reference_http/autoreload.md

@@ -1,7 +1,5 @@
 # Autoreload
 
-> Deploying to mainnet with AZLE_AUTORELOAD=true will expose your canister to arbitrary untrusted JavaScript code execution
-
 You can turn on automatic reloading of your canister's final compiled JavaScript by using the `AZLE_AUTORELOAD` environment variable during deploy:
 
 ```bash
@@ -14,4 +12,4 @@ Autoreload only works properly if you do not change the methods of your canister
 
 Autoreload will not reload assets uploaded through the `assets` property of your `dfx.json`.
 
-It is extremely important to keep in mind that setting `AZLE_AUTORELOAD=true` will create an update method in your canister called `reload_js` that has no authorization built into it. If you deploy this to mainnet, anyone will be able to call this method and change the JavaScript of your canister.
+Setting `AZLE_AUTORELOAD=true` will create a new `dfx` identity and set it as a controller of your canister. By default it will be called `_azle_file_uploader_identity`. This name can be changed with the `AZLE_UPLOADER_IDENTITY_NAME` environment variable.

the_azle_book/src/servers.md

@@ -41,6 +41,22 @@ app.use(express.static('/dist'));
 app.listen();
 ```
 
+or NestJS servers like this:
+
+```typescript
+import { NestFactory } from '@nestjs/core';
+import { NestExpressApplication } from '@nestjs/platform-express';
+
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+    const app = await NestFactory.create<NestExpressApplication>(AppModule);
+    await app.listen(3000);
+}
+
+bootstrap();
+```
+
 # Servers
 
 -   [Node.js http.server](#nodejs-httpserver)