// @ozaco/devkit

Resolve

Unplugin factories that rewrite the `std:`/`server:`/`db:`/`ai:`/`cli:` aliases to the real `@ozaco/*` packages.

import from@ozaco/devkit/resolve

The resolve module ships unplugin factories that rewrite ozaco's bare-specifier aliases — std:*, server:*, db:*, ai:* and cli:* — to the real @ozaco/* packages during a bundler build. Each factory is a UnpluginInstance, so it plugs into any unplugin-compatible bundler through its adapters (.rolldown(), .vite(), .rollup(), .webpack(), .rspack(), .esbuild(), .farm()).

These plugins are the build-time counterpart of devkit's . export, ambient.d.ts. That ambient declaration file makes the same specifiers typecheck: it declares each alias module (e.g. declare module 'std:result') and re-exports the matching @ozaco/* subpath, so import { succeed } from 'std:result' resolves to @ozaco/std/result in the type system. The resolve plugins are what make those specifiers resolve for real when the code is bundled.

By default each resolver maps an alias to the published package path (e.g. std:result -> @ozaco/std/result) and marks the target external, leaving it as a bare import in the output. Pass sourceDir and the alias instead maps to the on-disk source file under that directory (e.g. std:result -> <sourceDir>/result/index.ts) and is bundled inline — the mode used to build directly from monorepo source. Specifiers that match no alias are passed through untouched.

// on this page

Package resolvers Custom aliases Types

Package resolvers

One `UnpluginInstance` per ozaco package, each owning that package’s alias namespace.

const

stdResolve

Resolve `std:*` aliases to `@ozaco/std/*` (or to local source with `sourceDir`).

signature

const stdResolve: UnpluginInstance<ResolveOptions | undefined, false>

// register through the adapter for your bundler:
stdResolve.rolldown(options?: ResolveOptions)

Rewrites every std: specifier devkit knows about — std:result, std:effect, std:io, std:io/impl/node, std:codec/impl/json, std:logger/transport/file, std:config, and the rest — to its @ozaco/std subpath. Without sourceDir the targets stay external; with sourceDir they point at the real .ts sources and are bundled inline.

example

import { stdResolve } from '@ozaco/devkit/resolve'

// tsdown.config.ts — std:* stays external as @ozaco/std/*
export default defineConfig({
  plugins: [stdResolve.rolldown()],
})

// build from monorepo source instead (inlines the real .ts files)
stdResolve.rolldown({ sourceDir: '../std/src' })

const

serverResolve

Resolve `server:*` aliases to `@ozaco/server/*`.

signature

const serverResolve: UnpluginInstance<ResolveOptions | undefined, false>

serverResolve.rolldown(options?: ResolveOptions)

Owns the server: namespace: server:core, the transport/* (nats, worker) and policy/* (bucket, retry, cache, circuit-breaker, bulk, timeout, fallback, metrics) subpaths, the gateway/* and plugin/* entries, plus server:client and server:daemon. External by default; pass sourceDir to resolve to and bundle the local sources.

const

dbResolve

Resolve `db:*` aliases to `@ozaco/db` and its impl subpaths.

signature

const dbResolve: UnpluginInstance<ResolveOptions | undefined, false>

dbResolve.rolldown(options?: ResolveOptions)

Maps db:core to the @ozaco/db package root and db:impl/sqlite / db:impl/postgres to their respective subpaths. External by default; sourceDir switches to the on-disk sources.

const

aiResolve

Resolve `ai:*` aliases to `@ozaco/ai/*`.

signature

const aiResolve: UnpluginInstance<ResolveOptions | undefined, false>

aiResolve.rolldown(options?: ResolveOptions)

Maps ai:core to @ozaco/ai/core and ai:impl/openai to @ozaco/ai/impl/openai. External by default; sourceDir resolves to and bundles the local sources.

const

cliResolve

Resolve `cli:*` aliases to `@ozaco/cli/*`.

signature

const cliResolve: UnpluginInstance<ResolveOptions | undefined, false>

cliResolve.rolldown(options?: ResolveOptions)

Owns the cli: namespace: cli:core, cli:palette, cli:prompt, cli:spinner, cli:command, cli:table and cli:terminal/bun. External by default; pass sourceDir to resolve to the local sources and bundle them.

Custom aliases

The generic primitive the package resolvers are built on.

const

resolveAlias

Generic specifier-to-module resolver driven by an explicit alias map.

signature

const resolveAlias: UnpluginInstance<ResolveAliasOptions, false>

resolveAlias.vite(options: ResolveAliasOptions)

The building block behind every package resolver. Give it an aliases map (specifier -> target module id); any import matching a key is rewritten to its target and everything else is passed through untouched. Set external: true to leave the resolved targets as bare imports instead of bundling them.

example

import { resolveAlias } from '@ozaco/devkit/resolve'

resolveAlias.rolldown({
  aliases: { 'app:config': '@myorg/app/config' },
  external: true,
})

Types

iface

ResolveOptions

Options shared by every per-package resolver.

signature

interface ResolveOptions {
  sourceDir?: string
}

sourceDir switches between two modes. Omitted, each alias resolves to the published @ozaco/* package path and is kept external. Set, each alias resolves to the matching source file under sourceDir and is bundled inline — the shape used to build from monorepo source.

iface

ResolveAliasOptions

Options for `resolveAlias`: the alias map and externality flag.

signature

interface ResolveAliasOptions {
  aliases: Record<string, string>
  external?: boolean
}

aliases maps each specifier to the module id it should resolve to. external (default false) marks every matched target as external so the bundler leaves it as a bare import.