nextjs-ic-starter

nextjs-ic-starter is a boilerplate for building full-stack decentralized applications on the Internet Computer with a Next.js React frontend, Motoko backend canisters, and DFX deployment scripts.

What is nextjs-ic-starter?

nextjs-ic-starter is a starter template that pairs a Next.js 15.2.0 frontend with two Motoko canisters: a hello canister that returns a greeting and an ImageBucket canister that stores, retrieves, and deletes images. It requires DFX 0.25.0 and NodeJS 22.12.0, and it includes a live demo deployed to the IC mainnet at https://u4gun-5aaaa-aaaah-qabma-cai.raw.ic0.app. The template is authored by Henry Chan and released under the MIT license.

Key Features

• Two backend canisters in Motoko — the hello canister exposes a greet function that takes a name and returns a greeting; the ImageBucket canister supports createImage, deleteImage, and getImageById.
• React frontend examples — a name-input form that calls the greet canister and displays the result, plus an image upload form with a "Pick an Image" button that sends a file to the ImageBucket canister and displays it via the useImageObject hook.
• Service locator pattern — actor-locator.js reads the NEXT_PUBLIC_IC_HOST environment variable to set the DFX agent host, so the same code works locally and on the IC network.
• UI declarations adapted for Next.js — after running dfx generate, you copy the generated declaration files into ui/declarations and change variable names to use the NEXT_PUBLIC_ prefix.
• CSS modules styling — styles live in /ui/styles and use CSS modules rather than a CSS framework.
• Static export for IC hosting — npm run build exports the Next.js app to /out, which dfx deploy hello_assets uploads to the frontend canister.
• TypeScript support — the generated UI declarations can be used in TypeScript projects.

Who is it for?

• Web developers who want to deploy a React dapp to the Internet Computer without setting up a web server.
• Motoko developers who need a reference frontend that shows how to call canister methods from a Next.js app.
• Next.js developers curious about deploying static exports to a blockchain network.
• Hackathon participants building image-sharing or demo dapps on IC.

What can you do with it?

• Greeting dapps: call the hello canister with a user name and display the returned greeting — a minimal end-to-end example of canister interaction.
• Image storage dapps: use the ImageBucket canister and useImageObject hook to upload, persist, and retrieve images on-chain.
• Learning IC development: follow the copy commands and deploy steps to understand how UI declarations bridge React and Motoko.

How does it work?

After cloning the repository, you start a local DFX server with dfx start --background, install dependencies with npm install, deploy the canisters locally with dfx deploy --network local, and run the Next.js dev server with npm run dev. The frontend calls canister methods through async actors generated by dfx generate and bridged by the service locator.

Pros and cons

• Pros: includes two complete examples (greeting and image upload), a live mainnet demo, clear deployment instructions for local and mainnet, and permissive MIT licensing.
• Cons: static export limits the frontend to client-side features — Next.js features that require a Node.js server cannot be used when deployed to IC.

FAQ

Is the template free to use?

Yes, nextjs-ic-starter is open source and released under the MIT license. You can use, modify, and redistribute it freely, including in commercial projects.

How do I deploy the dapp to the Internet Computer mainnet?

You need ICP tokens converted to cycles and a cycles wallet. Then copy .env.icprod to .env.production, run dfx deploy --network ic, and open the returned canister ID at https://[canisterId].raw.ic0.app/.

Does the template support TypeScript?

Yes. The generated UI declarations in src/declarations include TypeScript definitions. The template itself uses JavaScript, but you can use the declarations in a TypeScript Next.js project.

What are the system requirements?

The template requires NodeJS 18 or higher, the DFX CLI, and Visual Studio Code with the Motoko extension for editing backend code. The provided install command for DFX is sh -ci "$(curl -fsSL https://internetcomputer.org/install.sh)".

Why is my image not loading in the browser?

Check the Chrome DevTools console and network tab to verify that the frontend is using the correct canister ID and that the DFX host environment variable matches your deployment target (local or mainnet).