Internal code sharing strategy

[yamcodes]

Status

Proposed

Summary

This RFC defines how ArkEnv should share internal code across the core library and its plugins (@arkenv/vite-plugin, @arkenv/bun-plugin, etc.).

This proposal is independent of Optional ArkType and focuses only on code organization, sharing, and exposure.

---

Motivation

ArkEnv currently relies on internal workspace packages (e.g. @repo/scope, @repo/types) that:

• Are needed by multiple packages
• Are not meant for end users
• Introduce bundling and resolution complexity

As ArkEnv grows, we need a clearer and simpler strategy that avoids unnecessary packages while keeping authoring ergonomic.

---

Goals

• Share internal helpers across ArkEnv packages safely
• Keep the public API intentional and minimal
• Avoid bundler-driven design compromises
• Keep plugin development straightforward

Non-Goals

• Changing validation behavior or runtime semantics
• Solving optional peer dependency handling
• Perfect encapsulation of all internal logic

---

Decision

1. Prefer a Single Core Package

arkenv is the primary place for shared logic.

We will avoid creating internal workspace packages by default. Shared code should live in arkenv unless there is a strong reason otherwise.

---

2. Use Explicit “Internal” Exports

Internal helpers may be exported from arkenv using conventions such as:

• @internal JSDoc annotations
• Internal subpaths (e.g. arkenv/internal/*)

These exports:

• Are not documented
• Are not semver-stable
• May change without notice

This follows established patterns used by Zod and ArkType.

---

3. Plugins Depend on arkenv

ArkEnv plugins:

• Depend on arkenv
• Import shared logic (including internal exports) from arkenv
• Do not introduce a separate shared “plugin core” package

This keeps installation and dependency graphs simple.

---

4. Internal Workspace Packages Are Exceptional

Internal workspace packages should only be used when code:

• Must be shared across multiple published packages
• Cannot reasonably live inside arkenv

They are not the default solution.

---

Trade-offs

Pros

• Simpler repo and build setup
• Fewer packages to maintain
• Easier plugin authoring
• Aligns with ecosystem conventions

Cons

• Internal helpers are technically importable
• Requires discipline to treat internals as unstable

These trade-offs are intentional.

---

Migration

No immediate changes required.

Existing internal packages may be:

• Inlined into arkenv, or
• Replaced with internal exports incrementally

---

Conclusion

ArkEnv will favor a single core package with explicit internal exports over hidden internal packages.

This keeps the system easier to evolve without over-engineering boundaries.