Using an existing frontend application
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:
Downloaded and installed
dfx
.An existing Next.js application. This guide will use the Next.js ICP example.
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.