Skip to content

docs: document how to install the alpha packages #90

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: document how to install the alpha packages #90

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 68 additions & 0 deletions packages/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
# Language Specific Packages

This section of the monorepo contains the language specific published packages which may or may not be built from shared rust code.

## Installation

Whilst we are building out the capabilities, we will likely be making a lot of breaking changes.
As such we will only be releasing alpha versions of the packages for integration with internal tooling.
At this point anything is open to change, so because of that we'll only publish these packages to internal package sources.

See below for the installation instructions for each supported language:

### Python

The Python packages are published as wheels on the GitHub release. These can be installed directly.

For a binary wheel with multiple target platforms like [algokit_transact](https://github.com/algorandfoundation/algokit-core/releases/tag/python%2Falgokit_transact%401.0.0-alpha.1), you can use the below config.

```toml
[tool.poetry.dependencies]
algokit_transact = [
{ url = "https://github.com/algorandfoundation/algokit-core/releases/download/python%2Falgokit_transact%401.0.0-alpha.1/algokit_transact-1.0.0a1-py3-none-macosx_10_12_x86_64.whl", markers = "sys_platform == 'darwin' and platform_machine == 'x86_64'" },
{ url = "https://github.com/algorandfoundation/algokit-core/releases/download/python%2Falgokit_transact%401.0.0-alpha.1/algokit_transact-1.0.0a1-py3-none-macosx_11_0_arm64.whl", markers = "sys_platform == 'darwin' and platform_machine == 'arm64'" },
{ url = "https://github.com/algorandfoundation/algokit-core/releases/download/python%2Falgokit_transact%401.0.0-alpha.1/algokit_transact-1.0.0a1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", markers = "sys_platform == 'linux' and platform_machine == 'x86_64'" },
{ url = "https://github.com/algorandfoundation/algokit-core/releases/download/python%2Falgokit_transact%401.0.0-alpha.1/algokit_transact-1.0.0a1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", markers = "sys_platform == 'linux' and platform_machine == 'aarch64'" },
{ url = "https://github.com/algorandfoundation/algokit-core/releases/download/python%2Falgokit_transact%401.0.0-alpha.1/algokit_transact-1.0.0a1-py3-none-win_amd64.whl", markers = "sys_platform == 'win32' and platform_machine == 'AMD64'" }
]
```

For a non binary wheel like [algod_api](https://github.com/algorandfoundation/algokit-core/releases/tag/python%2Falgod_api%401.0.0-alpha.2), you can use the below config.

```toml
[tool.poetry.dependencies]
algokit_algod_api = { url = "https://github.com/algorandfoundation/algokit-core/releases/download/python%2Falgod_api%401.0.0-alpha.2/algokit_algod_api-1.0.0a2-py3-none-any.whl" }
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Installing like this works fine but, for some reason I don't yet understand, the wheel doesn't bring a list of dependencies with it yet.

I installed this and it didn't ask the package manager to install pydantic, for example

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This may be why: https://github.com/orgs/python-poetry/discussions/9479#discussioncomment-9741142

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Which means that the generated algod client should import algokit transact from a non-local source CC: @aorumbayev

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if it's this space here https://github.com/algorandfoundation/algokit-core/blob/main/packages/python/algod_api/pyproject.toml#L16

```

### TypeScript

The TypeScript packages are published to the GitHub packages NPM repository.

For example [algokit_transact](https://github.com/algorandfoundation/algokit-core/pkgs/npm/algokit-transact).

GitHub packages (the product) has some constaints, namely:

- It requires authentication to install a package
- It enforce packages scopes, which must match the GitHub username (`algorandfoundation` in our case).

Unfortunately for us, the package scope in GitHub packages matches the official NPM registry and NPM itself does not support configuring multiple registries for a single package scope, so we need to be a little crafty when installing/updating the alpha packages we're installing from GitHub packages.

To install, follow the below:

1. Create a new [personal access token](https://github.com/settings/tokens/new) with `read:packages` permission and your preference of expiration time.
2. Add the following to `~/.npmrc`:

```
@algorandfoundation:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken={TOKEN}
```

3. Install the package hosted in GitHub packages, which will update your NPM package lock file.

```
npm install @algorandfoundation/algokit-transact@1.0.0-alpha.4
```

4. Remove `@algorandfoundation:registry=https://npm.pkg.github.com` from `~/.npmrc`, so NPM hosted `@algorandfoundation` packages can be resolved.

Note: You will need to perform steps 2-4 each time your either install a package for the first time or update a GitHub package hosted dependency. Installing from the lock file only requires the token.
Copy link
Collaborator

@PatrickDinh PatrickDinh May 19, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm wondering if we can reduce the manual steps by:

  • instead of using the global .npmrc, we can create a file within the repo, maybe call it .github-npm-rc (I can't think of a better name).
  • The content of the file is 
    @algorandfoundation:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken={TOKEN}
  • Of course, we should add this file to git ignore.
  • Update the install script to
$env:NPM_CONFIG_USERCONFIG=".algokit-core-alpharc"
npm install --save @algorandfoundation/algokit-transact@1.0.0-alpha.4
Remove-Item Env:NPM_CONFIG_USERCONFIG

Note: The above script only works for PowerShell. It set the environment variable NPM_CONFIG_USERCONFIG so that npm install can pick up the right file, then it unsets the env var.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah we could do something like that. Worth noting that this applies when installing the package in some other repo like utils-ts, so it may be better placed in that repo.

Another option that may work (would need to test) is to drop an .npmrc in the target repo (e.g. utils-ts) with a commented out #@algorandfoundation:registry=https://npm.pkg.github.com line. You can then conditionally uncomment, which saves touching the user .npmrc.

Copy link
Collaborator

@PatrickDinh PatrickDinh May 22, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Another option that may work (would need to test) is to drop an .npmrc in the target repo (e.g. utils-ts) with a commented out #@algorandfoundation:registry=https://npm.pkg.github.com line. You can then conditionally uncomment, which saves touching the user .npmrc.

I tested this option, it works. I think this is nice:

  • We can store the token at the global level
//npm.pkg.github.com/:_authToken={TOKEN}
  • In the target project, we create .npmrc file which has
@algorandfoundation:registry=https://npm.pkg.github.com

Then we can comment it out if we don't need it.