Static Site Generators on the IC

Updates

• Small changes to migrate this starter to dfx 0.8.0.
• I delivered a talk for our Genesis event, walking through the process of this blog post. That video recording is now available here:

Intro

Following up on my recent post announcing http-powered canisters, I want to walk through what it takes to build a frontend application on the Internet Computer while taking advantage of the new features we support. If it seems simple, that’s great! We worked to make this workflow approachable to engineers who are already used to hosting static assets on Netlify, Fastly, or S3 buckets.

For the sake of this demo, I’ll be using Gatsby.js, the framework I use to maintain this blog.

Getting Started

To begin, I run the command npm init gatsby. I’m prompted with “What would you like to call your site?”, and I’ll call this phone_book. I’ll use that name for the folder to create as well. Next I’m prompted whether I’ll be using a CMS, and I answer “No”. I’ll select styled-components from the styling system prompt as a preference, skip the other optional features, and then we’re on our way with a fresh project!

The Gatsby new project CLI

This will set me up with a simple file structure:

├── README.md
├── gatsby-config.js
├── package-lock.json
├── package.json
└── src
    ├── images
    │   └── icon.png
    └── pages
        ├── 404.js
        └── index.js

Deploy a static site

We can start the project up with webpack-dev-server by running npm run develop, and we can compile the project into static HTML, CSS, and JavaScript assets with the command npm run build.

In order to host the project on the Internet computer, we will need to do the following:

• create and configure a dfx.json file at the root of the project
• install the dfx SDK
• deploy using the dfx deploy command

Creating dfx.json

Because Gatsby compiles its build output into the public directory, our dfx.json file will look like this:

// dfx.json
{
  "canisters": {
    "www": {
      "type": "assets",
      "source": ["public"]
    }
  }
}

Installing dfx

You can follow quickstart guide at https://dfinity.org/developers/, or

sh -ci "$(curl -fsSL https://sdk.dfinity.org/install.sh)"

You’ll be prompted to agree to install the latest version, and you should be good to go!

Deploy your site

You will need to fund your production Canister. I recommend going to https://faucet.dfinity.org and following the directions there to get set up with a Cycles Wallet.

Alternately, I’ve written a blog post on creating a canister using the NNS app, which you can read at https://kaipeacock.com/blog/dfinity/your-first-canister/.

Start by running npm run build to compile your website. You can now run dfx deploy --network=ic from the same directory as your dfx.json to publish your website to the Sodium network.

Note: if you used the NNS guide, you will deploy with dfx deploy --network=ic --no-wallet

Once your site deploy is finished, you can find your canister id by running dfx canister id www, and then navigating to https://{canisterId}.icp0.io.

Take a breather

Congratulations! You’ve deployed your first Internet Computer web application! There’s a very good chance that this is your first application built on blockchain technology at all, and that’s worth celebrating. You’ll see that all your assets from HTML to images are all behaving normally, as if you had pulled them directly from an old-school Nginx or PHP static server.

Customizing the application

Now, let’s customize the code here a bit. I want to build a contact book, so let’s swap out the logic in src/pages/index.js with our new application logic.

// dfx.json
{
  "canisters": {
    "phone_book": {
      "main": "src/backend/phone_book/Main.mo"
    },
    "www": {
      "dependencies": ["phone_book"],
      "type": "assets",
      "source": ["public"]
    }
  }
}

"scripts": {
  ...
    "copy:types": "rsync -avr .dfx/$(echo ${DFX_NETWORK:-'**'})/canisters/** --exclude='assets/' --exclude='idl/' --exclude='*.wasm' --delete src/declarations",
    "prestart": "npm run copy:types",
    "prebuild": "npm run copy:types",
}

dfx deploy phone_book
npm run copy:types

// gatsby-config.js
module.exports = {
  siteMetadata: {
    title: "contact book",
  },
  plugins: ["gatsby-plugin-styled-components"],
  proxy: {
    prefix: "/api",
    url: "http://localhost:8000",
  },
};

React.useEffect(() => {
  import("../declarations/phone_book").then((module) => {
    setActor(module.phone_book);
  });
}, []);

actor?.set(email, JSON.stringify(card.toJSON())).then(() => {
  alert("card uploaded!");
  inputs.forEach((input) => {
    input.value = "";
  });
  setImage("");
});

actor?.get(email).then((returnedCard) => {
  if (!returnedCard.length) {
    return alert("No contact found for that email");
  }
  setCard(vCard.fromJSON(returnedCard[0]));
  console.log(returnedCard);
});

├── README.md
├── dfx.json
├── gatsby-config.js
├── gatsby-node.js
├── package-lock.json
├── package.json
└── src
    ├── backend
    │   └── phone_book
    │       └── Main.mo
    ├── images
    │   └── icon.png
    └── pages
        ├── 404.js
        └── index.js