Skip to main content

Installation

Install​

pnpm add hex-di

That's it. The hex-di umbrella package includes everything you need:

  • @hex-di/core — Port token system
  • @hex-di/graph — GraphBuilder and compile-time validation
  • @hex-di/runtime — Container and scopes

React​

pnpm add @hex-di/react

Result (Rust-style error handling)​

pnpm add @hex-di/result

Used by GraphBuilder.tryBuild() and any adapter that returns Result<T, E>.

Testing​

pnpm add -D @hex-di/testing

TypeScript Configuration​

HexDI requires TypeScript 5.0+ with strict: true.

{
  "compilerOptions": {
    "strict": true,
    "moduleResolution": "bundler",
    "target": "ES2022",
    "module": "ESNext"
  }
}

strict: true is required — HexDI's compile-time guarantees depend on it. Without strict mode, the type system cannot enforce structural correctness.

{
  "compilerOptions": {
    "strict": true,
    "strictNullChecks": true,
    "noUncheckedIndexedAccess": true,
    "moduleResolution": "bundler",
    "target": "ES2022",
    "module": "ESNext",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  }
}

Importing​

import {
  port,
  createAdapter,
  GraphBuilder,
  createContainer,
} from "hex-di";

From individual packages​

import { port, createAdapter } from "@hex-di/core";
import { GraphBuilder } from "@hex-di/graph";
import { createContainer } from "@hex-di/runtime";

Both patterns work. The umbrella re-exports everything from the three core packages.

Verify​

// verify-hexdi.ts
import { port, createAdapter, GraphBuilder, createContainer } from "hex-di";

interface Logger {
  log(message: string): void;
}

const LoggerPort = port<Logger>()({ name: "Logger" });

const LoggerAdapter = createAdapter({
  provides: LoggerPort,
  requires: [],
  lifetime: "singleton",
  factory: () => ({
    log: msg => console.log(`[Test] ${msg}`),
  }),
});

const graph = GraphBuilder.create().provide(LoggerAdapter).build();
const container = createContainer({ graph, name: "App" });

container.tryResolve(LoggerPort).match(
  (logger) => { logger.log("HexDI is working!"); },
  (error) => { console.error("Resolution failed:", error); },
);
npx tsx verify-hexdi.ts
# [Test] HexDI is working!

Troubleshooting​

"Cannot find module 'hex-di'" — Run pnpm add hex-di in your project root.

Type errors with strict mode — Add "strict": true to your tsconfig.json. HexDI requires it.

Module resolution errors — Use "moduleResolution": "bundler" or "moduleResolution": "node16".

Next: Core Concepts