Skip to main content

Using an existing frontend application

Intermediate
Tutorial

Overview​

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 for building an application on ICP.

This guide provides an overview of how to deploy an existing Next.js application as a frontend canister.

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

Next.js​

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.

Prerequisites​

Before you start, verify that you have:

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:

output: 'export'

Your next.config.js file should resemble the following:

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

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

Then, build your Next.js application by running the appropriate build command. For example, if you are using npx:

npx run build

You should reference your package.json scripts section to determine the correct build command.

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

When deploying on ICP, these static files are not public to anyone, including the nodes. Only the Wasm file, which is a binary instruction file that does not leak any of your code, is public.

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": {
      "app": {
        "frontend": {
          "entrypoint": "out/index.html"
        },
        "source": ["out"],
        "type": "assets"
      }
    },
    "output_env_file": ".env"
}

dfx.json is the configuration file for deploying your 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"

  • "source": ["out"]

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: Navigate to the frontend canister to view the application​

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

Next steps​

Learn about asset security policies.