{"id":29177878,"url":"https://github.com/gitcoinco/allo-starter-kit","last_synced_at":"2025-07-01T18:09:03.094Z","repository":{"id":237057749,"uuid":"793719087","full_name":"gitcoinco/allo-starter-kit","owner":"gitcoinco","description":null,"archived":false,"fork":false,"pushed_at":"2024-10-15T17:34:37.000Z","size":11177,"stargazers_count":7,"open_issues_count":3,"forks_count":5,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-06-21T09:48:47.988Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://allo-starter-kit-demo.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gitcoinco.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-04-29T18:34:53.000Z","updated_at":"2025-04-04T02:15:29.000Z","dependencies_parsed_at":null,"dependency_job_id":"12b5aa8d-b2fe-4399-9d21-ea5fbd96ca74","html_url":"https://github.com/gitcoinco/allo-starter-kit","commit_stats":null,"previous_names":["carlbarrdahl/allo-sdk-research","gitcoinco/allo-starter-kit"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/gitcoinco/allo-starter-kit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gitcoinco%2Fallo-starter-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gitcoinco%2Fallo-starter-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gitcoinco%2Fallo-starter-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gitcoinco%2Fallo-starter-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gitcoinco","download_url":"https://codeload.github.com/gitcoinco/allo-starter-kit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gitcoinco%2Fallo-starter-kit/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263013738,"owners_count":23399815,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-01T18:09:00.375Z","updated_at":"2025-07-01T18:09:03.081Z","avatar_url":"https://github.com/gitcoinco.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Allo Kit\n\nAlloKit is a collection of functions, hooks, and components for interacting with the Allo Protocol and its Indexer.\n\n## Table of Contents\n\n- [Allo Kit](#allo-kit)\n  - [Table of Contents](#table-of-contents)\n  - [Introduction](#introduction)\n    - [Building a simple Discover Rounds app](#building-a-simple-discover-rounds-app)\n  - [Stack](#stack)\n  - [Using AlloKit in your project](#using-allokit-in-your-project)\n    - [Install AlloKit in your project](#install-allokit-in-your-project)\n    - [Link AlloKit to your project](#link-allokit-to-your-project)\n    - [Peer Dependencies](#peer-dependencies)\n    - [Usage](#usage)\n      - [Add Component Styles](#add-component-styles)\n      - [Add AlloKit Providers](#add-allokit-providers)\n      - [Import \\\u0026 Use Components](#import--use-components)\n    - [Example usage in your project](#example-usage-in-your-project)\n      - [Demo App](#demo-app)\n  - [Local Development](#local-development)\n    - [Setup](#setup)\n      - [Clone the Repository](#clone-the-repository)\n      - [Install pnpm](#install-pnpm)\n      - [Install Dependencies](#install-dependencies)\n    - [Running the project](#running-the-project)\n      - [Open Demo App in your browser](#open-demo-app-in-your-browser)\n      - [Open Storybook in your browser](#open-storybook-in-your-browser)\n    - [Running the Demo App Standalone](#running-the-demo-app-standalone)\n    - [Running Storybook Standalone](#running-storybook-standalone)\n      - [Run Storybook](#run-storybook)\n  - [Strategy Extensions](#strategy-extensions)\n    - [Building a Strategy Extension](#building-a-strategy-extension)\n\n## Introduction\n\nAlloKit is a collection of functions, hooks, and components for interacting with the Allo Protocol and its Indexer.\n\nFor example:\n\n- Query Rounds, Applications, and Projects\n- Create Rounds, Register and Approve Applications\n- Allocate and Distribute\n\n### Building a simple Discover Rounds app\n\nhttps://www.loom.com/share/e7932c4da2e54902a3d9b66b69285f5e\n\n## Stack\n\n![image](https://github.com/gitcoinco/allo-starter-kit/assets/2961337/4eaabc4a-80a6-41ac-959c-bc2ee459831b)\n\n## Using AlloKit in your project\n\n### Install AlloKit in your project\n\nYou can install it using either _npm_, _pnpm_, _yarn_ **or** _bun_\n\n```sh\nbun add @allo-team/kit\npnpm add @allo-team/kit\nyarn add @allo-team/kit\nnpm install @allo-team/kit --save\n```\n\n### Link AlloKit to your project\n\nIn local development you can link the package to automatically update any changes made to the codebase. You first need to clone this repo.\n\n1. Link the package from the AlloKit project:\n\n   ```sh\n    cd packages/kit\n    bun run link\n   ```\n\n2. Link the package to your project:\n   ```sh\n    cd /path/to/your-project\n    bun link @allo-team/kit --save\n   ```\n\nThis will link the AlloKit package from the cloned repository to the project where you want to use it, allowing you to use it as if it were installed from npm package manager.\n\n### Peer Dependencies\n\nAlloKit has the following peer dependencies that you need to install in your project:\n\n- `react` (version ^18.0.0)\n- `react-dom` (version ^18.0.0)\n- `@rainbow-me/rainbowkit` (version ^2.1.4)\n- `wagmi` (version ^2.12.2)\n\nMake sure these packages are installed in your project.\n\n### Usage\n\nCreate a simple grants app [tutorial](./packages/kit/tutorial.md).\n\n#### Add Component Styles\n\nTo use AlloKit's styles in your project, import the styles CSS file:\n\n```tsx\nimport \"@allo-team/kit/styles.css\";\n```\n\n#### Add AlloKit Providers\n\nTo use AlloKit's context providers, add them to your application:\n\n```tsx\n\"use client\";\nimport { ApiProvider, Web3Provider } from \"@allo-team/kit\";\n\nexport function AlloKitProviders({ children }: PropsWithChildren) {\n  return (\n    \u003cApiProvider api={{ upload }}\u003e\n      \u003cWeb3Provider\u003e{children}\u003c/Web3Provider\u003e\n    \u003c/ApiProvider\u003e\n  );\n}\n// Provide Upload metadata API\n// See `apps/demo/src/app/api/ipfs/route.ts` for example implementation\nasync function upload(data) {\n  return fetch(`/api/ipfs`, { method: \"POST\", body: data })\n    .then(r =\u003e r.json())\n    .then(r =\u003e r.cid);\n}\n```\n\n#### Import \u0026 Use Components\n\nDepending on your app and use-cases you can use the kit in different ways. For example:\n\n- **Direct function call** - This is useful when you want to query the indexer server-side\n- **React Hooks** - Function calls are wrapped in ReactQuery hooks for loading \u0026 error states (plus more!)\n- **React Components** - Ready-made components for common uses\n  - **UI** - Simple design primitives like buttons and forms (see `packages/kit/src/ui`)\n  - **Features** - Larger components often with a complete feature (CreateRound, DiscoverProjects, etc)\n\nExample:\n\n```tsx\nimport { DiscoverRounds, useRounds, indexer } from \"@allo-team/kit\";\n\nexport default function RoundsPage() {\n  // Server-side\n  const rounds = await indexer.rounds(query);\n\n  // Or using hooks (remember to \"use client\" at top of file)\n  const { data, error, isPending } = useRounds(query);\n\n  // Or render ready-made component\n  return (\n    \u003cDiscoverRounds\n      query={query}\n      // Optional renderItem function to wrap in Link component\n      renderItem={({ key, ...round }, RoundCard) =\u003e (\n        \u003cLink key={key} href={`/${round.chainId}/rounds/${round.id}`}\u003e\n          \u003cRoundCard {...round} /\u003e\n        \u003c/Link\u003e\n      )}\n      // Customize how many columns for different screen-sizes [sm, md, lg, xl]\n      columns={[1, 2, 3, 4]}\n    /\u003e\n  );\n}\n\n// Simple query\n// Discover queries here: https://grants-stack-indexer-v2.gitcoin.co/graphiql\n// (There are some differences in the queries. See packages/kit/src/api/types.d.ts)\nconst query = {\n  where: { chainId: { in: [10] } },\n  orderBy: { unique_donors_count: \"desc\" },\n  offset: 0,\n  first: 12,\n};\n```\n\nSee Storybook for more components: https://allo-starter-kit-storybook.vercel.app\n\n### Example usage in your project\n\nSee `apps/demo`\n\n#### Demo App\n\nThe Demo App shows most of the basic usage.\n\nLink: https://allo-starter-kit-demo.vercel.app\n\nExplore code:\n\n- [AlloKit Providers](./apps/demo/src/app/providers.tsx)\n- [Discover Rounds page](./apps/demo/src/app/%5BchainId%5D/page.tsx)\n- [Round Details page + Discover Applications](./apps/demo/src/app/%5BchainId%5D/rounds/%5BroundId%5D/page.tsx)\n- [Project Details page](./apps/demo/src/app/%5BchainId%5D/projects/%5BprojectId%5D/page.tsx)\n- [Create Application / Apply to Round](./apps/demo/src/app/%5BchainId%5D/rounds/%5BroundId%5D/apply/page.tsx)\n- [Create Round](./apps/demo/src/app/admin/rounds/create/page.tsx)\n- [Review Applications](./apps/demo/src/app/admin/rounds/%5BchainId%5D/%5BroundId%5D/page.tsx)\n- [Metadata Upload API](./apps/demo/src/app/api/ipfs/route.ts)\n\n## Local Development\n\n### Setup\n\n#### Clone the Repository\n\n```sh\ngit clone https://github.com/gitcoinco/allo-starter-kit\ncd allo-starter-kit\n```\n\n#### Install pnpm\n\n```sh\nbrew install pnpm\n```\n\n#### Install Dependencies\n\n```sh\npnpm i\n```\n\n### Running the project\n\nThis will run the apps and the kit build in parallel\n\n```sh\npnpm run build\npnpm run dev\n```\n\n#### Open Demo App in your browser\n\n```sh\nopen http://localhost:3000\n```\n\n#### Open Storybook in your browser\n\n```sh\nopen http://localhost:6006\n```\n\n### Running the Demo App Standalone\n\nThis section covers how to run the demo app independently for local development.\n\n### Running Storybook Standalone\n\nThis section covers how to run Storybook independently for local development.\n\n#### Run Storybook\n\nThis will build the kit and run storybook.\n\n```sh\npnpm run storybook\n```\n\n## Strategy Extensions\n\nThe Allo Protocol is highly flexible in the types of strategies can be created. Different strategies might require different parameters and configurations.\n\nThe AlloKit provides a way to create StrategyExtensions where UI components are rendered based on the strategy in the correct components.\n\n### Building a Strategy Extension\n\nLet's use DirectGrantsLite as an example.\n\nFirst we need to understand how Allo and strategies work:\n\n**Allo.sol**\n\n```solidity\n// createPool invokes the strategy's initialize function\n_strategy.initialize(poolId, _initStrategyData);\n```\n\n**DirectGrantsLite.sol**\n\n```solidity\nstruct InitializeData {\n    bool useRegistryAnchor;\n    bool metadataRequired;\n    uint64 registrationStartTime;\n    uint64 registrationEndTime;\n}\n\n// the strategy's initialize function decodes the data\nInitializeData memory initializeData = abi.decode(_data, (InitializeData));\n```\n\nNow, we want to include form components in CreateRound for the user to select start and end times. We also want to encode this into the strategy's InitializeData struct.\n\nThe CreateRound component (and many others) will look for a strategy extension for the current round (or the selected strategy in CreateRound).\n\nIf a matching strategy extension is found, it will render the custom UI component and extend the Zod form schema with the strategy extension.\n\nLet's define a FormField with a RangeCalendar component to choose dates for registration start and end\n\n```tsx\nexport function ChooseRegistrationTimes() {\n  const { control } = useFormContext();\n  return (\n    \u003cFormField\n      control={control}\n      // See the schema definition for information about internal state\n      name=\"initStrategyData.__internal__\"\n      render={({ field }) =\u003e {\n        return (\n          \u003cFormItem\u003e\n            \u003cFormLabel\u003eProject Registration\u003c/FormLabel\u003e\n            \u003cRangeCalendar field={field}\u003e\n              Pick start and end dates\n            \u003c/RangeCalendar\u003e\n            \u003cFormDescription\u003e\n              When can projects submit their application?\n            \u003c/FormDescription\u003e\n            \u003cFormMessage /\u003e\n          \u003c/FormItem\u003e\n        );\n      }}\n    /\u003e\n  );\n}\n\n// Schema definition\nexport const directGrantsRoundSchema = z\n  .object({\n    /*\n    initStrategyData expects to be a bytes string starting with 0x.\n    Temporarily store from and to in an internal state. This will be encoded into the bytes string.\n    */\n    __internal__: z.object({ from: z.date(), to: z.date() }),\n  })\n  // Transform the dates into initStrategyData\n  .transform((val) =\u003e {\n    const { from, to } = val.__internal__;\n    return DirectGrantsLiteStrategy.prototype.getInitializeData({\n      useRegistryAnchor: false,\n      metadataRequired: false,\n      registrationStartTime: dateToUint64(from),\n      registrationEndTime: dateToUint64(to),\n    });\n  });\n\n// Define the DirectGrants Strategy Extension with the createRound component and schema\nexport const directGrants: StrategyExtension = {\n  name: \"Direct Grants Lite\",\n  type: \"directGrants\",\n  // Deployed strategy contract address for all supported networks\n  contracts: supportedChains.reduce(\n    (acc, x) =\u003e ({ ...acc, [x.id]: x.contracts.directGrants }),\n    {}\n  ),\n  components: {\n    createRound: {\n      schema: directGrantsRoundSchema,\n      component: ChooseRegistrationTimes,\n    },\n    // We can also extend other components with strategy-specific functionality\n    registerRecipient: { ... },\n    reviewRecipients: { ... },\n    allocate: { ... },\n    distribute: { ... },\n  },\n};\n\n// Finally we add the directGrants strategy to the AlloKit ApiProvider\n\u003cApiProvider strategies={{ directGrants }}\u003e...\u003c/ApiProvider\u003e;\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgitcoinco%2Fallo-starter-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgitcoinco%2Fallo-starter-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgitcoinco%2Fallo-starter-kit/lists"}