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 canister is also a viable option for building an application on ICP.

Frontend canisters are deployed as a client-only application; therefore, server methods such as getServerSideProps are not supported.

Example: 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. This example will demonstrate how an existing Next.js application can be deployed as a canister on ICP.

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',
};

Do not delete your existing configuration, as you may have existing settings that should not be overwritten.

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

Building your application 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 used for defining and configuring your project to be compiled and deployed to ICP. In this example, dfx.json is configuring a canister called 'app'; you can adjust this value to refer to the name of your canister. Make sure that the following configuration lines 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. Deploying to the mainnet will cost cycles.

dfx deploy --network ic

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