diff --git a/docs/developer-docs/web-apps/application-frontends/add-stylesheet.mdx b/docs/developer-docs/web-apps/application-frontends/add-stylesheet.mdx index 6fc6d05f8e..0c2ab9bed6 100644 --- a/docs/developer-docs/web-apps/application-frontends/add-stylesheet.mdx +++ b/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 diff --git a/docs/developer-docs/web-apps/application-frontends/bundlers.mdx b/docs/developer-docs/web-apps/application-frontends/bundlers.mdx new file mode 100644 index 0000000000..160a878adc --- /dev/null +++ b/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 + + + +## 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//index.js` and replace `process.env._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 --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`. diff --git a/docs/developer-docs/web-apps/application-frontends/custom-frontend.mdx b/docs/developer-docs/web-apps/application-frontends/custom-frontend.mdx index 177c9dad50..2030ba87a3 100644 --- a/docs/developer-docs/web-apps/application-frontends/custom-frontend.mdx +++ b/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 ## 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 diff --git a/docs/developer-docs/web-apps/application-frontends/existing-frontend.mdx b/docs/developer-docs/web-apps/application-frontends/existing-frontend.mdx index 9cdced8c04..4528e7b24a 100644 --- a/docs/developer-docs/web-apps/application-frontends/existing-frontend.mdx +++ b/docs/developer-docs/web-apps/application-frontends/existing-frontend.mdx @@ -4,7 +4,7 @@ keywords: [intermediate, tutorial, frontend] import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -# Deploy an existing frontend +# Existing frontend applications @@ -12,9 +12,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; 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 diff --git a/docs/developer-docs/web-apps/application-frontends/overview.mdx b/docs/developer-docs/web-apps/application-frontends/overview.mdx index a72840648f..e1131553df 100644 --- a/docs/developer-docs/web-apps/application-frontends/overview.mdx +++ b/docs/developer-docs/web-apps/application-frontends/overview.mdx @@ -1,258 +1,36 @@ --- -keywords: [intermediate, tutorial, frontend] +keywords: [intermediate, concept, frontend] --- import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; # Overview - + -A frontend canister, also referred to as an **asset canister**, is a type of canister used to host an application's frontend assets, such as the user interface, webpage, or dashboard for the dapp. +Dapps deployed on ICP often utilize a frontend interface to facilitate user interaction with the application. Application frontends include the user interface, webpage, dashboard, or other assets that are displayed in the web browser. -Frontend canisters utilize the [JavaScript agent](https://www.npmjs.com/package/@dfinity/agent) as a communication layer. By using -the [default frontend canister](https://github.com/dfinity/sdk/tree/master/src/canisters/frontend/ic-frontend-canister) provided by `dfx` to upload static files to ICP, -you will be able to run your entire application on decentralized technology. This section takes a closer look at the -default frontend template that is generated by running the `dfx new` command, configuring the frontend canister, and using other frameworks to -build the user interface for your projects. +Frontends can exist in the following forms: -:::info -Frontend canisters are also known as *asset canisters*, since they hold *assets*. -::: +- A frontend canister that communicates with backend canister(s) to provide a full-stack dapp. You can learn more by viewing the [default frontend canister](custom-frontend.mdx) and learn how to customize it. -Here are some quick links to tutorials with example code for various stages of developing your frontend dapp: +- Backend canisters communicate with an external frontend application that isn't hosted on ICP. To facilitate this communication, [agent-js](/docs/current/developer-docs/developer-tools/off-chain/agents/javascript-agent) can be used. You can [learn more about the JS request API](/docs/current/developer-docs/web-apps/browser-js/js-request-api). -- [Customize the frontend](./custom-frontend.mdx): a tutorial on building a React dapp. +- A frontend canister that doesn't communicate with any backend canisters and only provides web assets such as a website. [Learn more about serving static assets](serving-static-assets). -- Using [Candid](/docs/current/developer-docs/backend/motoko/hello-location#candid-ui) as a bare-bones interface to expose and test the functions in a canister. +Frontend canisters are also referred to as asset canisters in the context of ICP. -- Using [raw HTML and JavaScript](/docs/current/developer-docs/backend/motoko/explore-templates#default-frontend) to display a simple HTML entry page. +## Resources + +- [Customize the default frontend canister](./custom-frontend.mdx). -- Using [React and compiled JavaScript](./custom-frontend.mdx) to embed HTML attributes and elements directly in a page. +- Using [raw HTML and JavaScript](/docs/current/developer-docs/backend/motoko/explore-templates#default-frontend) to display a simple HTML entry page. - Using [React and TypeScript](./add-stylesheet.mdx) to import CSS properties from an external file. - Deploying an [existing React application](./existing-frontend.mdx) as a frontend canister. -## Default templates - -### `dfx` v0.17.0 and newer - -Projects created with `dfx` (v0.17.0 and newer) include the option to decide between several different frontend templates, including: - -- SvelteKit -- React -- Vue -- Vanilla JS -- No JS template -- No frontend canister - -### `dfx` v0.16.1 and older - -`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. - -The generated code for the agent will look like this: - -`src/declarations/hello_frontend/index.js`: - -``` -import { Actor, HttpAgent } from "@dfinity/agent"; - -// Imports and re-exports candid interface -import { idlFactory } from "./hello_frontend.did.js"; -export { idlFactory } from "./hello_frontend.did.js"; - -/* CANISTER_ID is replaced by webpack based on node environment - * Note: canister environment variable will be standardized as - * process.env.CANISTER_ID_ - * beginning in dfx 0.15.0 - */ -export const canisterId = - process.env.CANISTER_ID_HELLO_FRONTEND || - process.env.HELLO_FRONTEND_CANISTER_ID; - -export const createActor = (canisterId, options = {}) => { - const agent = options.agent || new HttpAgent({ ...options.agentOptions }); - - if (options.agent && options.agentOptions) { - console.warn( - "Detected both agent and agentOptions passed to createActor. Ignoring agentOptions and proceeding with the provided agent." - ); - } - - // Fetch root key for certificate validation during development - if (process.env.DFX_NETWORK !== "ic") { - agent.fetchRootKey().catch((err) => { - console.warn( - "Unable to fetch root key. Check to ensure that your local replica is running" - ); - console.error(err); - }); - } - - // Creates an actor with using the candid interface and the HttpAgent - return Actor.createActor(idlFactory, { - agent, - canisterId, - ...options.actorOptions, - }); -}; - -export const hello_frontend = createActor(canisterId); -``` - -:::caution -This example uses `fetchRootKey`. It is not recommended that dapps deployed on the mainnet call this function from agent-js, since using `fetchRootKey` on the mainnet poses severe security concerns for the dapp that's making the call. It is recommended to put it behind a condition so that it only runs locally. - -This API call will fetch a root key for verification of update calls from a single replica, so it’s possible for that replica to respond with a malicious key. A verified mainnet root key is already embedded into agent-js, so this only needs to be called on your local replica, which will have a different key from mainnet that agent-js does not know ahead of time. -::: - -Then, if you look at the `src/hello_frontend/src/index.js` file, you can see that it takes the generated actor, and uses it to make a call to the hello canister’s greet method: - -``` -import { hello_backend } from "../../declarations/hello_backend"; - -document.querySelector("form").addEventListener("submit", async (e) => { - e.preventDefault(); - const button = e.target.querySelector("button"); - - const name = document.getElementById("name").value.toString(); - - button.setAttribute("disabled", true); - - // Interact with foo actor, calling the greet method - const greeting = await hello_backend.greet(name); - - button.removeAttribute("disabled"); - - document.getElementById("greeting").innerText = greeting; - - return false; -}); -``` - -In many projects, you will be able to use the code under `declarations` without any changes, then customize your dapp's frontend by making changes -in `src/hello_frontend/assets` and `src/hello_frontend/src`. However, if your project has additional requirements, continue reading below. - -## Modifying the webpack configuration - -Because webpack is a popular and highly-configurable module bundler for JavaScript-based applications, new projects -create 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 configuration 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 modules with the React framework - -Several tutorials and sample projects in the [examples](https://github.com/dfinity/examples) repository illustrate how -to add React modules using the `npm install` command. You can use these modules to construct the user interface -components you want to use in your project. For example, you might run the following command to install -the `react-router` module: - - npm install --save react react-router-dom - -You could then use the module to construct a navigation component similar to the following: - - import React from 'react'; - import { NavLink } from 'react-router-dom'; - - const Navigation = () => { - return ( - - ); - } - - export default Navigation; - - -## Using other frameworks - -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//index.js` and replace `process.env._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 --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`. diff --git a/sidebars.js b/sidebars.js index 9de6d2a371..8022b64511 100644 --- a/sidebars.js +++ b/sidebars.js @@ -467,10 +467,11 @@ const sidebars = { label: "Application frontends", items: [ "developer-docs/web-apps/application-frontends/overview", - "developer-docs/web-apps/application-frontends/serving-static-assets", "developer-docs/web-apps/application-frontends/custom-frontend", - "developer-docs/web-apps/application-frontends/add-stylesheet", "developer-docs/web-apps/application-frontends/existing-frontend", + "developer-docs/web-apps/application-frontends/serving-static-assets", + "developer-docs/web-apps/application-frontends/add-stylesheet", + "developer-docs/web-apps/application-frontends/bundlers", "developer-docs/web-apps/application-frontends/webpack-dev-server", ], },