SuperAPI AI Directory

setup-ts-deep-modules

Coding & development

View repository

Updated 10-16 09:29

About this skill

Setup TS Deep Modules

Make every package in the repo a deep module: hide a large amount of behaviour behind a small interface. A package's public surface is its entry points(the files in the package root); all subfolders are hidden. This skill installs dependency-cruiser, adds rules enforcing access only through entry points, and proves that these rules actually block violations.

The vocabulary (deep module, interface, seam, depth) comes from invoking the Skill tool and specifying codebase-design; use its language throughout.

The shape this enforces

src/packages/
  <name>/
    index.ts        ← an entry point (public). Import this from outside.
    client.ts       ← another entry point. Packages may expose SEVERAL.
    lib/            ← implementation: hidden from outside, free to import each other.
    tests/          ← co-located tests + fixtures (a subfolder, so private).

The public surface is the package's root files, not a single designated index.ts. By convention, implementation goes in lib/and tests go in tests/, so that all packages adopt the same two-folder shape. The rule itself is generic:any content in aanysubfolder is private, so the config never needs to be extended to add a new folder.

Four rules, all error:

  1. Entry-point boundary — code outside the package (app code or another package) can only import that package's entry points (root files), and cannot import anything in a subfolder.
  2. Intra-package freedom — the package's own files can freely import each other.
  3. Tests through the entry points — <pkg>/tests/ can import any package's entry points and its own tests/ fixtures, but cannot import any package's subfolder internals (including its own). Cross-package integration tests are allowed; deep imports are not.
  4. No cycles — dependency cycles are not allowed.

Entry points, not a barrel. The public surface is every root file, so a package can provide multiple small entry points (index.ts、client.ts、server.ts), without having to funnel everything into a giant index.ts. Barrel files that re-export an entire subtree are discouraged; entry points should be small, with the implementation hidden in subfolders.

Layering (which packages may depend on which) is a separate concern; keep a commented stub in the config, to be filled in by the current repo.

Steps

1. Detect the environment

  • Package manager — pnpm-lock.yaml → pnpm,yarn.lock → yarn,bun.lockb → bun, otherwise npm. Every subsequent command uses it (pnpm/yarn/npm run/bunx)。
  • Packages root — if src/ exists use src/packages, otherwise use packages. If the repo already has an obviously different convention, confirm with the user.
  • Existing config — check the .dependency-cruiser.* file. If it exists, do not overwrite it; merge the four rules and options, and explain what was added.

Done when: package manager, packages root, and existing-config status are all explicit.

2. Install dependency-cruiser

Using the detected package manager, install dependency-cruiser as a devDependency.

Done when: dependency-cruiser appears in devDependencies。

3. Write the config

Copy dependency-cruiser.config.cjs to the repo root, naming it .dependency-cruiser.cjs. Set PACKAGES_ROOT to the root detected in step 1. The rules are based on path depth and are extension-independent, so no other adjustments are needed.

Done when: .dependency-cruiser.cjs exists,PACKAGES_ROOT is correct, and it contains the four forbidden rules.

4. Wire it into the checks

  • Add lint:boundaries script:depcruise <packages-root>(or depcruise src)。
  • include it in the umbrella check command the repo already runs typecheck with (such as check / ci / validate). Do not modify tsconfig or add path aliases.
  • If there is no umbrella script, add lint:boundaries, and tell the user to add it to CI.

Done when: lint:boundaries exists, and runs from the same command as typecheck.

5. Scaffold the example package

Create and commit a <packages-root>/example/ as a copy-me template:

  • index.ts — an entry point that exports a function delegating to an internal file, so the package is clearly a deep, not a pass-through.
  • lib/impl.ts — subfolder in the internal file, imported by index.ts , inaccessible from outside.
  • tests/example.test.ts — only import ../index(entry point), and assert against the public function.

Tell the user this is a starter template that can be copied or deleted.

Done when: example package exists, exposes behaviour through the root entry point, and keeps the impl hidden in a subfolder.

6. Prove the rules bite

This is the completion criterion for the whole skill; a config that cannot fail on a violation is worthless.

  1. Run lint:boundaries, the clean example must pass。
  2. temporarily add a deep import to tests/example.test.ts , for example import { thing } from "../lib/impl". Run lint:boundariesagain, it must tests-through-entrypoints fail。
  3. Revert the deep import, run once more, it must pass。

Done when: passed, failed on deep import, and passed again after reverting has been observed. If Step 2 does not fail, fix the wiring first; you cannot complete the task.

7. Document the convention

In the packages folder (<packages-root>/README.md), write README.md, covering:src/packages/<name>/ layout (entry points in root,lib/ for implementation,tests/ for tests), "import only through the package's entry points (root files)", and how to run lint:boundaries. Explicitly discourage barrel files, use multiple small entry points rather than re-exporting the entire subtree from one index. Keep the content to the copy-me snippet plus one paragraph for each of the four rules.

Then point to it from the repo's agent-instructions file: prefer CLAUDE.md, otherwise AGENTS.md; if neither exists, create AGENTS.md. One line is enough, for example:Packages are deep modules — see [src/packages/README.md](./src/packages/README.md) before adding or importing one. This lets the agent discover the boundary rule instead of running into it.

Done when: <packages-root>/README.md exists and discourages barrels, and the repo's CLAUDE.md/AGENTS.md links to it.

Notes

  • In the config, $1 back-references (dependency-cruiser group matching) let a package access its own internals while blocking outsiders; do not expand them into one rule per package.
  • Public/private is determined by depth : package root files are entry points, and everything in subfolders is private. The convention is lib/ and tests/, but the rule does not hardcode them; adding a folder requires no config change, and adding an entry point just means adding a root file, no barrel needed.
  • Packages are flat: only one level of immediate children under the root. Package internals can be arbitrarily deep, but a package cannot contain another package.
  • Use .cjs(not .js), ensuring that even if the repo uses "type": "module", the config's module.exports still works.