Shared Packages in the Akash Console Monorepo: Architecture and Usage Guide

The Akash Console monorepo organizes twelve shared packages under the packages/ directory that supply reusable UI components, type-safe networking layers, database schemas, and development tooling to unify the provider console, deployment web interface, and transaction signer applications.

The akash-network/console repository structures its codebase as a monorepo, consolidating reusable libraries in the packages/ directory to ensure consistency across frontend and backend applications. These shared packages in the Akash Console monorepo eliminate code duplication by encapsulating everything from React component libraries to protobuf-generated RPC clients, serving as dependencies for apps like apps/provider-console, apps/deploy-web, and apps/tx-signer.

Overview of the Shared Package Architecture

The monorepo places all shared code in the repository root under packages/, with each directory representing an independent npm package prefixed with @akashnetwork/. Applications consume these packages via workspace references defined in package.json, ensuring that updates to core logic propagate consistently across the entire codebase. This architecture separates concerns into distinct layers: user interface primitives, data access abstractions, state management utilities, observability services, and build automation tools.

Core Shared Packages and Their Purposes

The following packages provide the foundational functionality used throughout the Akash Console ecosystem.

UI and Frontend Primitives

@akashnetwork/ui exports React components, Tailwind CSS configurations, hooks, and context providers used across console frontends. Located in packages/ui/, this library ensures visual consistency between the provider console and deployment web interfaces. The package entry point at packages/ui/components/index.tsx exposes all available UI primitives.

@akashnetwork/react-query-proxy serves as a thin abstraction layer that re-exports types and utilities from @tanstack/react-query. Defined in packages/react-query-proxy/package.json, this proxy enables consistent import paths throughout the monorepo while centralizing version management for the query library.

Data Fetching and Networking

@akashnetwork/react-query-sdk provides auto-generated React Query hooks based on Akash OpenAPI definitions. Located in packages/react-query-sdk/, this package offers type-safe data-fetching utilities that applications import to interact with backend services, such as useGetDeployments from src/notifications/index.ts.

@akashnetwork/http-sdk wraps axios with Akash-specific request handling, implementing retry policies via cockatiel and runtime schema validation using zod. The main client exports from packages/http-sdk/src/index.ts provide a configured axios instance with interceptors for authentication and error handling.

@akashnetwork/net contains core networking utilities generated from Akash protobuf definitions. Stored in packages/net/, this package supplies RPC and REST call helpers that SDKs use to communicate with the Akash blockchain, including network configuration getters like getNetworkConfig.

State Management and Configuration

@akashnetwork/network-store implements browser-based storage for network selection using jotai atoms. The implementation in packages/network-store/src/network.store.ts persists the active network configuration and metadata, allowing users to switch between mainnet and testnet seamlessly across applications.

@akashnetwork/env-loader handles environment variable discovery and loading from .env* files using dotenvx. Located in packages/env-loader/, this package exposes a CLI command (detect-env-files) that ensures correct environment configuration across development and production deployments.

Observability and Persistence

@akashnetwork/logging delivers centralized, structured logging built on pino with optional OpenTelemetry integrations. The service defined in packages/logging/src/services/logger/logger.service.ts supports trace emission via hono and otel bindings for external collector ingestion.

@akashnetwork/database centralizes Sequelize models, migrations, and TypeScript schema definitions. Located in packages/database/, this package powers multiple console services with shared database logic, exposing model definitions from packages/database/dbSchemas/index.ts to prevent schema duplication.

Build and Release Tooling

@akashnetwork/dev-config standardizes development configurations across the monorepo, bundling ESLint, Prettier, and TypeScript settings. The package in packages/dev-config/ also includes a custom ESLint plugin (eslint-plugin-akash) that enforces project-specific coding standards.

@akashnetwork/docker provides utility scripts for container orchestration, exporting binary commands like dc and build-image from packages/docker/package.json. These scripts streamline Docker image creation in CI pipelines and local development environments.

@akashnetwork/releaser manages release automation and changelog generation. Located in packages/releaser/, this package contains console-specific Docker files and scripts that handle version bumping and release note creation.

How Shared Packages Interact in the Monorepo

The packages form distinct architectural layers that applications compose into complete feature implementations.

1. Presentation Layer – @akashnetwork/ui supplies React components and styling primitives that render the user interface consistently across apps/deploy-web and apps/provider-console.

2. Data Access Layer – @akashnetwork/http-sdk handles low-level HTTP communication, while @akashnetwork/react-query-sdk provides cached, type-safe query hooks. @akashnetwork/net supplies the underlying protobuf-generated RPC clients for blockchain interaction.

