{"id":26951449,"url":"https://github.com/algorandfoundation/algokit-client-generator-ts","last_synced_at":"2026-04-09T18:02:11.526Z","repository":{"id":165976817,"uuid":"641289933","full_name":"algorandfoundation/algokit-client-generator-ts","owner":"algorandfoundation","description":null,"archived":false,"fork":false,"pushed_at":"2025-03-21T18:24:58.000Z","size":2947,"stargazers_count":4,"open_issues_count":12,"forks_count":7,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-21T19:33:06.597Z","etag":null,"topics":["algokit"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/algorandfoundation.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2023-05-16T07:05:40.000Z","updated_at":"2025-03-13T16:15:57.000Z","dependencies_parsed_at":"2023-10-10T20:38:19.934Z","dependency_job_id":"a6110d34-96fe-4a39-a521-af25c8c4d64e","html_url":"https://github.com/algorandfoundation/algokit-client-generator-ts","commit_stats":null,"previous_names":[],"tags_count":106,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/algorandfoundation%2Falgokit-client-generator-ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/algorandfoundation%2Falgokit-client-generator-ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/algorandfoundation%2Falgokit-client-generator-ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/algorandfoundation%2Falgokit-client-generator-ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/algorandfoundation","download_url":"https://codeload.github.com/algorandfoundation/algokit-client-generator-ts/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246911490,"owners_count":20853656,"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":["algokit"],"created_at":"2025-04-03T00:01:28.214Z","updated_at":"2026-03-12T17:30:04.107Z","avatar_url":"https://github.com/algorandfoundation.png","language":"TypeScript","funding_links":[],"categories":["Core Resources"],"sub_categories":["AlgoKit"],"readme":"# AlgoKit TypeScript client generator (algokit-client-generator-ts)\n\nThis project generates a type-safe smart contract client in TypeScript for the Algorand Blockchain that wraps the [application client](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/docs/capabilities/app-client.md) in [AlgoKit Utils](https://github.com/algorandfoundation/algokit-utils-ts) and tailors it to a specific smart contract. It does this by reading an [ARC-56](https://github.com/algorandfoundation/ARCs/pull/258) or [ARC-32](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0032.md) application spec file and generating a client which exposes methods for each ABI method in the target smart contract, along with helpers to create, update, and delete the application.\n\n## Usage\n\n### Prerequisites\n\nTo be able to consume the generated file you need to include it in a TypeScript project that has (at least) the following package installed:\n\n```\nnpm install @algorandfoundation/algokit-utils\n```\n\nNote: you need at least version 7 of AlgoKit Utils to work with the latest version of the generator. It currently only works with algosdk v2.\n\n### Migration\n\nIf you're migrating your project from an older generated typed client to v4, please refer to the [v4 migration guide](./docs/v4-migration.md).\n\n### Use\n\nThe cli can be used to generate a client via the following command.\n\n```bash\nnpx --yes  @algorandfoundation/algokit-client-generator generate -a ./application.json -o ./client.generated.ts\n```\n\n#### CLI Options\n\nThe CLI supports the following options:\n\n- `-a, --application \u003cpath\u003e` (required): Specifies the path to the ARC-56 or ARC-32 application.json file\n- `-o, --output \u003cpath\u003e` (required): Specifies the output file path for the generated TypeScript client\n- `--pn, --preserve-names`: Preserve names from the application.json spec instead of sanitizing them to camelCase\n- `-m, --mode \u003cmode\u003e`: Generate client in specified mode (default: `full`)\n  - `full`: Generates a complete client with factory, deployment capabilities and all features\n  - `minimal`: Generates a lightweight client without factory or deployment capabilities, resulting in a smaller output\n\n#### CLI Examples\n\nGenerate a full client (default):\n\n```bash\nnpx --yes @algorandfoundation/algokit-client-generator generate -a ./application.json -o ./client.ts\n```\n\nGenerate a minimal client:\n\n```bash\nnpx --yes @algorandfoundation/algokit-client-generator generate -a ./application.json -o ./client.ts -m minimal\n```\n\n#### Generation Modes\n\nThe generator supports two modes:\n\n**Full Mode (default):**\n\n- Includes factory class for creating and deploying smart contracts\n- Includes deployment types and methods\n- Includes all deployment-related metadata (source code, bytecode, template variables)\n- Includes client class for interacting with already deployed contracts\n- Best for development, deployment and interaction workflows or where output size is less important\n\n**Minimal Mode:**\n\n- Excludes factory class and deployment capabilities\n- Excludes deployment-related metadata to reduce output size\n- Only includes client class for interacting with already deployed contracts\n- Best for scenarios that only need to interact with existing contracts\n\n#### Programmatic API\n\nAlternatively, a client can be generated from code by invoking the `generate` function paired with either `writeDocumentPartsToString` or `writeDocumentPartsToStream` depending on your needs. We also expose helpers to optionally load and validate an application.json file.\n\n```ts\nimport fs from 'fs'\nimport {\n  writeDocumentPartsToStream,\n  writeDocumentPartsToString,\n  generate,\n  loadApplicationJson,\n  validateApplicationJson,\n} from '@algorandfoundation/algokit-client-generator'\nimport appJson from './application.json'\n\nconst appJsonFromFile = loadApplicationJson('./application.json')\nconst appJsonFromObject = validateApplicationJson(appJson)\n\nconst fileStream = fs.createWriteStream('./client.ts', {\n  flags: 'w',\n})\nwriteDocumentPartsToStream(generate(appJsonFromFile), fileStream)\n\n// Generate a full client (default)\nconst clientAsString = writeDocumentPartsToString(generate(appJsonFromObject))\n\n// Generate a minimal client\nconst minimalClientAsString = writeDocumentPartsToString(generate(appJsonFromObject, { mode: 'minimal' }))\n```\n\nFor details on how to use the generated client see the more detailed [usage docs](./docs/usage.md)\n\n## Code Examples\n\nThere are a range of [examples](./examples) that you can look at to see a source smart contract (e.g. `{contract.py}`), the generated client (`client.ts`) and some tests that demonstrate how you can use the client (`client.spec.ts`).\n\n## Contributing\n\nIf you want to contribute to this project the following information will be helpful.\n\n### Initial setup\n\n1. Clone this repository locally\n2. Install pre-requisites:\n\n   - Install `AlgoKit` - [Link](https://github.com/algorandfoundation/algokit-cli#install): Ensure you can execute `algokit --version`.\n   - Bootstrap your local environment; run `algokit bootstrap all` within this folder, which will:\n     - Install `Poetry` - [Link](https://python-poetry.org/docs/#installation): The minimum required version is `1.2`. Ensure you can execute `poetry -V` and get `1.2`+\n     - Run `poetry install` in the root directory, which will set up a `.venv` folder with a Python virtual environment and also install all Python dependencies\n     - Run `npm install`\n\n3. Open the project and start debugging / developing via:\n   - VS Code\n     1. Open the repository root in VS Code\n     2. Install recommended extensions\n     3. Run tests via test explorer\n   - IDEA (e.g. PyCharm)\n     1. Open the repository root in the IDE\n     2. It should automatically detect it's a Poetry project and set up a Python interpreter and virtual environment.\n     3. Run tests\n   - Other\n     1. Open the repository root in your text editor of choice\n     2. Run `npm run test`\n\n### Subsequently\n\n1. If you update to the latest source code and there are new dependencies you will need to run `algokit bootstrap all` again\n2. Follow step 3 above\n\n### Building examples\n\nIn the `examples` folder there is a series of example contracts along with their generated client. These contracts are built using [Algorand Python](https://github.com/algorandfoundation/puya).\n\nIf you want to make changes to any of the smart contract examples and re-generate the ARC-0032 application.json files then change the corresponding `examples/{contract}/{contract}.py` file and then run:\n\n```\npoetry run python -m examples\n```\n\nOr in Visual Studio Code you can use the default build task (Ctrl+Shift+B).\n\nTo regenerate the generated clients run `npm run update-approvals`.\n\n### Continuous Integration / Continuous Deployment (CI/CD)\n\nThis project uses [GitHub Actions](https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions) to define CI/CD workflows, which are located in the [`.github/workflows`](./.github/workflows) folder.\n\n### Approval tests\n\nMaking any changes to the generated code will result in the approval tests failing. The approval tests work by generating a version of client\nand outputting it to `./examples/APP_NAME/client.generated.ts` then comparing to the approved version `./examples/APP_NAME/client.ts`. If you\nmake a change and break the approval tests, you will need to update the approved version by overwriting it with the generated version.\nYou can run `npm run update-approvals` to update all approved clients in one go.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falgorandfoundation%2Falgokit-client-generator-ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falgorandfoundation%2Falgokit-client-generator-ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falgorandfoundation%2Falgokit-client-generator-ts/lists"}