Merge pull request #2645 from dfinity/frontend-docs

Rewrite Frontend Overview & Add info about using external frontends

docs/developer-docs/web-apps/application-frontends/add-stylesheet.mdx

@@ -7,7 +7,7 @@ import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";
 
-# Adding a stylesheet
+# Add a stylesheet
 
 <MarkdownChipRow labels={["Intermediate", "Tutorial"]} />
 

docs/developer-docs/web-apps/application-frontends/bundlers.mdx

@@ -0,0 +1,96 @@
+---
+keywords: [intermediate, concept, frontend]
+---
+
+import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";
+
+# Using bundlers
+
+<MarkdownChipRow labels={["Intermediate", "Concept"]} />
+
+## Overview
+
+Webpack is a popular and highly-configurable module bundler for JavaScript-based applications, new projects created with `dfx new` that choose to create a default JavaScript frontend include a default `webpack.config.js` file that makes it easy to add the specific modules, such as `react` and `markdown`, that you want to use.
+
+## Entry and output configuration
+
+In many cases, you can use the default `webpack.config.js` file as-is, without any modification, or you can add
+plug-ins, modules, and other custom configurations to suit your needs. The specific changes you make to
+the `webpack.config.js` configuration largely depend on the other tools and frameworks you want to use.
+
+For example, if you have experimented with the [customizing the frontend](custom-frontend)
+or [adding a stylesheet](add-stylesheet) frontend tutorials, you might have modified the following section to work with React
+JavaScript:
+
+```
+        module: {
+          rules: [
+            { test: /\.(ts|tsx|jsx)$/, loader: "ts-loader" },
+            { test: /\.css$/, use: ['style-loader','css-loader'] }
+          ]
+        }
+      };
+    }
+```
+
+If your application does not use `dfx` to run your build script, you can provide the variables yourself. For example:
+
+    DFX_NETWORK=ic NODE_ENV=production HELLO_CANISTER_ID=rrkah... npm run build
+
+### Ensuring node.js is available in a project
+
+Because projects rely on webpack to provide the framework for the default frontend, you must have `node.js` installed in
+your development environment and accessible in the project directory.
+
+- If you want to develop your project without using the default webpack configuration and canister aliases, you can
+  remove the `frontend` canister from the `dfx.json` file or build your project using a specific canister name. For
+  example, you can choose to build only the hello program without frontend assets by running the following command:
+
+      dfx build hello_backend
+
+- If you are using the default webpack configuration and running `dfx build` fails, you should try running `npm install`
+  in the project directory then re-running `dfx build`.
+
+- If running `npm install` in the project directory doesn’t fix the issue, you should check the configuration of
+  the `webpack.config.js` file for syntax errors.
+
+## Using other bundlers
+
+You may want to use a bundler other than webpack. Per-bundler instructions are not ready yet, but if you are familiar
+with your bundler, the following steps should get you going:
+
+- #### Step 1: Remove the `copy:types`, `prestart`, and `prebuild` scripts from `package.json`.
+
+- #### Step 2: Run `dfx deploy` to generate the local bindings for your canisters.
+
+- #### Step 3: Copy the generated bindings to a directory where you would like to keep them.
+
+- #### Step 4: Modify `declarations/<canister_name>/index.js` and replace `process.env.<CANISTER_NAME>_CANISTER_ID` with the equivalent pattern for environment variables for your bundler.
+
+    - Alternately hardcode the canister ID if that is your preferred workflow
+
+- #### Step 5: Commit the declarations and import them in your codebase.
+
+## Deploying a frontend canister without building frontend dependencies 
+
+If you'd like to deploy a frontend asset canister without building the node or npm dependency packages, you can manually download the Wasm module dfx uses for its default frontend canister and install the canister manually.
+
+- #### Step 1: Download the frontend asset canister's Wasm module.
+
+```
+wget https://github.com/dfinity/sdk/raw/0.15.2/src/distributed/assetstorage.wasm.gzand
+```
+
+- #### Step 2: Install the canister.
+
+```
+dfx canister install <id instead of name> --wasm assetstorage.wasm.gz
+```
+
+Using the canister ID, the canister will not sync automatically. If you want the canister to sync according to the configuration in `dfx.json`, then use the canister name instead of the canister ID:
+
+```
+dfx canister install frontend_canister --wasm assetstorage.wasm.gz
+```
+
+To sync assets to the canister manually, you can use `icx-asset sync`, but this package must be installed with Rust, `cargo install icx-asset`.