3. State Layer – @akashnetwork/network-store persists user preferences such as selected network chains, while @akashnetwork/env-loader injects runtime configuration variables required by backend services.

4. Observability Layer – @akashnetwork/logging emits structured logs and distributed traces, enabling monitoring across microservices and frontend applications.

5. Persistence Layer – @akashnetwork/database ensures data consistency by sharing Sequelize models between the API server and background workers.

6. Tooling Layer – @akashnetwork/dev-config enforces code quality, while @akashnetwork/docker and @akashnetwork/releaser automate deployment artifacts.

Practical Implementation Examples

The following snippets demonstrate how applications import and utilize these shared packages.

Consuming Generated Query Hooks

Applications fetch deployment data using type-safe hooks from the React Query SDK:

// src/pages/Deployments.tsx
import { useGetDeployments } from '@akashnetwork/react-query-sdk/notifications';

export function Deployments() {
  const { data, isLoading } = useGetDeployments();
  return isLoading ? <Spinner /> : <DeploymentList data={data} />;
}

Source: packages/react-query-sdk/src/notifications/index.ts

Managing Network Selection

The network store persists chain configuration using Jotai atoms:

import { networkStore } from '@akashnetwork/network-store';
import { getNetworkConfig } from '@akashnetwork/net';

async function switchToNetwork(networkId: string) {
  const config = await getNetworkConfig(networkId);
  networkStore.set(config);
}

Source: packages/network-store/src/network.store.ts

Making HTTP Requests

The HTTP SDK provides a configured axios instance with automatic retries:

import { apiClient } from '@akashnetwork/http-sdk';

async function fetchBalance(address: string) {
  const response = await apiClient.get(`/v1/balance/${address}`);
  return response.data;
}

Source: packages/http-sdk/src/index.ts

Structured Logging with Tracing

Services emit logs using the centralized logger with optional OpenTelemetry context:

import { logger } from '@akashnetwork/logging';

logger.info('Deployment initiated', { deploymentId, userAddress });

Source: packages/logging/src/services/logger/logger.service.ts

Key Source Files to Explore

Developers extending these packages should examine the following entry points:

• UI Components: packages/ui/components/index.tsx
• Network State: packages/network-store/src/network.store.ts
• HTTP Client: packages/http-sdk/src/index.ts
• Logging Service: packages/logging/src/services/logger/logger.service.ts
• Database Models: packages/database/dbSchemas/index.ts

These files define the public APIs consumed by applications throughout the akash-network/console repository.

Summary

• The Akash Console monorepo organizes twelve shared packages under packages/ to prevent code duplication across frontend and backend applications.
• UI and networking are handled by @akashnetwork/ui, @akashnetwork/react-query-sdk, @akashnetwork/http-sdk, and @akashnetwork/net, providing type-safe components and API clients.
• State and configuration management relies on @akashnetwork/network-store (browser storage) and @akashnetwork/env-loader (environment variables).
• Observability is centralized through @akashnetwork/logging with structured Pino logs and optional OpenTelemetry tracing.
• Database consistency is enforced by @akashnetwork/database, which shares Sequelize models across services.
• Development tooling includes @akashnetwork/dev-config for linting/formatting and @akashnetwork/docker for container orchestration.

Frequently Asked Questions

What is the purpose of the @akashnetwork/react-query-proxy package?

@akashnetwork/react-query-proxy re-exports types and utilities from @tanstack/react-query to provide a centralized import path throughout the monorepo. This abstraction allows maintainers to upgrade React Query versions or modify type exports in a single location without refactoring import statements across multiple applications.

How does the Akash Console handle database schema consistency across services?

The @akashnetwork/database package centralizes all Sequelize models, migrations, and TypeScript schema definitions in packages/database/. By importing database logic from this shared package, services like the API server and background workers operate against identical schema definitions, preventing drift and ensuring migration consistency.

Which package manages environment variable loading in the monorepo?

@akashnetwork/env-loader handles environment configuration using dotenvx to load variables from .env* files. The package exposes a CLI command (detect-env-files) that runs during application startup to ensure the correct environment variables are available across development, staging, and production deployments.

How is logging standardized across Akash Console applications?

@akashnetwork/logging provides a centralized logging service built on pino that exports a consistent logger interface from packages/logging/src/services/logger/logger.service.ts. The package optionally integrates OpenTelemetry via hono and otel bindings, allowing both frontend and backend services to emit structured logs and distributed traces to external collectors.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}