HarperFast / HarperFast/skills
typescript-type-stripping: Document import type requirement and config.yaml variable syntax limitation
- Dominant language
- JavaScript
- Stars
- 3
- Forks
- 0
- Avg merge
- 3d 7h
- Merged PRs (30d)
- 8
Description
## 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:
```typescript
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.
Contributor guide
Assessment
This issue has not been assessed yet.