Skip to main content

Using an existing application frontend

Intermediate
Tutorial

While numerous starter projects and examples exist for those who prefer to start from scratch, deploying an existing application frontend as a frontend canister is also a viable option for building an application on ICP.

Server methods such as getServerSideProps are not supported, since it will be deployed as a client-only application.

Using a Next.js frontend​

Next.js is an open-source web development framework providing React-based web applications with server-side rendering and static website generation.

View the GitHub repo for this example.

Install the IC SDK.

  • Step 1: Build your Next.js application.​

To start, you must generate static files and build your Next.js application. To generate the static files, add this line to your next.config.js file:

const nextConfig = {
  output: 'export',
};

Please note that you may have existing settings that you should avoid overwriting.

Then, build your Next.js application by running the appropriate build command. You should reference your package.json's scripts section to determine the correct build command. For example, if you are using npx:

npx run build

This should generate an out folder, which consists of the static assets that make up the frontend.

  • Step 2: Create a dfx.json file​

In the top-level directory of your repository, add a dfx.json file containing the following content:

{
    "canisters": {
        "frontend": {
          "entrypoint": "out/index.html"
        "source": ["out"],
        "type": "assets"
      }
    },
    "output_env_file": ".env"
}

dfx.json is the configuration file used for configuring and deploying your app to ICP as a canister. In this example, this file is configuring a canister called 'app'. Note that you can adjust app to refer to the name of your canister. Also, make sure that these point to the correct files:

  • "entrypoint": "out/index.html": The index or entrance point for the application's files.

  • "source": ["out"]: The directory hosting the application's web assets.

  • Step 3: Generate Candid definitions.​

Run the following command to generate the correct Candid type definitions:

dfx generate

  • Step 4: Deploy the project.​

Then, you can deploy the Next.js application locally for testing:

dfx deploy

Or, you can deploy directly on the mainnet:

dfx deploy --network ic

Deploying to the mainnet will cost cycles.

After running either command, you will see a generated link that is now hosting your Next.js application. The local url will be in the format http://127.0.0.1:4943/?canisterId=<canister-id>, while the mainnet URL will be in the format https://<canister-id>.icp0.io/.

  • Step 5: Open the application.​

Navigate to the frontend canister using the URL you received in the last step.