vf-module-development

Veryfront Module Development

Overview

Veryfront has 45+ modules in src/, organized in strict dependency layers. Each module has a clear public API via barrel exports.

Core principle: Modules communicate through their public API. Never import from another module's internals.

Dependency Layers

Layer 5 (top):    Orchestrators  → server/, proxy/, build/, cli/
Layer 4:          Features       → data/, html/, react/, rendering/
Layer 3:          Module System  → modules/, transforms/, cache/
Layer 2:          Infrastructure → security/, routing/, middleware/
Layer 1 (bottom): Foundation     → config/, types/, utils/, errors/, platform/

Rules:

• A module may only import from its own layer or lower layers
• Never import upward (e.g., Foundation must not import from Features)
• Validate with: deno task validate:architecture

Module Structure

src/my-module/
├── index.ts              # Public API (barrel exports only)
├── index.test.ts         # Export verification test
├── types.ts              # Public types and interfaces
├── implementation.ts     # Core logic
├── factory.ts            # Factory functions (if needed)
├── utils.ts              # Module-internal utilities
└── sub-feature/          # Sub-directories for complex modules
    ├── index.ts
    └── implementation.ts

Hash Imports

All internal imports use hash-based aliases defined in deno.json:

// Correct
import { VeryfrontError } from "#veryfront/errors";
import { defineConfig } from "#veryfront/config";
import { logger } from "#veryfront/utils/logger";

// Wrong - never use relative paths across modules
import { VeryfrontError } from "../../errors/types.ts";

Within the same module, use relative imports:

// Within src/my-module/
import { MyType } from "./types.ts";
import { helper } from "./utils.ts";

Barrel Exports (index.ts)

Every module's index.ts is its public API:

// src/my-module/index.ts

// Re-export public types
export type { MyConfig, MyOptions } from "./types.ts";

// Re-export public functions/constants
export { createMyThing } from "./factory.ts";
export { MY_ERROR_CONSTANT } from "#veryfront/errors";