A grant proposal for the Dapper Team from Doodles

flooksProposal.md

Flooks - React Hooks for Flow

Grant category

• Open source maintenance
• Developer tools / services

Description

flooks is a react hooks library inspired by the wagmi library in the ethereum ecosystem to create a set of easy to use and understand react hooks to build on flow from the frontend. It serves as an easy-to-use wrapper around FCL that simplifies configuration, provides easier and more compact utility and makes getting a user's wallet connected a simple task.

We would like to open source this library and maintain it for the Flow developer community at large, which we believe will lower the barrier to entry in working with Cadence contracts and wallets on Flow by leveraging simple react hooks and providers with a strong focus on typing and extensibility via actions to streamline app development on Flow.

Problem statement

Working with Cadence scripts and contracts via fcl directly in react apps is possible, but the API can be difficult to use for newcomers, and errors can be difficult to parse. flooks makes it easy for developers new to Flow but understand typical data flows in React applications. Creating an idiomatic and pleasurable react developer experience is important to increase adoption and streamline the development of web3 apps that connect to Flow.

Proposed solution

flooks provides a massive increase in developer experience by doing the following:

1. Leverages strong typing and best practices in Typescript for developer experience and type safety
2. Wraps errors for accessible and easy to understand messages, improving debugging experience and reducing development time
3. Exposes a FlowProvider context to allow use of actions and hooks from the library anywhere within a React application
4. Provides a FlowConnect react component that can be easily configured and skinned to maintain state and open up your account information in a modal for you
5. Typed functions are used to wrap Flow interactions, such as event subscription and script and transaction execution, removing the need to directly use the fcl library.
6. Exposes multiple hooks for ease of development: -- useFlowAccount -- useFlowConnect -- useFlowDisconnect -- useFlowEvent -- useFlowScript -- useFlowScripts -- useFlowTransaction
7. Provides template cadence code generation for common scenarios, such as getting NFTs with MetadataViews or initializing collections, eliminating the need to add cadence code to React in these cases

Simple example:

import { UseQueryResult } from '@tanstack/react-query';
import uniqBy from 'lodash/uniqBy';

import { resolveMetadataViewsFile, useFlowScript } from '@doodles/flooks';

import { getWearablesInventoryScript } from '../../../cadence';
import { WearableToken, WearableTokenQueryData } from '../../../types';

interface UseWearablesInventoryOptions {
  address: string;
  filter?: {
    type?: string;
  };
  uniqueBy?: {
    thumbnail?: boolean;
  };
}

export const useWearablesInventory = ({
  address,
  filter,
  uniqueBy,
}: UseWearablesInventoryOptions): UseQueryResult<WearableToken[]> => {
  const result = useFlowScript<
    WearableTokenQueryData[],
    unknown,
    WearableToken[]
  >({
    code: getWearablesInventoryScript,
    args: [address],
    enabled: !!address,
    select: (data) => {
      let tokens = data.map<WearableToken>((token) => {
        return {
          ...token,
          thumbnail: resolveMetadataViewsFile(
            token.thumbnail,
            process.env.NEXT_PUBLIC_IPFS_GATEWAY,
          ),
        };
      });

      if (filter?.type) {
        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
        tokens = tokens.filter((token) => token.name.includes(filter.type!));
      }

      if (uniqueBy?.thumbnail) {
        tokens = uniqBy(tokens, 'thumbnail');
      }

      return tokens;
    },
  });

  return result;
};

Impact

We believe that this library will lower the barrier to entry for developers that are building UIs on Flow by recreating a familiar API and event loop that web3 developers are already familiar with. By having a well-tested and production-ready react hook solution in the Flow community, we believe that developers will enjoy working with Cadence more, and in effect will create more exiting and dynamic apps in the Flow ecosystem.

Milestones and funding

Note: Please consider adoption and/or maintenance milestones at the end of your project.

Milestone	Deliverables	Timeline	Risks	USD proposal
1 - MVP	Flooks library published	2 weeks	-	-
2 - Market	Official docs website published, full test coverage	6 weeks	-	-
3 - Community Adoption	4+ teams using flooks	3 months	-	-
4 - Community Integrations	Integrate with FLIX	TBD	-	-
X - Ongoing Maintenance	Resolving issues and fixing bugs up to 1.0	3 months	-	-

Total funding proposed: 10k FLOW per month for maintenance

Team

Name	Role	Bio	Contact
Javier Pozzi	Web3 Engineer	web3 developer at Doodles, deployed multiple cadence contracts including Flow marketplace, extensive solidity and cadence experience	javi@doodles.app
Noah Davis	Full-Stack Engineer	Eng Lead at Doodles and previous VP Eng at Sturdy - a marketplace on Flow with extensive experience in well-structured and battle-tested libraries.	noah@doodles.app
Jay Ciruolo	Frontend Engineer	Director of FE at Doodles and previous founder of Jambb - a collectibles project on Flow.	jay@doodles.app