DEV Community

Asha Alcazar
Asha Alcazar

Posted on

Getting Started with AlgoKit 3.0 on macOS: A Practical Walkthrough

#algorand

Getting Started with AlgoKit 3.0 on macOS: A Practical Walkthrough

If you've been curious about building on Algorand but haven't found a clean entry point, AlgoKit 3.0 is worth your time. This post walks through the macOS onboarding flow and what you can expect when you initialize your first project.

What is AlgoKit?

AlgoKit is the official developer toolkit for Algorand. It handles local environment setup, project scaffolding, smart contract compilation, testing, and deployment workflows. Think of it as the opinionated starting point that removes the friction between "I want to build on Algorand" and "I have a running local environment with a real project structure."

Version 3.0 brings a cleaner CLI experience, tighter TypeScript SDK integration, and improved project templates.

Prerequisites

Before you run anything, make sure you have:

  • macOS (Apple Silicon or Intel both work)
  • Python 3.12+ (AlgoKit itself is Python-based)
  • pipx (recommended for isolated CLI installs)
  • Docker Desktop (for running a local Algorand network via AlgoKit LocalNet)
  • Node.js 20+ (if you're using TypeScript templates, which you should be)

Check your versions:

python3 --version
node --version
docker --version
Enter fullscreen mode Exit fullscreen mode

Step 1: Install AlgoKit

The cleanest install path on macOS uses pipx:

brew install pipx
pipx ensurepath
pipx install algokit
Enter fullscreen mode Exit fullscreen mode

Verify the install:

algokit --version
Enter fullscreen mode Exit fullscreen mode

You should see something like algokit, version 3.x.x. If the command isn't found, restart your terminal or run pipx ensurepath again and reload your shell config.

Step 2: Bootstrap your environment

AlgoKit includes a doctor command that checks your environment for missing dependencies:

algokit doctor
Enter fullscreen mode Exit fullscreen mode

This will flag anything missing, like Docker not running or a Node version mismatch. Fix those before moving forward. The doctor output is clear and actionable, which makes it genuinely useful rather than just decorative.

Step 3: Initialize a project

This is where AlgoKit 3.0 shines. The init command walks you through project scaffolding interactively:

algokit init
Enter fullscreen mode Exit fullscreen mode

You'll be prompted to:

  1. Choose a project type (smart contract, full-stack dApp, or custom)
  2. Choose your language (TypeScript or Python)
  3. Name your project
  4. Configure optional features like linting and testing setup

For most developers starting out, the TypeScript smart contract template is the right choice. It gives you:

  • A pre-configured AlgoKit project structure
  • TypeScript SDK wiring out of the box
  • A local test harness using @algorandfoundation/algokit-utils
  • Vitest for unit testing

Step 4: Start LocalNet

AlgoKit LocalNet runs a sandboxed Algorand network locally using Docker. Start it with:

algokit localnet start
Enter fullscreen mode Exit fullscreen mode

This spins up a local node, indexer, and KMD (key management daemon). You get a fully functional Algorand environment without touching mainnet or testnet.

Check that it's running:

algokit localnet status
Enter fullscreen mode Exit fullscreen mode

Step 5: Explore the project structure

After algokit init, your project will look roughly like this:

my-project/
  contracts/
    hello_world/
      contract.ts       # Smart contract logic
      deploy-config.ts  # Deployment configuration
  tests/
    hello_world.test.ts
  package.json
  algokit.toml
  .algokit/
Enter fullscreen mode Exit fullscreen mode

The algokit.toml file is the project manifest. It tells AlgoKit how to build, deploy, and test your contracts.

Step 6: Build and deploy locally

Compile your contract:

algokit project run build
Enter fullscreen mode Exit fullscreen mode

Deploy to LocalNet:

algokit project deploy localnet
Enter fullscreen mode Exit fullscreen mode

If everything is wired correctly, you'll see a deployment transaction confirmed on your local network. That's your first smart contract live in a real Algorand environment.

A note on the TypeScript SDK

The TypeScript SDK (@algorandfoundation/algokit-utils and the core algosdk package) is the primary way to interact with Algorand from application code. AlgoKit project templates wire this up for you, but it's worth understanding what's happening under the hood.

A basic client interaction looks like this:

import { AlgorandClient } from '@algorandfoundation/algokit-utils'

const algorand = AlgorandClient.fromEnvironment()

const accountInfo = await algorand.account.getInformation('YOUR_ADDRESS')
console.log(accountInfo)
Enter fullscreen mode Exit fullscreen mode

AlgorandClient.fromEnvironment() reads your environment variables (set by

Top comments (0)