HarperFast / HarperFast/nextjs
Turbopack build can't resolve `import 'harper'` (Next 16); README recommends an import that breaks the build
- Dominant language
- TypeScript
- Stars
- 4
- Forks
- 2
- PR merge metrics
- No merged PRs in 30d
Description
## Summary
On Next.js 16, a top-level `import 'harper'` in server code fails the plugin's on-startup build with:
```
Error: Turbopack build failed with 1 errors:
Module not found: Can't resolve 'harper'
> import 'harper';
```
`withHarper()` externalizes `harper` for the **webpack** path and adds it to `serverExternalPackages`, but adds nothing for Turbopack (`src/withHarper.cts` L31–43; the comment at L24–26 notes Turbopack support is "currently proving difficult"). Since v16 defaults to Turbopack (`src/plugin.ts` L196–197), the build throws, and the plugin logs the error and `return`s **without serving** (`src/plugin.ts` L254–264) — so the app boots but every route 404s. It's a silent failure that's especially confusing on remote/Studio deploys (the component "deploys" but serves nothing).
## Interaction with #37
Forcing `bundler: webpack` gets past module resolution, but then hits #37: the same top-level `import 'harper'` opens the database during Next's build-time page-data collection → `IO error: While lock file: .../database/data/LOCK: Resource temporarily unavailable`. So a top-level `import 'harper'` breaks the build under **both** bundlers, for two different reasons (resolution under Turbopack, DB lock under webpack).
## The docs recommend the import that breaks it
README step 5 (~L63–75) tells users to `import 'harper'` in server-side code. That guidance triggers this on v16. Notably, the plugin's **own** `next-16` fixture doesn't import `harper` in Next code — it keeps Harper access in a `jsResource` (`fixtures/next-16/greeting.js`) and the Next pages use the injected `tables` global / `process.env`. Using the injected `tables` global directly (no top-level import) builds and serves fine on Turbopack, and it's what the `_next-14-old` fixture does in a Next module.
## Minimal repro
1. A Next 16 app using `@harperfast/nextjs` (e.g. `npx create-harper my-app --template nextjs`).
2. Add `import 'harper';` at the top of a server action/component (as the README shows).
3. `harper run .` → Turbopack build fails (`Can't resolve 'harper'`) → all routes 404.
4. Remove the import and use the injected `tables` global instead → builds & serves fine.
Versions: `@harperfast/nextjs` 2.2.1, `next` 16.2.11, `harper` 5.1.22, Node 24.
## Suggestions
1. Add Turbopack externalization for `harper`/`harper-pro` in `withHarper()` (e.g. `turbopack.resolveAlias` / external config) so `import 'harper'` resolves under the v16 default bundler — or, if that's blocked upstream, default the plugin build to `webpack` on v16 with a warning.
2. Update the README to recommend the injected `tables` global **without** a top-level `import 'harper'` (or document that any such import must be lazy/request-time to avoid #37). The current guidance produces broken builds on v16.
3. Consider surfacing a failed startup build more loudly than a logged error + silent 404s (e.g. serve a 500 with the build error), so the failure mode is obvious on remote deploys.
Happy to open a PR for the docs change and/or test a Turbopack externalization approach if useful.
Contributor guide
Research direction
Start with src/withHarper.cts and src/plugin.ts, then compare the README guidance around steps 5 and the next-16 and _next-14-old fixtures. Reproduce the Next 16 Turbopack build with the documented import and without it, and inspect the existing webpack and startup-error paths. Done means the documented server usage has an agreed working path, the relevant build behavior is covered or verified, and failures are no longer silently served as 404s.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- next.js, typescript
- Domain
- build-system, web-dev
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100