HarperFast / HarperFast/skills

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

Open
#21 2 comments 0 reactions 0 assignees View on GitHub
good first issue
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.