AlgoKit Project Bootstrap | Algorand Developer Portal

AlgoKit Project Bootstrap

The AlgoKit Project Bootstrap feature allows you to bootstrap different project dependencies by looking up specific files in your current directory and immediate subdirectories by convention.

This is useful to allow for expedited initial setup for each developer e.g. when they clone a repository for the first time. It’s also useful to provide a quick getting started experience when initializing a new project via AlgoKit Init and meeting our goal of “nothing to debugging code in 5 minutes.”

It can bootstrap one or all of the following (with other options potentially being added in the future):

Note: Invoking bootstrap from algokit bootstrap is not recommended. Please prefer using algokit project bootstrap instead.

You can configure which package managers are used by default via:

For more details, see the configuration documentation.

Package Manager Override

You can override the default package manager settings on a per-project basis by adding configuration to your project’s .algokit.toml file:

[package_manager]

python = "uv"        # Override Python package manager (poetry or uv)

javascript = "pnpm"  # Override JavaScript package manager (npm or pnpm)

This project-specific configuration takes precedence over your global settings, allowing different projects to use different package managers as needed.

Configuration Precedence

The bootstrap command follows this precedence order when determining which package manager to use:

  1. Project override - Configuration in .algokit.toml (highest priority)
  2. User preference - Global configuration set via algokit config (respects your explicit choice)
  3. Smart defaults - Based on project structure (e.g., poetry.toml → Poetry, pnpm-lock.yaml → PNPM)
  4. Interactive prompt - Asked on first use if no preference is set

This means if you set a global preference (e.g., algokit config py-package-manager uv), it will be used across all projects unless explicitly overridden at the project level. Smart defaults only apply when you haven’t set a preference yet.

Package Manager Command Translation

During the bootstrap process, AlgoKit automatically translates package manager commands in your project’s .algokit.toml file to match your configured package manager preferences. This ensures that project run commands work correctly regardless of which package manager the template was originally created with.

How It Works

When you run algokit project bootstrap, if your project contains run commands in .algokit.toml, they will be automatically updated:

JavaScript Translation (npm ↔ pnpm)

Commands that translate:

Commands that DON’T translate (will show a warning):

Python Translation (poetry ↔ uv)

Only commands with equivalent semantics are translated:

Commands that translate:

Commands that DON’T translate (will show a warning):

When AlgoKit encounters a command that cannot be translated, it will:

  1. Leave the command unchanged in .algokit.toml
  2. Display a warning message explaining that the command has no equivalent
  3. The command may not work when executed with algokit project run

Example

Given a .algokit.toml with:

[project.run]

build = { commands = ["npm run build"] }

create = { commands = ["npx create-next-app"] }  # Different behavior in pnpm

test = { commands = ["poetry run pytest"] }

deps = { commands = ["poetry show --tree"] }  # No uv equivalent

If you’ve configured:

After bootstrap:

[project.run]

build = { commands = ["pnpm run build"] }        # ✅ Translated

create = { commands = ["npx create-next-app"] }   # ⚠️ Not translated (warning shown)

test = { commands = ["uv run pytest"] }          # ✅ Translated

deps = { commands = ["poetry show --tree"] }     # ⚠️ Not translated (warning shown)

You’ll see warnings:

⚠️ Command 'npx create-next-app' behaves differently in pnpm. Consider using 'pnpm exec' for local binaries or 'pnpm dlx' for remote packages. The command will remain unchanged.

⚠️ Command 'poetry show --tree' has no direct equivalent in uv. The command will remain unchanged and may not work as expected.

This approach ensures your project commands work correctly while being transparent about limitations.

Usage

Available commands and possible usage as follows:

$ ~ algokit project bootstrap

Usage: algokit project bootstrap [OPTIONS] COMMAND [ARGS]...

Options:

-h, --help  Show this message and exit.

Commands:

all     Bootstrap all aspects of the current directory and immediate subdirectories by convention.

env     Bootstrap .env file in the current working directory.

npm     Bootstrap Node.js project in the current working directory.

poetry  Bootstrap Python Poetry and install in the current working directory.

Functionality

Bootstrap .env file

The command algokit project bootstrap env runs two main tasks in the current directory:

For instance, a sample .env.template file as follows:

SERVER_URL=https://myserver.com

# This is a mandatory field to run the server, please enter a value

# For example: 5000

SERVER_PORT=

Running the algokit project bootstrap env command while the above .env.template file in the current directory will result in the following:

$ ~ algokit project bootstrap env

Copying /Users/me/my-project/.env.template to /Users/me/my-project/.env and prompting for empty values

# This is a mandatory field to run the server, please enter a value value

# For example: 5000

? Please provide a value for SERVER_PORT:

And when the user enters a value for SERVER_PORT, a new .env file will be created as follows (e.g. if they entered 4000 as the value):

SERVER_URL=https://myserver.com

# This is a mandatory field to run the server, please enter a value

# For example: 5000

SERVER_PORT=4000

Bootstrap Node.js project

The command algokit project bootstrap npm installs Node.js project dependencies if there is a package.json file in the current directory by running npm install command to install all node modules specified in that file. However, when running in CI mode with present package-lock.json file (either by setting the CI environment variable or using the --ci flag), it will run npm ci instead, which provides a cleaner and more deterministic installation. If package-lock.json is missing, it will show a clear error message and resolution instructions. If you don’t have npm available it will show a clear error message and resolution instructions.

Here is an example outcome of running algokit project bootstrap npm command:

$ ~ algokit project bootstrap npm

Installing npm dependencies

npm:

npm: added 17 packages, and audited 18 packages in 3s

npm:

npm: 2 packages are looking for funding

npm: run `npm fund` for details

npm:

npm: found 0 vulnerabilities

Bootstrap Python poetry project

The command algokit project bootstrap poetry does two main actions:

Here is an example of running algokit project bootstrap poetry command:

$ ~ algokit project bootstrap poetry

Installing Python dependencies and setting up Python virtual environment via Poetry

poetry:

poetry: Installing dependencies from lock file

poetry:

poetry: Package operations: 1 installs, 1 update, 0 removals

poetry:

poetry: • Installing pytz (2022.7)

poetry: • Updating copier (7.0.1 -> 7.1.0a0)

poetry:

poetry: Installing the current project: algokit (0.1.0)

Bootstrap all

Execute algokit project bootstrap all to initiate algokit project bootstrap env, algokit project bootstrap npm, and algokit project bootstrap poetry commands within the current directory and all its immediate sub-directories. This comprehensive command is automatically triggered following the initialization of a new project through the AlgoKit Init command.

Filtering Options

The algokit project bootstrap all command includes flags for more granular control over the bootstrapping process within AlgoKit workspaces:

These new flags enhance the flexibility and efficiency of the bootstrapping process, enabling developers to tailor the setup according to project-specific needs.