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 or adding a 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 thedfx.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 runningnpm install
in the project directory then re-runningdfx build
.If running
npm install
in the project directory doesn’t fix the issue, you should check the configuration of thewebpack.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
, andprebuild
scripts frompackage.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 replaceprocess.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
.