Skip to main content

Using bundlers

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 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 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.