docs/developer-docs/web-apps/application-frontends/custom-frontend.mdx

@@ -4,17 +4,30 @@ keywords: [intermediate, tutorial, frontend]
 
 import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";
 
-# Customizing the frontend
+# Customizing the default frontend canister
 
 <MarkdownChipRow labels={["Intermediate", "Tutorial"]} />
 
 ## Overview
 
-Now that you have a basic understanding of how to create, build, and deploy a simple dapp and are familiar with the default project files and sample frontend, you might want to start experimenting with different ways to customize the frontend user experience for your project.
+By default, projects created with `dfx new` have the option to include a frontend canister that uses a template for one of several frontend frameworks.
 
-This guide illustrates using the React framework to create a new frontend for the default sample dapp and guides you through some basic modifications to customize the interface displayed. Later guides expand on the techniques introduced here, but if you already know how to use CSS, HTML, JavaScript, and React or other frameworks to build your user interface, you can skip this guide.
+Projects created with `dfx` (v0.17.0 and newer) include the option to decide between:
 
-This guide walks through how to manage the Document Object Model (DOM) for your canister. Because React has its own custom DOM syntax, you need to modify the webpack configuration to compile the frontend code, which is written in JSX. For more information about learning to use React and JSX, see [getting started](https://react.dev/learn) on the [React website](https://reactjs.org/).
+- SvelteKit
+- React
+- Vue
+- Vanilla JS
+- No JS template
+- No frontend canister
+
+`dfx` versions v0.16.1 and older include a JavaScript template `index.js` and `webpack.config.js` file.
+
+By default, the `index.js` file imports an agent that is located in `src/declarations/project_frontend/` folder, where 'project' is your project's name (for this guide, the project's name is 'hello'). This directory will be generated by `dfx` when you run `dfx deploy`, either locally or when deploying to ICP.
+
+This guide illustrates using the React framework to edit the frontend for the default sample dapp and guides you through some basic modifications to customize the interface displayed.
+
+This guide explains how to manage the Document Object Model (DOM) for your frontend canister. Because React has its own custom DOM syntax, you need to modify the webpack configuration to compile the frontend code, which is written in JSX. For more information about learning to use React and JSX, see [getting started](https://react.dev/learn) on the [React website](https://reactjs.org/).
 
 ## Prerequisites
 

docs/developer-docs/web-apps/application-frontends/existing-frontend.mdx

@@ -4,17 +4,15 @@ keywords: [intermediate, tutorial, frontend]
 
 import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";
 
-# Deploy an existing frontend
+# Existing frontend applications
 
 <MarkdownChipRow labels={["Intermediate", "Tutorial"]} />
 
 ## Overview
 
 While numerous starter projects and examples exist for those who prefer to start from scratch, deploying an existing frontend application as a frontend canister is also a viable option.
 
-This guide provides an overview of how to deploy an existing frontend application built on the following frameworks as a frontend canister:
-
-- [Next.js](#nextjs)
+This guide provides an overview of how to deploy an existing frontend application built on the Next.js framework as a frontend canister.
 
 ## Next.js
 
@@ -28,7 +26,7 @@ You’ll need the following to complete this guide:
 
 -  [x] An existing Next.js application.
 
--  [x] Complete download and configuration of DFX, the command-line execution environment that serves as the primary tool for creating, deploying, and managing dapps on the Internet Computer. You can reference how to download and configure dfx by reviewing the [install DFX section](/docs/current/developer-docs/getting-started/install/).
+-  [x] Download [`dfx`](/docs/current/developer-docs/getting-started/install), the command-line execution environment that serves as the primary tool for creating, deploying, and managing dapps on the Internet Computer. You can reference how to download and configure dfx by reviewing the [install DFX section](/docs/current/developer-docs/getting-started/install/).
 
 
 ### Step 1: Create an application build