typescript-type-stripping: Document import type requirement and config.yaml variable syntax limitation

[jcohen-hdb]

Context

We built a Harper app entirely in TypeScript (~3,000 lines across resource, domain, and connector layers). The type-stripping rule correctly documents .ts extensions in imports, but misses two patterns that caused build failures for us.

Caveat: These may be Node.js type-stripping limitations rather than Harper-specific, but since Harper's skill is the entry point for TS development, it should either document them or link to the relevant Node.js docs.

---

1. import type { X } is required for type-only imports

What we hit: We wrote import { MyConfig } from './config/env.ts' where MyConfig is only used as a type annotation. Harper's type stripping failed because it tried to resolve a runtime import for something that doesn't exist at runtime.

What we did: Changed all type-only imports to use the import type syntax:

import type { MyConfig } from './config/env.ts';

What the skill should do: Add this next to the existing .ts extension rule. It's the same class of "thing that works in tsc but fails under type stripping" and developers will hit it immediately.

---

2. config.yaml does not support ${VAR:-default} shell syntax

What we hit: We tried using ${SYNC_INTERVAL:-4} in config.yaml for a default value. Harper didn't expand it and passed the literal string.

What we did: Removed all :-default syntax and handled defaults in our TypeScript config loader instead.

What the skill should do: Mention that config.yaml supports ${VAR} for env var substitution but does NOT support shell-style defaults (${VAR:-fallback}). This is easy to assume coming from Docker/shell environments.

[kriszyp]

Mention that config.yaml supports ${VAR} for env var substitution

I didn't think we supported env var substitution at all?

[jcohen-hdb]

Good catch — you might be right. Looking at our actual config.yaml, we don't use ${VAR} substitution anywhere. We use loadEnv: files: '.env' and then read everything from process.env in our TypeScript config loader.

What actually happened: early in development, Claude Code tried putting ${SYNC_INTERVAL:-4} in config.yaml and it didn't work. We assumed the :-default part was the problem and that ${VAR} alone would work, but we never actually tested that — we just moved everything to process.env reads in code and moved on.

So the skill guidance here should probably be: "Don't use env var substitution in config.yaml — use loadEnv to load your .env file, then read values from process.env in your resource/application code." If that's accurate?

---

This response was drafted and posted by Claude Code on behalf of Jake.