icp-codegen v0.0.5

Internet Computer JS/TS Code Generator

icp-codegen is a tool that generates code automatically from your Internet Computer cannisters, intended to speedup frontend development in JS/TS. It can do things like automatically create react-query code for all your methods, transform the data you pass to and receive from your canisters, and more. icp-codegen is extensible with a plugin system. Think of this as GraphQL Codegen for the internet computer.

There already exists dfx, the official dfinity tool for generating code from canisters but it is very bare bones. icp-codegen is intended to be much more "batteries included" and extensible.

icp-codegen works by implementing it's own pure JS candid parser using ohm. It downloads candid files over the network, parses them into it's own internal representation, then passes that through a series of plugins to generate output files.

How to use

• In your frontend project run npm install icp-codegen
• Create a icp-codegen.config.ts file in the root of your frontend application
• Run npx icp-codegen to generate the output file
• In your frontend code import the functions you want from the generated file and use them

See below for examples

Examples

React query queries/mutations

Create a config with reactQueryPlugin in the plugins list

icp-codegen.config.ts:

import { reactQueryPlugin } from "icp-codegen/plugins";
import { createConfig, getDefaultPlugins } from "icp-codegen/config";

export default createConfig({
  output: "./src/icp-api",
  plugins: [
    ...getDefaultPlugins(),
    reactQueryPlugin(),
  ],
  canisters: {
    MyCoolCanister: { principle: "aaaaa-aaaaaa-aaaaa-aaaaa-aaa" }
  },
});

Add the Provider to your react app component tree

src/providers.tsx:

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { Provider as ICPProvider } from "./icp-api";
import { HttpAgent } from "@dfinity/agent";

const queryClient = new QueryClient();
const httpAgent = HttpAgent.createSync();

export const Providers: React.FC<{ children: React.ReactNode }> = ({
  children,
}) => {
  return (
    <QueryClientProvider client={queryClient}>
      <ICPProvider httpAgent={httpAgent}>
        {children}
      </ICPProvider>
    </QueryClientProvider>
  );
};

Use a query (args are passed in the arg param)

src/something.tsx:

import { useMyExampleQuery } from "./icp-api";

export const SomeComponent = () => {
  const { data } = useMyExampleQuery({ args: [42n, "Hello world"] });
  return (
    <p>{data ? data.something : 'no data (yet?)'}</p>
  );
};